Collect payment details without an initial payment session

Last updated: July 7, 2025

To support advanced payment scenarios, you can render Flow components and collect payment details without an initial payment session. For example, if you need to create the session later after additional validations or user actions have taken place.

The customer lands on the checkout page.
You initialize and mount the individual Flow components for each payment method you want to display.
Flow displays the payment methods to the customer. If the customer's chosen payment method requires additional customer data, Flow captures this from them.
Optionally, you capture additional order details from the customer during checkout.
When the customer clicks the Pay option, you submit their chosen payment method.
You perform a server-side request to complete the checkout and include the payment details you received from Flow.
After you create the order on your server, you request a payment session.
You return the payment session response to the client side and use it to handle the submission callback. Flow handles any additional actions required – For example, a third-party payment page redirect.
If the customer selected 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.
The customer is redirected to the success or failure URL you specified in the payment session and 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.

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.

The client side initializes an instance of CheckoutWebComponents with configuration information.


1// Insert your public key here
2const publicKey = '{YOUR_PUBLIC_KEY}';
3
4// Handle payment submission with your server integration
5const handleSubmit = async (component, submitData) => {
6  const submitResponse = await performPaymentSubmission(submitData);
7  return submitResponse;
8};
9
10const checkout = await CheckoutWebComponents({
11  publicKey,
12  environment: 'sandbox',
13  handleSubmit,
14});

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.
`handleSubmit(component, submitData)`	Raised when you or the customer submit a component element. This enables you to receive payment details provided by the customer, which you can use to submit a server-side payment session request. You must provide this callback in the `CheckoutWebComponents` initialization.
`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.
`onChange(component)`	An event fired when a component changes after a customer interaction.
`onError(component, error)`	An event fired when an error occurs.
`onPaymentCompleted(component, paymentResponse)`	An event fired when the payment has been completed synchronously.
`onReady(component)`	An event fired when a component is initialized and ready for the customer to interact.
`onSubmit(component)`	An event fired when you or the customer trigger a component submission.
`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 an object for each payment method you want to display. For example:


1const alipayCnComponent = checkout.create('alipay_cn');
2const idealComponent = checkout.create('ideal');

For integrations without an initial payment session, you can create any of the following payment method components:

alipay_cn
alipay_hk
alma
bancontact
benefit
dana
eps
gcash
ideal
kakaopay
knet
multibanco
p24
qpay
tng
truemoney
sepa
mbway

Mount the payment components to the website using the mount() method. The method takes an Element selector or an Element as an argument. For example:


1if (await alipayCnComponent.isAvailable()) {
2  alipayCnComponent.mount('#alma-container');
3}
4
5if (await idealComponent.isAvailable()) {
6  idealComponent.mount('#alma-container');
7}


1const alipayCnElement = document.getElementById('alipaycn-container');
2const idealElement = document.getElementById('ideal-container');
3
4if (await alipayCnComponent.isAvailable()) {
5  alipayCnComponent.mount(alipayCnElement);
6}
7
8if (await idealComponent.isAvailable()) {
9  idealComponent.mount(idealElement);
10}

Note

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

When the customer finishes entering their order details and is ready to pay, call the submit() method using the payment method component that the customer selected.

The handleSubmit callback provides the captured payment details, which you can use in your server-side integration to submit the payment session request.


1// Handle payment submission
2submitButton.addEventListener('click', () => {
3  // Get the payment method selected by customer
4  const selectedPaymentMethod = getSelectedPaymentMethod();
5
6  // Trigger payment submission using the selected payment method component
7  switch (selectedPaymentMethod) {
8    case 'alipay_cn':
9      alipayCnComponent.submit();
10      break;
11    case 'ideal':
12      idealComponent.submit();
13      break;
14  }
15});

The data you receive from the handleSubmit callback contains a session_data property which you can use to send a server-side request to securely create a payment session.

Information

Some payment methods have specific field requirements. For more information, see each payment method's Flow documentation.

Call the Create and submit payment session endpoint:

post

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


1{
2  "session_data": "eyJ0eXBlIjoiYWxpcGF5X2NuIiwic2Vzc2lvbl9tZXRhZGF0YSI6eyJpbnRlcm5hbF9wbGF0Zm9ybSI6eyJuYW1lIjoiQ2hlY2tvdXRXZWJDb21wb25lbnRzIiwidmVyc2lvbiI6IjEuMTM4LjAifSwiZmVhdHVyZV9mbGFncyI6WyJhbmFseXRpY3Nfb2JzZXJ2YWJpbGl0eV9lbmFibGVkIiwiY2FyZF9maWVsZHNfZW5hYmxlZCIsImdldF93aXRoX3B1YmxpY19rZXlfZW5hYmxlZCIsImxvZ3Nfb2JzZXJ2YWJpbGl0eV9lbmFibGVkIiwicmlza19qc19lbmFibGVkIiwidXNlX25vbl9iaWNfaWRlYWxfaW50ZWdyYXRpb24iXSwiZXhwZXJpbWVudHMiOnt9fX0=",
3  "amount": 1000,
4  "currency": "HKD",
5  "billing": {
6    "address": {
7      "address_line1": "Customer Home",
8      "city": "Shanghai",
9      "country": "CN"
10    }
11  },
12  "success_url": "https://example.com/payments/success",
13  "failure_url": "https://example.com/payments/failure",
14  "reference": "ORD-123A"
15}


1{
2  "id": "pay_mbabizu24mvu3mela5njyhpit4",
3  "status": "Action Required",
4  "type": "alipay_cn",
5  "action": {
6    "type": "redirect",
7    "url": "https://third-party-provider.com/ui"
8  },
9  "payment_session_id": "ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ",
10  "payment_session_secret": "pss_9823241e-2cec-4c98-b23d-7b29ow4e2e34"
11}

When you receive the payment response, you must return it to the client side integration and use it when you return the handleSubmit callback.

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.

We send a webhook 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. Call the Get payment details endpoint and provide the cko-payment-id from the URL as the request's {id} path parameter. 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.


1const checkout = await CheckoutWebComponents({
2  publicKey,
3  environment: 'sandbox',
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.

For each payment method you intend to support, follow the testing steps and 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

Collect payment details without an initial payment session

Payment process

Before you start

Initialize and mount Flow
Client side

Configuration options

Initialize and mount the payment components
Client side

Note

Handle the payment submission
Client side

Submit the payment session request
Server side

Information

Request example

Response example

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

Payment process

Before you start

Initialize and mount Flow Client side

Configuration options

Initialize and mount the payment components Client side

Note

Handle the payment submission Client side

Submit the payment session request Server side

Information

Request example

Response example

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

Initialize and mount Flow
Client side

Initialize and mount the payment components
Client side

Handle the payment submission
Client side

Submit the payment session request
Server side

Handle the payment response
Client side