ComponentCallback

Last updated: October 6, 2025


1/**
2 * Represents a callback interface for handling events for a payment method
3 *
4 * @property onReady Triggered when the payment method is ready.
5 * @property onChange Triggered when the payment method is changed and any new updates.
6 * @property onSubmit Triggered when the payment method is submitted.
7 * @property onSuccess Triggered when the payment is completed successfully.
8 * @property onError Triggered when there is an error.
9 * @property onTokenized Triggered when a card is tokenized, providing the [TokenizationResult].
10 *                       return [CallbackResult] to indicate whether to proceed with or block the payment.
11 * @property onCardBinChanged Triggered when the card BIN (first 8 digits) changes, providing the [CardMetadata].
12 *                       return [CallbackResult] to indicate whether to proceed with card scheme or block the payment.
13 * @property handleSubmit Triggered when payment submission is required. You can implement this to handle payment submission with your own backend. 
14 *                        The function receives [SessionData] and should return [ApiCallResult], indicating the success or failure of the submission.
15 * @property handleTap Triggered when the pay button is pressed after SDK's validation for respective payment method.
16 *                     If implemented and it returns true, the payment process continues. If it returns false, the payment process stops and no other callbacks are triggered.
17 */
18
19public data class ComponentCallback(
20    val onReady: ((PaymentMethodComponent) -> Unit)? = null,
21    val onChange: ((PaymentMethodComponent) -> Unit)? = null,
22    val onSubmit: ((PaymentMethodComponent) -> Unit)? = null,
23    val onSuccess: ((PaymentMethodComponent, String) -> Unit)? = null,
24    val onError: ((PaymentMethodComponent, CheckoutError) -> Unit)? = null,
25    val onTokenized: ((TokenizationResult) -> CallbackResult)? = null,
26    val onCardBinChanged: ((CardMetadata) -> CallbackResult)? = null,
27    val handleSubmit: (suspend (SessionData) -> ApiCallResult)? = null,
28    val handleTap: ((PaymentMethodComponent) -> Boolean)? = null,
29)

Triggered when the customer inputs or changes the first eight digits of a card.

Use this event to perform checks on the card based on its metadata, or to observe changes to the bank identification number (BIN).

The CardMetadata object contains the response to the Get card metadata request.

If you do not provide a callback, Flow for Mobile automatically accepts the card. You can also explicitly specify the action to take:

To accept the card, return CallbackResult.Accepted.
To reject the card, return CallbackResult.Rejected("Error message"). You can also provide an optional errorMessage to display a custom error message on the card component.


1val callback = ComponentCallback(
2  onCardBinChanged = { cardMetadata ->
3    // Check if card is from a specific issuer
4    if (cardMetadata.issuer == "RESTRICTED_BANK") {
5      CallbackResult.Rejected("Cards from this bank are not accepted")
6    }
7    // Check if card is from a specific country
8    else if (cardMetadata.issuerCountry == "XX") {
9      CallbackResult.Rejected("Cards from this country are not supported")
10    }
11    // Check card type
12    else if (cardMetadata.cardType == "credit") {
13      CallbackResult.Rejected("Credit cards are not accepted")
14    }
15    // Accept all other cards
16    else {
17      CallbackResult.Accepted
18    }
19  }
20)
21val config = CheckoutComponentConfiguration(
22  componentCallback = callback
23)

Triggered when a PaymentMethodComponent is initialized and ready for the customer to interact.

PaymentMethodComponent is the payment method component that triggered the event.


1fun onReady(component: PaymentMethodComponent) {
2  // Hide loading overlay
3  hideLoadingOverlay();
4}
5
6val callback = ComponentCallback(onReady=onReady) 
7val config = CheckoutComponentConfiguration(
8  componentCallback = callback
9)

Triggered when you or the customer triggers a PaymentMethodComponent submission.
PaymentMethodComponent is the name of the payment method component that Triggered the event.


1fun onSubmit(component: PaymentMethodComponent) {
2  // Show loading overlay to prevent further user interaction
3  showLoadingOverlay();
4}
5
6val callback = ComponentCallback(onSubmit=onSubmit) 
7val config = CheckoutComponentConfiguration(
8  componentCallback = callback
9)

Triggered when the payment is completed synchronously or asynchronously – for example, after a successful 3DS authentication.

The callback contains information on the successful payment:

PaymentMethodComponent is the name of the payment method component that triggered the event.
String is the unique ID of this payment.


1fun onSuccess(Component: PaymentMethodComponent, paymentId: String) {
2  // Complete order in server side
3  completeOrder(paymentId);
4}
5
6val callback = ComponentCallback(onSuccess=onSuccess) 
7val config = CheckoutComponentConfiguration(
8  componentCallback = callback
9)

Triggered when an error occurs. See the CheckoutError reference for more information.
PaymentMethodComponent is the name of the payment method component that triggered the event.


1fun onError(component: PaymentMethodComponent, error: CheckoutError) {
2  // Display the payment request failure message
3  if (error.code == CheckoutErrorCode.PAYMENT_REQUEST_DECLINED) {
4  showErrorMessage('Payment could not be processed. Please try again.');
5  }
6}
7
8val callback = ComponentCallback(onError=onError) 
9val config = CheckoutComponentConfiguration(
10  componentCallback = callback
11)

Triggered when a supported PaymentMethodComponent item is tokenized and provides the TokenizationResult object.

This callback is triggered after a successful card tokenization and provides the TokenizationResult for you to validate.

type – The name of the payment method that triggered the tokenization. Always set this to card.
data – The card tokenization response.
cardMetadata – An optional Card metadata lookup response object included when a you receive a card metadata API response during customer input.
preferredScheme – The customer's preferred payment scheme when multiple schemes are supported for the card. For example, Visa and Cartes Bancaires. This can be null if no preference is selected, or if the scheme choice was not offered.

If you do not provide a callback, Flow for Mobile automatically accepts the card. You can also explicitly specify the action to take:

To accept the card, return CallbackResult.Accepted.
To reject the card, return CallbackResult.Rejected("Error message"). You can also provide an optional errorMessage to display a custom error message on the card component.

Note

If you attempt to tokenize an unsupported component, the onError() callback triggers instead.


1val callback = ComponentCallback(
2  onTokenized = { tokenizationResult ->
3    if (tokenizationResult.data.cardType == "Credit") {
4      CallbackResult.Rejected("Credit cards are not accepted")
5    } else {
6      CallbackResult.Accepted
7    }
8  }
9) 
10val config = CheckoutComponentConfiguration(
11  componentCallback = callback
12)

Use this callback to submit a customized payment session to the Submit a payment session endpoint.

Information

If you do not provide this callback, Flow for Mobile automatically sends the payment request for processing.

sessionData is a unique token that represents the additional customer data captured by Flow for Mobile. You must:

Provide the token in the session_data field when you call the Submit a payment session endpoint.
Provide Flow for Mobile with the unmodified response body returned by the request.


1suspend fun handleSubmit(sessionData: SessionData): ApiCallResult {
2  return try {
3    val response = apiClient.submitPayment(sessionData)
4    if (response.isSuccessful) {
5      ApiCallResult.Success(response.paymentSessionSubmissionResult)
6    } else {
7      ApiCallResult.Failure
8    }
9  } catch (e: Exception) {
10    ApiCallResult.Failure
11  }
12}
13val callback = ComponentCallback(handleSubmit = ::handleSubmit)

Triggered when the pay button is pressed after the SDK validates the respective payment method.

This callback enables you to implement custom validation logic before you continue with the payment.

true - The payment process continues.
false – The payment process stops and no other callbacks are triggered.


1fun handleTap(component: PaymentMethodComponent): Boolean {
2  // Implement custom validation logic.
3  // For example, check terms & conditions acceptance.
4  if (component.isValid() && !termsAccepted) {
5    showTermsError()
6    return false
7  }
8  
9  // Or validate business rules:
10  if (component.isValid() && !isBusinessRuleValid()) {
11    showBusinessRuleError()
12    return false
13  }
14  
15  // Return true to continue payment
16  return true
17}

Triggered when the payment method is changed, and after any new updates.

This callback enables you to react to changes in the payment component state. For example, field updates and validation changes.


1fun onChange(component: PaymentMethodComponent) {
2  // React to component state changes.
3  // For example, update UI based on validation state:
4  CoroutineScope(Dispatchers.Main).launch {
5  try {
6    val isValid = component.isValid()
7    isComponentValid(isValid)
8  } catch (e: Exception) {
9    isComponentValid(false)
10    } 
11}    
12// Or track user component selection
13when (component.name) {
14  is "card"-> {
15  // Handle card changes:
16  }
17  is "googlepay"-> {
18    // Handle Google Pay changes:
19    }
20  }
21}

ComponentCallback

Methods

onCardBinChanged(CardMetadata): -> CallbackResult

onReady(PaymentMethodComponent)

onSubmit(PaymentMethodComponent)

onSuccess(PaymentMethodComponent, PaymentId)

onError(PaymentMethodComponent, CheckoutError)

onTokenized:((TokenizationResult) -> CallbackResult)

Note

handleSubmit: (suspend (SessionData) -> ApiCallResult)

Information

handleTap(PaymentMethodComponent) -> Boolean

onChange(PaymentMethodComponent) -> Unit