ComponentCallback

Last updated: September 3, 2025


1/// - Parameters:
2///   - onReady: A closure that is triggered when the payment method is ready. Defaults to `nil`.
3///   - handleTap: A closure that is used to validate conditions before processing the payment. Useful for handling pre-payment checks like T&C validation. Defaults to `nil`.
4///   - onChange: A closure that is triggered when the payment method is changed and any new updates.
5///   - onCardBinChanged: A closure that is triggered when the card bin is changed and card metadata is successfully fetched.
6///   - onSubmit: A closure that is triggered when the payment method is submitted. Defaults to `nil`.
7///   - onTokenized: A closure that is triggered when an item can be tokenized, providing the token details.
8///   - handleSubmit: A closure that is used to submit a customized payment session
9///   - onSuccess: A closure that is triggered when the payment is successful, passing the payment method and a unique `PaymentId`.
10///   - onError: A closure that is triggered when an error occurs during the payment process.
11
12public init(onReady: (@Sendable (Describable) -> Void)? = nil,
13 handleTap: (@Sendable (Describable) async -> Bool)? = nil,
14 onChange: (@Sendable (Describable & Submittable) -> Void)? = nil,
15 onCardBinChanged: (@Sendable (CardMetadata) -> CallbackResult)? = nil,
16 onSubmit: (@Sendable (Describable) -> Void)? = nil,
17 onTokenized: (@Sendable (TokenizationResult) -> CallbackResult)? = nil,
18 handleSubmit: (@Sendable (SessionData) async -> APICallResult)? = nil,
19 onSuccess: (@Sendable (Describable, PaymentID) -> Void)? = nil,
20 onError: (@Sendable (CheckoutComponents.Error) -> Void)? = nil)

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

Describable is the payment method that triggered the event.


1let callbacks = CheckoutComponents.Callbacks(onReady: { paymentMethod in
2  // Hide loading overlay
3  hideLoadingOverlay();
4}
5
6let configuration = CheckoutComponents.Configuration(callbacks: callbacks)

Triggered when you or the customer trigger a component submission.

Describable is the payment method that triggered the event.


1let callbacks = CheckoutComponents.Callbacks(onSubmit: { paymentMethod in
2   // Show loading overlay to prevent further user interaction
3  showLoadingOverlay();
4}
5
6let configuration = CheckoutComponents.Configuration(callbacks: callbacks)

Triggered when the payment has been synchronously or asynchronously completed. For example, after a successful 3DS authentication.

The callback contains the following payment information:

Describable – The payment method component that triggered the event
PaymentID – The payment's unique identifier


1let callbacks = CheckoutComponents.Callbacks(onSuccess: { paymentMethod, paymentID in
2    // Payment with ID: paymentID has gone through successfully
3}
4
5let configuration = CheckoutComponents.Configuration(callbacks: callbacks)

Triggered when an error occurs. See the CheckoutError reference for more information.

Describable is the payment method component that triggered the event.


1let callbacks = CheckoutComponents.Callbacks(onError: { error in
2  switch error.errorCode {
3    case .paymentRequestDeclined:
4      showErrorMessage("Payment could not be processed. Please try again.")
5    default:
6      showErrorMessage("An error occurred") // Or refine more specific error strings for different error codes
7    }
8  }
9)
10
11let configuration = CheckoutComponents.Configuration(callbacks: callbacks)

Triggered when the customer selects a payment button.

You can use this to perform checks before beginning the payment process.


1handleTap: { paymentMethod async -> Bool in
2  return isTermsAndConditionsAccepted(for: paymentMethod)
3}

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

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.

Flow for mobile accepts the card if you don't provide the callback. Additionally, depending on your preferred action, you can provide the corresponding object:

Accept the card – return .accepted
Reject the card – return .reject(message: "Error message")

If you reject the card, you can display a custom error message using the optional errorMessage object.

Note

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


1onTokenized: { tokenizationResult in
2    if tokenizationResult.data.cardType == "CREDIT" {
3      return .rejected(message: "Credit cards are not accepted.")
4    }
5    return .accepted
6  }
7)
8
9let configuration = CheckoutComponents.Configuration(..., callbacks: callbacks)

Triggered when a component's inputs change after a customer interaction.

Note

If you attempt to submit an unsupported Submittable component, you'll trigger the onError() callback.


1let callbacks = CheckoutComponents.Callbacks(onTokenized: { tokenizationResult in
2 handleToken(tokenizationResult.data) // Or use other token details for your own fraud checks
3})
4let configuration = CheckoutComponents.Configuration(..., callbacks: callbacks)

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

You can use this event to perform checks on a card based on its metadata or to observe changes to the bank identification number (BIN).

The CardMetadata object contains the Card Metadata lookup response.

Flow for mobile accepts the card if you don't provide the callback. Additionally, depending on your preferred action, you can provide the corresponding object:

Accept the card – return .accepted
Reject the card – return .rejected(message: "Error message")

If you reject the card, you can display a custom error message using the optional errorMessage object.


1let callbacks = CheckoutComponents.Callbacks(
2  onCardBinChanged: { cardMetadata in
3    // Reject credit cards
4    if cardMetadata.cardType == "credit" {
5      return .rejected(message: "Credit cards are not accepted.")
6    }
7    // Otherwise, allow the payment to proceed
8    return .accepted
9  }
10)
11
12let configuration = CheckoutComponents.Configuration(..., callbacks: callbacks)

You can use this callback to submit a customized payment, using the Submit a Payment Session endpoint.

If no callback is provided, the payment is processed as normal, and Flow for mobile sends the request.

The SubmitData object contains session_data, which is a unique token representing the additional customer data that Flow for mobile captured. You must provide this token when you submit the customized payment session request.

You must provide the unmodified response body returned by the endpoint.


1let callbacks = CheckoutComponents.Callbacks(
2  handleSubmit: { sessionData in
3    submitPaymentSession(sessionData)
4  }
5)
6
7let configuration = CheckoutComponents.Configuration(..., callbacks: callbacks)

ComponentCallback

Methods

onReady(Describable)

onSubmit(Describable)

onSuccess(Describable, PaymentID)

onError(CheckoutComponents.Error)

handleTap(Describable)

onTokenized(TokenizationResult)

Note

onChange(Describable)

Note

onCardBinChanged(CardMetadata) : CallbackResult

handleSubmit(SessionData) : APICallResult