Retrieve card metadata
Last updated: July 2, 2025
Use the onCardBinChanged
event to monitor the card details provided by the customer in real time. This enables you to customize the payment session with the data collected and implement more complex processes. For example, if you want to:
- Add custom logic depending on the payment card's scheme.
- Modify the payment amount based on additional checkout information, such as a promotional code or a shipping address that incurs additional delivery fees.
Information
Follow the Getting started with Flow guide before you update your integration with the steps outlined on this page.
The onCardBinChanged
event triggers when the customer inputs the first eight digits of the card number. It then returns the Request card metadata response.
Add the event to the initialization code for your Flow instance:
1// Flow initialization2const flowComponent = checkout.create('flow', {3onCardBinChanged,4});
Implement the event logic to customize the payment flow depending on the card details the customer inputs. For example, the following code creates branching logic depending on the card scheme detected and rejects credit card payments:
1//Implement the onCardBinChanged event2const onCardBinChanged = (self, cardMetadata) => {34// Apply custom logic based on card scheme5switch (cardMetadata.scheme) {6case 'visa':7// apply custom logic for Visa8break;9case 'mastercard':10// apply custom logic for Mastercard11break;12}1314// Reject credit cards15if (cardMetadata.card_type === 'credit') {16return {17continue: false,18errorMessage: 'Credit cards are not accepted.',19};20}2122// Otherwise, allow the payment to proceed23return {24continue: true,25};26};
The handleSubmit
event enables you to submit a modified payment session.
Add the event to the initialization code for your Flow instance:
1// Flow initialization2const flowComponent = checkout.create('flow', {3onCardBinChanged,4handleSubmit,5});
Implement the event logic to provide the payment submission data to your server-side integration:
1const handleSubmit = async (self, submitData) => {2// Provide the `submitData` to your server-side integration3// for payment submission4const submitResponse = await performPaymentSubmission(submitData);56return submitResponse;7};
Call the Submit a payment session endpoint and provide the payment session's ID as a path parameter.
In your request, provide the payment session data from the handleSubmit
event in session_data
. You can also modify any of the following fields:
3ds
amount
items
reference
post
https://api.checkout.com/payment-sessions/{id}/submit
1{2"session_data": "{SESSION_DATA_FROM_FLOW}",3"3ds": {4"enabled": true5}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 handleSubmit
event in the client-side integration. Flow handles any additional required actions.
You can obtain the payment response for both asynchronous and synchronous payments.