Upgrade from Frames for web

Last updated: November 5, 2025

Follow this guide to upgrade your Frames for web integration to Flow.

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

Configure your webhook server to receive notifications for payment events.

To prepare for the upgrade to Flow, remove all Frames code from your client-side and server-side integrations.

If you included the Frames JavaScript library in your HTML, remove the Frames <script> tag:


1<script src="https://cdn.checkout.com/js/framesv2.min.js"></script>

Remove any JavaScript code where you initialize Frames. For example:


1Frames.init("PUBLIC_KEY");
2
3Frames.addEventHandler(Frames.Events.CARD_VALIDATION_CHANGED, onValidationChanged);
4Frames.addEventHandler(Frames.Events.CARD_TOKENIZED, onCardTokenized);

Delete any HTML related to Frames. For example, the card input form:


1<form id="payment-form">
2  <div id="card-frame"></div>
3  <button id="pay-button">Pay</button>
4</form>

Remove all server-side API calls to the following endpoints:

post

https://api.checkout.com/payments

Update your server to create a PaymentSession for the Flow integration.

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}

Include the Flow library in the project:


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

Configure Flow with your public key and the payment session data returned from the server:


1const publicKey = 'PUBLIC_KEY';
2
3const checkout = await CheckoutWebComponents({
4  paymentSession,
5  publicKey,
6  environment: 'sandbox', // Use 'production' for Production environment
7});

Add the Flow component to a container in your HTML:


1<div id="flow-container"></div>

In your JavaScript, create and mount the component:


1const flowComponent = checkout.create('flow');
2flowComponent.mount('#flow-container');

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 (3DS) authentication flows redirect the customer to a success or failure URL on your website.

We send a webhook notifying you of changes to the payment's status. Wait for the webhook callback before you start 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 initiate an onPaymentCompleted event when the payment is successfully completed. You can use this to notify the customer of the payment's status.

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


1const checkout = await CheckoutWebComponents({
2  paymentSession,
3  publicKey,
4  onPaymentCompleted: async (_self, paymentResponse) => {
5    // Handle synchronous payment completion
6    console.log('Payment successful', paymentResponse);
7  },
8});

Flow sends real-time card metadata events, which you can integrate with third-party systems to determine how to handle payment requests.

You can use these events to customize the payment session if you have more complex processes. For example, you can conduct a pre-payment risk check based on a card's issuing country and then decide to proceed with 3DS authentication or cancel the payment.

Information

For more information, see Customize your payment process.

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

Information

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

To check the status of a payment:

Sign in to the Dashboard.
Go to Payments > Processing > All payments.

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;

Upgrade from Frames for web

Before you begin

Remove existing Frames code

Remove Frames library
Client side

Remove Frames initialization
Client side

Remove Frames form
Client side

Remove payment logic
Server side

Create a Flow Payment Session
Server side

Request example

Response example

Initialize and mount Flow
Client side

Add the Flow library

Initialize Flow

Mount Flow

Handle payment responses

Asynchronous payments

Synchronous payments

Customize the payment flow logic

Information

Test the Flow integration

Information

Adjust Content Security Policy

Next steps

Customize your Flow integration

Flow library reference

Tokenize credentials

Before you begin

Remove existing Frames code

Remove Frames library Client side

Remove Frames initialization Client side

Remove Frames form Client side

Remove payment logic Server side

Create a Flow Payment Session Server side

Request example

Response example

Initialize and mount Flow Client side

Add the Flow library

Initialize Flow

Mount Flow

Handle payment responses

Asynchronous payments

Synchronous payments

Customize the payment flow logic

Information

Test the Flow integration

Information

Adjust Content Security Policy

Next steps

Customize your Flow integration

Flow library reference

Tokenize credentials

Remove Frames library
Client side

Remove Frames initialization
Client side

Remove Frames form
Client side

Remove payment logic
Server side

Create a Flow Payment Session
Server side

Initialize and mount Flow
Client side