Get started with Flow

Last updated: November 13, 2024

Set up your client-side and server-side Flow integrations to 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 available payment methods to the customer. If the customer's chosen payment method requires additional customer data, Flow captures this from them.
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.

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.

To create a new PaymentSession, call the following endpoint with your secret key:

post

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

For the full API specification, see the API reference.


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


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

The payment session response determines which payment methods can be displayed to the customer. The response is determined by:

the customer's device
the customer's region
the payment methods that have been activated for your account – to enable additional payment methods on your account, contact your Account Manager or [email protected]

Some payment methods may require you to provide additional fields or specific values.

Information

Apple Pay and Google Pay have additional requirements you must adhere to.

Payment method	Field requirements
Card payments	No additional requirements.
Apple Pay	Apple Pay is processed as a card transaction `currency` and `billing.address.country` must be supported by Apple Pay
Google Pay	Google Pay is processed as a card transaction `currency` and `billing.address.country` must be supported by Google Pay
PayPal	`items[]` must be provided `currency` and `billing.address.country` must be supported by PayPal
Alipay CN	`amount` must be provided `customer.email` or `customer.id` must be provided `payment_type` must be set to `Regular` or `Recurring` `items[]` must be provided for each `item` in `items[]`, the following must be provided: `name` `quantity` `reference` `unit_price` `billing.address.country` value must be `CN`, for China `currency` value must be one of: `CNY` `HKD` `SGD`
Alipay HK	`amount` must be provided `customer.email` or `customer.id` must be provided `payment_type` must be set to `Regular` or `Recurring` `items[]` must be provided for each `item` in `items[]`, the following must be provided: `name` `quantity` `reference` `unit_price` `billing.address.country` value must be `HK`, for Hong Kong `currency` value must be one of: `HKD` `SGD`
Bancontact	`billing.address.country` value must be `BE`, for Belgium `currency` value must be `EUR`
Benefit Payment Gateway	`billing.address.country` value must be `BH`, for Bahrain `currency` value must be `BHD` `reference` must be provided
Dana	`amount` must be provided `customer.email` or `customer.id` must be provided `payment_type` must be set to `Regular` or `Recurring` `items[]` must be provided for each `item` in `items[]`, the following must be provided: `name` `quantity` `reference` `unit_price` `billing.address.country` value must be `ID`, for Indonesia `currency` value must be one of: `IDR` `HKD` `SGD`
EPS	`billing.address.country` value must be `AT`, for Austria `currency` value must be `EUR`
GCash	`amount` must be provided `customer.email` or `customer.id` must be provided `payment_type` must be set to `Regular` or `Recurring` `items[]` must be provided for each `item` in `items[]`, the following must be provided: `name` `quantity` `reference` `unit_price` `billing.address.country` value must be `PH`, for the Philippines `currency` value must be one of: `PHP` `HKD` `SGD`
iDEAL	`billing.address.country` value must be `NL`, for Netherlands `currency` value must be `EUR`
Kakao Pay	`amount` must be provided `customer.email` or `customer.id` must be provided `payment_type` must be set to `Regular` or `Recurring` `items[]` must be provided for each `item` in `items[]`, the following must be provided: `name` `quantity` `reference` `unit_price` `billing.address.country` value must be `KR`, for South Korea `currency` value must be one of: `KRW` `HKD` `SGD`
Klarna	`items[]` and `items.total_amount` must be provided `customer.name` must be provided and must contain a first and last name at a minimum `billing.address.country` value must be one of: `AT`, for Austria `AU`, for Australia `BE`, for Belgium `CH`, for Switzerland `CZ`, for Czech Republic `DE`, for Germany `DK`, for Denmark `ES`, for Spain `FR`, for France `FI`, for Finland `GB`, for United Kingdom `GR`, for Greece `IE`, for Ireland `IT`, for Italy `NL`, for Netherlands `NO`, for Norway `PL`, for Poland `PT`, for Portugal `SE`, for Sweden `currency` value must be one of: `AUD` `CHF` `CZK` `DKK` `EUR` `GBP` `NOK` `PLN` `SEK`
KNET	`billing.address.country` value must be `KW`, for Kuwait `currency` value must be `KWD`
Multibanco	`billing.address.country` value must be `PT`, for Portugal `currency` value must be `EUR`
Przelewy24	`billing.address.country` value must be `PL`, for Poland `currency` value must be `EUR` or `PLN`
QPay	`billing.address.country` value must be `QA`, for Qatar `currency` value must be `QAR` `description` must be provided
stc pay	`billing.address.country` must be set to `SA` `currency` value must be `SAR` `reference` must be provided
Touch 'n Go	`amount` must be provided `customer.email` or `customer.id` must be provided `payment_type` must be set to `Regular` or `Recurring` `items[]` must be provided for each `item` in `items[]`, the following must be provided: `name` `quantity` `reference` `unit_price` `billing.address.country` value must be `MY`, for Malaysia `currency` value must be one of: `MYR` `HKD` `SGD`
TrueMoney	`amount` must be provided `customer.email` or `customer.id` must be provided `payment_type` must be set to `Regular` or `Recurring` `items[]` must be provided for each `item` in `items[]`, the following must be provided: `name` `quantity` `reference` `unit_price` `billing.address.country` value must be `TH`, for Thailand `currency` value must be one of: `THB` `HKD` `SGD`
Venmo	`billing.address.country` must be `US`, for the United States `currency` value must be `USD`

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" />

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.

Download sample files (.zip)

If you use the template, you must set up your own server.


1<!doctype html>
2<html lang="en">
3    <head>
4        <meta charset="utf-8" />
5        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
6        <title>Checkout Web Components: Flow Component</title>
7        <link rel="stylesheet" href="./style.css" />
8    </head>
9
10    <body>
11        <div id="successToast" class="toast success">
12            <span>The payment was successful</span>
13        </div>
14
15        <div id="failedToast" class="toast failed">
16            <span>The payment failed, try again</span>
17        </div>
18
19        <form>
20            <div class="container">
21                <div id="flow-container"></div>
22            </div>
23            <span id="error-message"></span>
24            <span id="successful-payment-message"></span>
25        </form>
26
27        <script src="https://checkout-web-components.checkout.com/index.js"></script>
28
29        <script src="app.js"></script>
30    </body>
31</html>


1/* Normalize */
2button,hr,input{overflow:visible}progress,sub,sup{vertical-align:baseline}[type=checkbox],[type=radio],legend{box-sizing:border-box;padding:0}html{line-height:1.15;-webkit-text-size-adjust:100%}body{margin:0}details,main{display:block}h1{font-size:2em;margin:.67em 0}hr{box-sizing:content-box;height:0}code,kbd,pre,samp{font-family:monospace,monospace;font-size:1em}a{background-color:transparent}abbr[title]{border-bottom:none;text-decoration:underline;text-decoration:underline dotted}b,strong{font-weight:bolder}small{font-size:80%}sub,sup{font-size:75%;line-height:0;position:relative}sub{bottom:-.25em}sup{top:-.5em}img{border-style:none}button,input,optgroup,select,textarea{font-family:inherit;font-size:100%;line-height:1.15;margin:0}button,select{text-transform:none}[type=button],[type=reset],[type=submit],button{-webkit-appearance:button}[type=button]::-moz-focus-inner,[type=reset]::-moz-focus-inner,[type=submit]::-moz-focus-inner,button::-moz-focus-inner{border-style:none;padding:0}[type=button]:-moz-focusring,[type=reset]:-moz-focusring,[type=submit]:-moz-focusring,button:-moz-focusring{outline:ButtonText dotted 1px}fieldset{padding:.35em .75em .625em}legend{color:inherit;display:table;max-width:100%;white-space:normal}textarea{overflow:auto}[type=number]::-webkit-inner-spin-button,[type=number]::-webkit-outer-spin-button{height:auto}[type=search]{-webkit-appearance:textfield;outline-offset:-2px}[type=search]::-webkit-search-decoration{-webkit-appearance:none}::-webkit-file-upload-button{-webkit-appearance:button;font:inherit}summary{display:list-item}[hidden],template{display:none}
3
4/* Styling */
5*,
6*::before,
7*::after {
8  box-sizing: border-box;
9}
10
11html {
12  padding: 1rem;
13  background-color: #fff;
14  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen,
15    Ubuntu, Cantarell, "Open Sans", "Helvetica Neue", sans-serif;
16}
17
18form {
19  max-width: 31.5rem;
20  margin: 0 auto;
21}
22
23.toast {
24  visibility: hidden;
25  min-width: 250px;
26  margin-left: -125px;
27  color: #fff;
28  text-align: center;
29  border-radius: 2px;
30  padding: 16px;
31  position: fixed;
32  z-index: 1;
33  left: 50%;
34  bottom: 0;
35  font-family: monospace;
36  display: inline-flex;
37  line-height: 12px;
38  opacity: 0;
39}
40
41.toast.success {
42  background-color: mediumseagreen;
43}
44
45.toast.failed {
46  background-color: indianred;
47}
48
49.toast span {
50  margin-left: 12px;
51  margin-top: 2px;
52}
53
54.toast.show {
55  visibility: visible;
56  -webkit-animation: fadein 5s;
57  animation: fadein 5s;
58}
59
60@keyframes fadein {
61  0% {
62    bottom: 0;
63    opacity: 0;
64  }
65  16.667% {
66    bottom: 30px;
67    opacity: 1;
68  }
69  83.333% {
70    bottom: 30px;
71    opacity: 1;
72  }
73  100% {
74    bottom: 0;
75    opacity: 0;
76  }
77}


1/* global CheckoutWebComponents */
2(async () => {
3  // Insert your public key here
4  const PUBLIC_KEY = "{your_public_key}";
5
6  const response = await fetch("/create-payment-sessions", { method: "POST" }); // Order
7  const paymentSession = await response.json();
8
9  if (!response.ok) {
10    console.error("Error creating payment session", paymentSession);
11    return;
12  }
13
14  const checkout = await CheckoutWebComponents({
15    publicKey: PUBLIC_KEY,
16    environment: "sandbox",
17    locale: "en-GB",
18    paymentSession,
19    onReady: () => {
20      console.log("onReady");
21    },
22    onPaymentCompleted: (_component, paymentResponse) => {
23      console.log("Create Payment with PaymentId: ", paymentResponse.id);
24    },
25    onChange: (component) => {
26      console.log(
27        `onChange() -> isValid: "${component.isValid()}" for "${
28          component.type
29        }"`,
30      );
31    },
32    onError: (component, error) => {
33      console.log("onError", error, "Component", component.type);
34    },
35  });
36
37  const flowComponent = checkout.create("flow");
38
39  flowComponent.mount(document.getElementById("flow-container"));
40})();
41
42function triggerToast(id) {
43  var element = document.getElementById(id);
44  element.classList.add("show");
45
46  setTimeout(function () {
47    element.classList.remove("show");
48  }, 5000);
49}
50
51const urlParams = new URLSearchParams(window.location.search);
52const paymentStatus = urlParams.get("status");
53const paymentId = urlParams.get("cko-payment-id");
54
55if (paymentStatus === "succeeded") {
56  triggerToast("successToast");
57}
58
59if (paymentStatus === "failed") {
60  triggerToast("failedToast");
61}
62
63if (paymentId) {
64  console.log("Create Payment with PaymentId: ", paymentId);
65}

The client side will initialize 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 will override 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 will be 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.

You can use CheckoutWebComponents to create a flow object. flow contains a dynamic list of all of the payment methods available for the payment session you passed into CheckoutWebComponents.


1const flowComponent = checkout.create('flow');

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


1flowComponent.mount('#flow-container');


1const flowElement = document.getElementById('flow-container');
2flowComponent.mount(flowElement);

Note

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

You can use Flow to handle payment methods that require a redirect (asynchronous payments) and those that do not (synchronous payments).

Depending on the payment outcome, some payment methods and 3D Secure authentication flows will redirect the customer to a success or failure URL on your website.

A webhook will be sent to your server notifying you of changes to the payment's status. Wait for the webhook callback before you trigger your order fulfillment process.

For payments submitted with Flow, the PaymentSession ID is returned in the webhook payload's data.metadata.cko_payment_session_id field.

Optionally, you can retrieve the payment result from your server by performing a Get payment details request using the cko-payment-id in the URL. For example:


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

Payment methods that do not require a redirect trigger an onPaymentCompleted event when the payment is successfully completed. You can use this to notify the customer of the payment status.

A webhook will be sent to your server notifying you of changes to the payment's status. Wait for the webhook callback before you trigger your order fulfillment process.


1const checkout = await CheckoutWebComponents({
2  paymentSession,
3  publicKey,
4  onPaymentCompleted: async (_self, paymentResponse) => {
5    // Handle synchronous payments
6    await handlePayment(paymentResponse.id);
7  },
8});

Optionally, you can retrieve the payment result from your server, perform a Get payment details request using the cko-payment-id in the URL. For example:


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

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

Information

Ensure that you test each payment method that you plan to offer to your customers.

You can check the status of a payment from the Payments > Processing > All payments screen in the Dashboard.

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

Get started with Flow

Flow payment process

Before you start

Step 1: Create a new Payment Session
Server side

Request example

Response example

Payment method field requirements

Information

Step 2: Initialize and mount Flow
Client side

Download project template (optional)

Configuration options

Note

Step 3: Handle the payment response
Client side

Asynchronous payments

Synchronous payments

Test the integration

Information

Content Security Policy

Next steps

Customize your Flow integration

Flow library reference

Set up your webhook receiver

Flow payment process

Before you start

Step 1: Create a new Payment Session Server side

Request example

Response example

Payment method field requirements

Information

Step 2: Initialize and mount Flow Client side

Download project template (optional)

Configuration options

Note

Step 3: Handle the payment response Client side

Asynchronous payments

Synchronous payments

Test the integration

Information

Content Security Policy

Next steps

Customize your Flow integration

Flow library reference

Set up your webhook receiver

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