Benefit Payment Gateway for web

Last updated: March 19, 2025

Accept Benefit Payment Gateway payments on your website with Flow, our pre-built, customizable payment user interface.

Flow enables you to accept payments using Checkout.com's global network of payment methods with a single integration.

Set up your client-side and server-side configuration to integrate with Checkout.com's payment gateway and enable payments on your website.

The customer lands on the checkout page.
You perform a server-side request to create a payment session.
You use the payment session data on the client-side to mount Flow.
Flow displays the Benefit Payment Gateway payment method to the customer.
When the customer clicks the Pay option, Flow performs a payment request and handles any additional actions. For example, additional actions required for 3D Secure (3DS) authentication, or a third-party payment page redirect.
You receive a webhook notifying you of the payment status.

Make sure you have a test account with Checkout.com.

Create a public key and a secret key from the Dashboard, with the following key scopes:

Public key – payment-sessions:pay and vault-tokenization
Secret key – payment-sessions

To receive notifications for the payment events that may be triggered throughout the steps, configure your webhook receiver.

If you have a Content Security Policy (CSP) on your website, Checkout.com requires the following directives:


1connect-src, https://*.checkout.com
2frame-src, https://*.checkout.com
3script-src, https://*.checkout.com
4img-src, https://*.checkout.com

When the customer is ready to pay, you must send a server-side request to securely create a PaymentSession object. The PaymentSession contains the information required to handle all steps of the payment flow.

In your request:

Set billing.address.country to BH
Set currency to BHD
Provide a reference

Information

For the full API specification, see the API reference.

post

https://api.checkout.com/payment-sessions


1{
2  "amount": 1000,
3  "currency": "EUR",
4  "reference": "ORD-123A",
5  "display_name": "Online shop",
6  "billing": {
7    "address": {
8      "country": "BE"
9    }
10  },
11  "customer": {
12    "name": "Jia Tsang",
13    "email": "[email protected]"
14  },
15  "success_url": "https://example.com/payments/success",
16  "failure_url": "https://example.com/payments/failure"
17}


1{
2  "id": "ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ",
3  "payment_session_secret": "pss_9823241e-2cec-4c98-b23d-7b29ow4e2e34",
4  "payment_session_token": "YmFzZTY0:eyJpZCI6InBzXzJVbjZJNmxScElBaUlFd1FJeXhXVm5WOUNxUSIsImFtb3VudCI6MTAwMCwibG9jYWxlIjoiZW4tR0IiLCJjdXJyZW5jeSI6IkdCUCIsInBheW1lbnRfbWV0aG9kcyI6W3sidHlwZSI6ImNhcmQiLCJjYXJkX3NjaGVtZXMiOlsiVmlzYSIsIk1hc3RlcmNhcmQiLCJBbWV4Il19XSwicmlzayI6eyJlbmFibGVkIjp0cnVlfSwiX2xpbmtzIjp7InNlbGYiOnsiaHJlZiI6Imh0dHBzOi8vYXBpLnNhbmRib3guY2hlY2tvdXQuY29tL3BheW1lbnQtc2Vzc2lvbnMvcHNfMlVuNkk2bFJwSUFpSUV3UUl5eFdWblY5Q3FRIn19fQ==",
5  "_links": {
6    "self": {
7      "href": "https://api.sandbox.checkout.com/payment-sessions/ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ"
8    }
9  }
10}

You can install the @checkout.com/checkout-web-components package via npm:


1npm install @checkout.com/checkout-web-components --save

Alternatively, you can load the package directly via a script:


1<script src="https://checkout-web-components.checkout.com/index.js" />

Note

To remain PCI compliant, you should only ever load the script directly from https://checkout-web-components.checkout.com. Do not download or host the script yourself, or include it in a bundle.

The client side initializes an instance of CheckoutWebComponents with configuration information and the payment session data retrieved in step 1.


1// Insert your public key here
2const publicKey = '{YOUR_PUBLIC_KEY}';
3
4const checkout = await CheckoutWebComponents({
5  paymentSession,
6  publicKey,
7  environment: 'sandbox',
8});

You can use the following configuration options to instantiate an instance of CheckoutWebComponents:

JavaScript key	Description
`appearance`	Allows you to customize the visual appearance of the `CheckoutWebComponents` elements. To see the customization options, refer to the Appearance options documentation.
`componentOptions`	Allows you to customize the options for the individual Flow components. For example, you can change the position of the cardholder field in the `card` component. To see the customization options, refer to the component options documentation.
`environment`	Sets the environment that the library should point, and send requests to. Use `sandbox` for your test environment, or `production` for your live environment.
`locale`	Sets the customer's locale. Explicitly setting this value overrides the `locale` returned by the `PaymentSession`. To see a list of supported languages, refer to the localization documentation.
`paymentSession`	The response from the `PaymentSession`. This field is required.
`publicKey`	Your public API key. Your key is prefixed with `pk_`. This field is required.
`translations`	Allows you to provide custom text translations for natively supported languages, or add custom text for locales and languages not natively supported by Flow. To learn how to add translations, refer to the Add localization to your Flow integration documentation.

Use CheckoutWebComponents to create a benefit object.


1const benefitComponent = checkout.create("benefit");

Mount Flow to the website using the mount() method. The method takes an Element selector or an Element as an argument. For example, #flow-container or document.getElementById(#flow-container), respectively.


1if (await benefitComponent.isAvailable()) {
2  benefitComponent.mount('#benefit-container');
3}


1const benefitElement = document.getElementById('benefit-container');
2
3if (await benefitComponent.isAvailable()) {
4  benefitComponent.mount(benefitElement);
5}

Note

Embedding Flow within an iframe or onto a Shadow DOM is not supported.

The customer is redirected to a success or failure URL on your website depending on the payment outcome and the result of any additional payment authentication. For example, 3DS authentication.

You can retrieve the payment result using the Get payment details endpoint. Use the cko-payment-id value from the success or failure URL as the {id} path parameter. For example:


1https://example.com/success?cko-payment-id=pay_mbabizu24mvu3mela5njyhpasd

If you've set up your webhook receiver, we send a Gateway webhook to your server. The webhook we send depends on the status of the payment. Wait for the webhook callback before you trigger your order fulfillment process.

The PaymentSession ID is returned in the webhook payload's data.metadata.cko_payment_session_id field.

Use our test cards to simulate different payment flows, to ensure your integration is set up correctly and behaving as expected.

To check the status of a payment:

Sign in to the Dashboard.
Go to Payments > Processing > All payments.
Select the test payment to view its details.

Customize your Flow integration

Learn how to customize your Flow integration.

Flow library reference

See the configuration options and error handling steps for Flow.

Benefit Payment Gateway for web

Flow payment process

Before you start

Content Security Policy

Step 1: Create a new Payment Session
Server side

Information

Request example

Response example

Step 2: Initialize and mount Flow
Client side

Note

Configuration options

Note

Step 3: Handle the payment response
Client side

Test the integration

Next steps

Customize your Flow integration

Flow library reference

Flow payment process

Before you start

Content Security Policy

Step 1: Create a new Payment Session Server side

Information

Request example

Response example

Step 2: Initialize and mount Flow Client side

Note

Configuration options

Note

Step 3: Handle the payment response Client side

Test the integration

Next steps

Customize your Flow integration

Flow library reference

Step 1: Create a new Payment Session
Server side

Step 2: Initialize and mount Flow
Client side

Step 3: Handle the payment response
Client side