Customize your payment process

Last updated: May 14, 2025

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, if you want to:

Conduct a pre-payment risk check with the card's details and decide whether to proceed with 3D Secure authentication or abort the payment.
Modify the payment amount based on additional checkout information, such as a promotional code or a shipping address that incurs additional delivery fees.

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 selects the Pay option, Flow provides additional data via the handleSubmit callback.
You perform a server-side request to submit a payment session payment using the additional data.
You return the payment response to Flow.
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 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.
You receive a webhook notifying you of the payment status.

Flow exposes the following callbacks that you can implement to customize your payment process:

onTokenized – Callback to receive card tokenization results.
onCardBinChanged – Callback to receive real-time card metadata updates.

Based on the results of these callbacks, you can update your payment flow logic. For example, to send the data to a third-party risk tool to conduct pre-payment risk checks.

After updating the logic, use the handleSubmit callback to submit a payment session with your server-side integration and customize the payment request.

Information

Follow the Get started with Flow guidelines to configure your integration, and apply the following changes to customize your payment process.

Mount Flow following these steps, depending on the callback event you want to inspect:

Use the CheckoutWebComponents instance to create a flow object.

Implement the onTokenized and handleSubmit callbacks:


1// Initialize a variable to store the outcome of the risk assessment 
2let cardRiskCheckResult;
3
4const onTokenized = async (self, tokenizeResult) => {
5  // Perform risk check with the tokenization result. For example, using an async function to 
6  // send the data to a third-party risk tool:
7  cardRiskCheckResult = await performRiskCheck(tokenizeResult);
8
9  // Return `{ continue: false }` to abort payment with the card
10  if (cardRiskCheckResult.result === 'abort') {
11    return {
12      continue: false,
13      errorMessage: 'This card is not supported',
14    };
15  }
16
17  // Otherwise return `{ continue: true }` to proceed with payment
18  return {
19    continue: true,
20  };
21};
22
23const handleSubmit = async (self, submitData) => {
24  // Provide the `submitData` to your server-side integration
25  // for payment submission
26  const submitResponse = await performPaymentSubmission(submitData, cardRiskCheckResult);
27
28  return submitResponse;
29};
30
31const flowComponent = checkout.create('flow', {
32  onTokenized,
33  handleSubmit,
34});

Implement the onCardBinChanged and handleSubmit callbacks:


1// Initialize a variable to store the outcome of the risk assessment 
2let cardRiskCheckResult;
3
4const onCardBinChanged = async (self, cardMetadata) => {
5  // Perform risk check with the card metadata updates. For example, using an async function to 
6  // send the data to a third-party risk tool:
7  cardRiskCheckResult = await performRiskCheck(cardMetadata);
8
9  // Return `{ continue: false }` to abort payment with the card
10  if (cardRiskCheckResult.result === 'abort') {
11    return {
12      continue: false,
13      errorMessage: 'This card is not supported',
14    };
15  }
16
17  // Otherwise return `{ continue: true }` to proceed with payment
18  return {
19    continue: true,
20  };
21};
22
23const handleSubmit = async (self, submitData) => {
24  // Provide the `submitData` to your server-side integration
25  // for payment submission
26  const submitResponse = await performPaymentSubmission(submitData, cardRiskCheckResult);
27
28  return submitResponse;
29};
30
31const flowComponent = checkout.create('flow', {
32  onCardBinChanged,
33  handleSubmit,
34});

Mount the flow component:


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

Send a server-side request with a PaymentSession object, using the data from the handleSubmit callback, and return the unmodified response as the handleSubmit callback response.

You can modify any of the following fields:

amount
items
reference
3ds

To submit a PaymentSession payment request, call the Submit a payment session endpoint with your secret key and the PaymentSession ID:

post

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


1{
2  "session_data": "{SESSION_DATA_FROM_FLOW}",
3  "3ds": {
4    "enabled": true
5  }
6}


1{
2  "id": "pay_f2ws3hn4ijquzbytp3v5lsfxge",
3  "status": "Action Required",
4  "type": "card",
5  "action": {
6    "type": "3ds",
7    "url": "http://3ds2.checkout.com/interceptor/sid_y3oqhf46pyzuxjbcn2giaqnb44"
8  }
9}

You must provide the unmodified response to the client's handleSubmit callback. Flow handles any additional required actions.

You can obtain the payment response for both asynchronous and synchronous payments.

Customize your payment process

Custom payment process

Inspect tokenization and card update events

Information

Mount Flow
Client side

Submit a customized payment session
Server side

Request example

Response example

Handle the payment response
Client side

Custom payment process

Inspect tokenization and card update events

Information

Mount Flow Client side

Submit a customized payment session Server side

Request example

Response example

Handle the payment response Client side

Mount Flow
Client side

Submit a customized payment session
Server side

Handle the payment response
Client side