Get started

Last updated: October 15, 2025

Flow is Checkout.com's pre-built payment user interface, which you can embed in your website to accept payments from your customers. Flow manages the end-to-end payment experience, including:

  • Tokenizing sensitive payment details so they never reach your server
  • Displaying available payment methods
  • Capturing any additional customer data required
  • Handling 3D Secure (3DS) authentication and redirection to third-party payment pages

Information

Use the following card details in the interactive demo to perform a test payment:

  • Cardholder name: Jordan Smith
  • Card number: 4242 4242 4242 4242
  • Expiry date: 12/30
  • Security code: 100

  1. The customer lands on your checkout page.

  2. You perform a server-side request to create a Payment Session.

  3. You use the Payment Session data on the client side to mount Flow.

  4. 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.

  5. 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.

  6. You receive a webhook notifying you of the payment status.

Diagram of the payment process when using Flow, showing the communication between your site, your server, and the Checkout.com server.

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 webhooks for the payment events, configure your webhook server.

When the customer is ready to pay, 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.

Call the Request a Payment Session endpoint with your secret key.

Information

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

Information

Your base URL's {prefix} value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see API endpoints.

post

https://{prefix}.api.checkout.com/payment-sessions

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": "jia.tsang@example.com"
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://{prefix}.api.sandbox.checkout.com/payment-sessions/ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ"
7
    }
8
  }
9
}

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

  • The customer's device
  • The customer's region
  • The values you provided for specific fields in your request
  • The payment methods that are activated for your account

Information

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

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

1
npm 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>

The client side initializes an instance of CheckoutWebComponents with configuration information and the payment session data returned in the Request a Payment Session response.

1
// Insert your public key here
2
const publicKey = '{YOUR_PUBLIC_KEY}';
3


4
const 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 keyDescriptionRequired

publicKey

Your public API key, prefixed with pk_.

check

paymentSession

The response from the PaymentSession.

check

locale

Sets the customer's locale. Explicitly providing this value overrides the locale returned by the PaymentSession. For supported languages, see Localization options.

error

environment

Sets the environment that the library should point to and send requests to. This can be one of:

  • production
  • sandbox
error

translations

Enables you to provide custom text translations for a natively supported languages, or add custom text for locales and languages not natively supported by Flow. For how to add translations, see Add localization to your Flow integration.

error

appearance

Enables you to customize the visual appearance of the CheckoutWebComponents elements. For customization options, see Appearance options.

error

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

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

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

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

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).

Some payment methods and 3D Secure authentication flows redirect the customer to a success or failure URL on your website, depending on the outcome of the payment.

Checkout.com sends you a webhook notifying you of changes to the payment's status. Wait for the webhook before you start your order fulfillment process.

Optionally, you can retrieve the payment result from your server. Call the Get payment details endpoint, and provide the cko-payment-id as the {id} path parameter. For example:

1
https://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.

We send you a webhook notifying you of changes to the payment's status. Wait for the webhook before you start your order fulfillment process.

1
const 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, with a Get payment details request.

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

You can check the payment's status on the Payments page in the Dashboard.

Customize your Flow integration

Learn how to customize your Flow integration.

Add localization to your Flow integration

Learn how to add localization to your Flow integration.

Use 3D Secure to authenticate your payments

Require your customers to complete an additional verification step with the card issuer when paying – you can do this with 3D Secure.

Store payment details for faster checkout

Store and reuse payment information, so your customers don’t have to enter payment details every time.