Get started with Flow

Last updated: October 15, 2025

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

Information

If you only want to accept a specific payment method with Flow, see the payment method's Flow documentation.

The customer lands on your 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 selects Pay, 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.
If the customer selects the option to save their card for faster checkout, we create a Remember Me profile for them and save their card to it. The customer can reuse their saved cards in future transactions.
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 in the Dashboard, with the following key scopes:

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

To receive webhooks for the payment events that may be raised throughout the steps, set up your webhook receiver.

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

Information

Some payment methods require specific fields. For more information, see each payment method's Flow documentation.

To create a new PaymentSession, call the Request a Payment Session endpoint with your secret key.

Information

You can enable Remember Me to allow customers to save their card details during checkout. The next time the customer shops at any merchant that has Remember Me enabled, we display their saved card details.

post

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


1{
2  "amount": 1000,
3  "currency": "GBP",
4  "reference": "ORD-123A",
5  "display_name": "Online shop",
6  "billing": {
7    "address": {
8      "country": "GB"
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}

The payment session response determines which payment methods can be displayed to the customer, depending on the following:

The customer's device
The customer's region
The payment methods activated for your account

To request to activate additional payment methods, contact your account manager or request support.

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, 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 initializes an instance of CheckoutWebComponents with configuration information and the payment session data retrieved earlier.


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`	Enables you to customize the visual appearance of the `CheckoutWebComponents` elements. For customization options, see Appearance options.
`componentOptions`	Enables 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. For customization options, see Component options.
`environment`	Sets the environment that the library should point to and send requests to. This can be one of: `production` `sandbox`
`locale`	Sets the customer's locale. Explicitly setting this value overrides the `locale` returned by the `PaymentSession`. For supported languages, see Add localization to your Flow integration.
`paymentSession` required	The response from the `PaymentSession`.
`publicKey` required	Your public API key, prefixed with `pk_`.
`translations`	Enables 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, see Add localization to your Flow integration.

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


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

Mount Flow to your 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

You cannot embed Flow within an iframe or onto a Shadow DOM.

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 redirect the customer to a success or failure URL on your website.

Checkout.com sends a webhook to your server notifying you of changes to the payment's status. Wait for the webhook callback before you initiate 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. Call the Get payment details endpoint and provide the cko-payment-id from the URL as the {id} path parameter. For example:


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

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


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

The event returns the payment ID in the paymentResponse.id field. To retrieve the payment result from your server, call the Get payment details endpoint and provide the payment ID as the {id} path parameter.

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

Information

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

You can check the status of a payment from the Payments > Processing > All payments page 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

Information

Flow payment process

Before you begin

Create a new Payment Session
Server side

Information

Information

Request example

Response example

Initialize and mount Flow
Client side

Note

Download project template (optional)

Configuration options

Note

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

Information

Flow payment process

Before you begin

Create a new Payment Session Server side

Information

Information

Request example

Response example

Initialize and mount Flow Client side

Note

Download project template (optional)

Configuration options

Note

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

Create a new Payment Session
Server side

Initialize and mount Flow
Client side

Handle the payment response
Client side