Pay.com Universal Component is a fully customizable UI component for the web that accepts all supported payment methods, validates input, and handles errors. Use it in your web app’s frontend.

Create a payment session

A payment session is the starting point for integrating payments at Pay.com. You can attach any data associated with the order to your payment session which will later will be used as part of the payment authorization. Creating a payment session provides you with a client secret, a temporary token used to initialize the Universal Component.

Generate an API key

Requests to our API are authenticated using an API key in the x-paycom-api-key header. Create an API key by visiting the API keys tab on the developers section of the Pay.com Dashboard.

Make a payment session request

On your server, create a payment session with POST /v1/sessions/payment.

Make sure to pass at least the following data:

The body of a successful response contains a client_secret that you will use to initialize the Universal Component.

Here is how the payment session request to the Pay.com API should look like:

curl --location --request \
 POST 'https://api.pay.com.com/v1/sessions/payment' \
 --header 'x-paycom-api-key: <YOUR_API_KEY>' \
 --header 'Content-Type: application/json'
 --data '{
    "currency": "usd",
    "amount": 1000,
    "customer_reference_id": "927071e4-464c-4f5d-a079-4aa097f922ca"
 }'

# Here is a (heavily truncated) example response

{
  "id": "ps_217940156986951680",
  "resource": "payment_session",
  "amount": 1000,
  "currency": "usd",
  "client_secret": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "status": "open"
}

Install and initialize the SDK

With npm

Our Components SDK is available on npm under the name @paycom/js. This package includes TypeScript definitions.

# With yarn
yarn add @pay-com/js

# With npm
npm install --save @pay-com/js

import Pay from '@pay-com/js'

const pay = await Pay.com({
  identifier: '{merchant_id}'
})

For production, please include the live: true boolean when calling the initialisation of the Pay.com SDK

import Pay from '@pay-com/js'

const pay = await Pay.com({
  identifier: '{merchant_id}',
  live: true
})

With our CDN

Include the Pay.com script and page where you want to render the Checkout. It is recommend to load the SDK to the page as early as possible as it asynchronously pre-loads the relevant resources to the page for immediate checkout loading times.

<script type="text/javascript" src="https://js.pay.com/v1"></script>

The script will add the Pay object to the global scope and will allow initialization with the unique merchant ID.

const { Pay } = window

const pay = Pay.com({
  identifier: '{merchant_id}'
})

Show the Universal Component

Use the generated client secret on the client-side to create a checkout instance by calling the checkout function.

const checkout = pay.checkout({
  clientSecret: '{client_secret}',
  onSuccess: (payment) => {
    console.log('Checkout Completed!', payment)
  },
  onFailure: (error) => {
    console.log('Checkout Failed!', error)
  },
})

You now have a checkout object with which you can render a payment form, validate it, and subscribe to events.

Next, to show the Universal Component, call the universal function on the checkout object passing a pass a selector to your container.

checkout.universal({
  container: '#paycom_checkout'
})

Some payment methods require redirecting to another web page in order to capture payment details., The universal component automatically renders that web page in a popup window in order to maintain the current context.

Handle successful payments

Listen to callback

On the client-side, listen to the onSuccess callback to be notified when the payment has been successfully completed. Use it to show an order confirmation screen, or to fulfill the order.

Handle webhooks

To receive updates about the status of your payments you’ll need to listen to webhooks. This is particularly useful for updating an order or any other data stored server-side. Head to the Developers section of the Dashboard to setup and test a webhook for payment_session.completed event.

If you are not yet ready to receive webhooks, you can use https://webhook.site to test your implementation.

Handle failed payments

Any errors, cancelled payment interactions or failed payments will trigger the onFailure callback.

Use your own submit button and Promise based flow (Advanced)

If you wish to render the fields without a submission button for more control, the submitButton: false option can be passed to the universal function while showing the component,

checkout.universal({
  container: '#paycom_checkout',
  toggles: {
    submitButton: false
  }
})

Use the isValid and submit Promises to validate the contents and to trigger submission.

  const { valid, invalidFields } = await checkout.validate()

  if (valid) {
    try {
      await checkout.submit()
      // Show an order confirmation screen, or to fulfill the order.
    } catch (e) {
      // Authorization failed, error message available via e.message.
    }
  } else {
    // Handle validation failure logic.
  }