Cards & Wallets · Mobile SDK

Payment Methods

The SDK supports card, Apple Pay and Google Pay payments, plus Pay by Bank (Open Banking). The flow is the same for each - only the function that starts the payment differs. Pay by Bank needs a return URL registered with the operating system, so it is documented under Pay by Bank.

Available payment methods

Initiating and completing a payment

These steps are the same for every available payment method - the only difference is the function that starts the payment.

1. Create the PaymentConfig

See Payment Setup.

2. Initiate the PaymentProcessor

Make sure you set at minimum the payment result callback.

3. Let the user input their card details

To do so you will need to display either the Card Input or Card Input Slim component.

4. Start the payment process

Launch the relevant function of the PaymentProcessor to begin the payment:

Card

More details

Kotlin
paymentProcessor.processCardPayment(billingAddress: customerBillingAddress)
Swift
paymentProcessor?.processCardPayment(billingAddress: customerBillingAddress)

Apple Pay

More details

Swift
paymentProcessor?.processApplePayPayment(appleMerchantId: applePayMerchantId, billingAddress: customerBillingAddress)

Google Pay

More details

Kotlin
paymentProcessor.processGooglePayPayment(billingAddress: customerBillingAddress)

Pay by Bank

Pay by Bank uses the same processor, but it needs a return URL registered with the operating system so the bank can hand the customer back to the app. See Take a payment for the call and Return URL setup for the link setup.

Good to know

While we do not impose any guideline for creating the normal payment button (pay by card), we strongly recommend handling its state properly. For example, when the user presses the button to pay with the card, make sure the UI updates after the click to inform them that something is happening - a loading indicator, the button becoming disabled, and so on. Design your payment flow with good UX: make sure the user knows at all times what stage they are at.

5. Wait for the payment result

The payment result is sent via the payment result callback.
The transaction id arrives earlier than the result. Register the transaction id callback to receive it while 3-D Secure, the wallet sheet or the bank redirect is still in progress - see Payment Setup.

6. Interpret the payment result

The callback returns a Status object of one of the following types:

StatusDescription
SuccessThe payment was successful.
CanceledThe user cancelled the payment process. This usually happens when the user cancels the Google Pay, Apple Pay or Pay by Bank flow before completing. Canceled is a Mobile SDK status - the API has no cancelled state, so a cancelled payment shows as Failed in the payment dashboard.
SessionExpiredThe authentication token expired before the payment finished. Request a new token and initiate the payment again.
Pending(Pay by Bank only) The provider is still processing the transaction. Keep the transaction id and retrieve the transaction for its final status - see Pending transactions.
ErrorThe payment failed. The object has two extra values that can be accessed to identify the issue: status.message and status.traceId. The traceId can be used as a debugging aid by us if the payment finished with an unexpected error.
After receiving the payment status the session is invalidated and cannot be reused; a new initiation is required. This happens for any status received except Status.Canceled.
Status.Canceled can be used to inform the user that they cancelled the process for that payment method (Google Pay, Apple Pay and Pay by Bank) and ask whether they still want to continue with the same or a different payment method in the same session.

Verify a new card

A verify card session is a special payment session where no amount is deducted from the cardholder. It can be used to pre-verify a card’s validity before a transaction, or to save a card to a customer without making a payment.

To make a verify session:

  • The customer details are necessary.
  • A clientToken with the MOBILE_CUSTOMER_PAYMENT scope enabled.
  • To save the card as well, enable the Save Card toggle in your UI, or call setSaveCard(true) yourself. It only has an effect when canSaveCards is true.
  • The PaymentConfig must use a TransactionDetails object whose amount is null - see below.

Then start the verification like any card payment:

Kotlin
paymentProcessor.processVerifyCard(billingAddress)
Swift
try paymentProcessor.processVerifyCard(billingAddress: billingAddress)

A verify session is created by providing the PaymentConfig with a TransactionDetails object whose amount is set to null.

Kotlin
val paymentConfig = PaymentConfig(
  installationId = installationId,
  countryCode = countryCode,
  currencyCode = currency,
  transactionType = TransactionType.PAYMENT, // <-- keep transaction type as payment
  clientToken = authToken,
  transaction = TransactionDetails(
      amount = null, // <-- amount set to null
      currency = currency,
      merchantRef = merchantRef,
  ),
  customer = customerDetails,
  financialServices = financialServices,
  environment = environment
)

The result is delivered through the same payment result callback as a payment. The card is saved only when saving was enabled for the session.