Android SDK reference

The reader SDK and Tap to Pay SDK are separate packages. Use the response model for the SDK that started the payment.

Response fields

Several response fields are available when the callback activity is called:

Read these fields from the intent returned by SumUpCheckoutContract, rather than your activity’s original launch intent. Inside its callback, where result is the returned activity result:

val data = result.data
val resultCode = data?.getIntExtra(SumUpAPI.Response.RESULT_CODE, -1)
val transactionCode = data?.getStringExtra(SumUpAPI.Response.TX_CODE)

See the Android quickstart for a complete result handler.

Tap to Pay events

These events are emitted by the separate Tap to Pay SDK.

The list of possible events:

• CardRequested - the SDK is trying to detect a card, waiting for the cardholder to tap/present their card.

• CardPresented - a card is detected.

• CVMRequested - a CVM (Cardholder Verification Method) is requested. This event is fired when the card is detected and the SDK is waiting for the cardholder to enter the PIN.

• CVMPresented - a CVM was entered by the cardholder. This event is fired upon completion of the CVM regardless if it was successful or not.

• TransactionDone(val paymentOutput: PaymentOutput) - transaction was completed. PaymentOutput param is:

  data class PaymentOutput(
      val txCode: String,
      val serverTransactionId: String,
      val cardType: String? = null,
      val lastFour: String? = null,
      val merchantCode: String? = null,
      val cardScheme: String? = null
  )

• TransactionFailed(val paymentOutput: PaymentOutput?, val tapToPayException: TapToPayException?) - transaction failed. It might happen due to many reasons, like attestation error, backend error, card reader error, and so on. The full list of errors is described in the Exceptions section. PaymentOutput param might be null if the transaction failed before reaching the backend.

• TransactionCanceled(val paymentOutput: PaymentOutput?) - transaction was canceled by the user.

• TransactionResultUnknown(val paymentOutput: PaymentOutput?) - transaction result is unknown. This might happen on remote calls, when there is no response due to timeout.

• PaymentFlowClosedSuccessfully(val paymentOutput: PaymentOutput, val shouldDisplayReceipt: Boolean = false) - after a successful transaction, once the user dismisses the success screen (or when it is skipped via skipSuccessScreen), the flow closes and fires this event. The Send receipt button has been removed from the SDK success screen (SDK 1.1.6+); receipts must be handled by the host app if required. shouldDisplayReceipt is deprecated, always emitted as false, and will be removed in 1.1.7.

Exceptions

Tap to Pay methods can return Result.Failure with an exception. The exception type identifies whether the problem involves initialization, connectivity, payment processing, or device security.

• CommonException - These exceptions cover scenarios such as initialization issues, registration problems, authentication failures, and required updates, providing a consistent and predictable way to handle errors across the system.
• NetworkException - These exceptions represent network-related and communication errors encountered during SDK operation. They include issues such as interrupted connections, authentication problems, and server/client-side failures.
• PaymentException - These exceptions represent errors related to the payment transaction flow, covering everything from preprocessing to final charge attempts. They include issues such as invalid payment actions, timeouts, incorrect amounts, unsupported card technologies, and unexpected states during card reading. Starting with SDK 1.1.6, when a presented card cannot be used the SDK prompts the cardholder to try another card; after repeated unsuccessful attempts the payment fails with PaymentException.CardErrorNotAccepted (code 1029). If you use an exhaustive when on PaymentException, add a branch for this type.
• PaymentPreparationException - These exceptions relate to the preparation and availability of the payment process. They indicate failures such as the unavailability of the payment function, issues during kernel setup, missing security-related data, and general checkout failures. These errors typically occur before or at the start of a transaction and prevent it from proceeding.
• AttestationException - These exceptions represent errors related to the attestation process, which is crucial for ensuring the security and integrity of the payment environment. They include issues like enabled USB debugging, non secure device or network.
• TapToPayException.Unknown - The Unknown exception represents an internal error that cannot be exposed externally. It acts as a fallback for unexpected or unclassified issues that occur within the SDK, ensuring sensitive or implementation-specific details are not leaked.

Error codes