Retrieve card metadata

Last updated: October 6, 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 card scheme.
Modify the payment amount based on additional checkout information. For example, a promotional code or a shipping address that incurs additional delivery fees.

Information

Follow the Getting started with Flow for mobile guide before you update your integration with the steps outlined on this page.

Add the event to the initialization code for your Flow for mobile configuration.

Implement the event logic to customize the payment flow depending on the card details the customer enters. For example, the following code creates branching logic depending on the card scheme detected and rejects credit card payments:


1val callbacks = ComponentCallback(
2  onCardBinChanged = { cardMetadata ->
3    // Apply custom logic based on card scheme
4    when (cardMetadata.scheme) {
5      "visa" -> {
6        // apply custom logic for Visa cardholders
7      }
8      "mastercard" -> {
9        // apply custom logic for Mastercard cardholders
10      }
11      else -> {
12        // default case
13      }
14    }
15    
16    // Reject credit cards
17    if (cardMetadata.cardType == "credit") {
18      CallbackResult.Rejected("Credit cards are not accepted.")
19    } else {
20      // Otherwise, proceed with the payment
21      CallbackResult.Accepted
22    }
23  }
24)
25val configuration = CheckoutComponentConfiguration(
26  componentCallback = callbacks
27)


1let callbacks = CheckoutComponents.Callbacks(...onCardBinChanged: { cardMetadata -> CheckoutComponents.CallbackResult in      
2    
3// Apply custom logic based on card scheme
4switch cardMetadata.scheme {
5  case "visa":
6    // apply custom logic for Visa cardholders
7    break
8case "mastercard":
9    // apply custom logic for Mastercard cardholders
10    break
11  default:
12    break
13}
14      
15// Reject credit cards
16if cardMetadata.cardType == "credit" {
17  return .rejected(message: "Credit cards are not accepted.")
18}
19      
20 // Otherwise, proceed with the payment
21 return .accepted
22}...)
23let configuration = CheckoutComponents.Configuration(..., callbacks: callbacks)

The handleSubmit event enables you to submit a modified payment session.

Add the event to the initialization code for your Flow for mobile configuration.

Implement the callback logic to provide the payment submission data to your server-side integration:


1suspend fun handleSubmit(sessionData: SessionData): ApiCallResult {
2  handlePaymentSubmission()
3}
4val callback = ComponentCallback(handleSubmit = ::handleSubmit)


1let callbacks = CheckoutComponents.Callbacks(...handleSubmit: handleSubmit)
2let configuration = CheckoutComponents.Configuration(..., callbacks: callbacks)

Call the Submit a payment session endpoint and provide the payment session ID as the {id} 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": 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 handleSubmit event in the client-side integration. Flow handles any additional required actions.

Retrieve card metadata

Information

Add the handleSubmit event
Client side

Submit the modified payment session
Server side

Request example

Response example

Handle the payment response
Client side

Information

Add the handleSubmit event Client side

Submit the modified payment session Server side

Request example

Response example

Handle the payment response Client side

Add the handleSubmit event
Client side

Submit the modified payment session
Server side

Handle the payment response
Client side