PrimerHeadlessUniversalCheckoutListener

Overview

Set the PrimerHeadlessUniversalCheckoutListener in order to receive different callbacks from Primer SDK.

Callbacks can be used for managing the customer journey and trigger actions after specific events throughout the payment journey. See below for a breakdown of all callbacks supported within the Primer SDK.

onAvailablePaymentMethodsLoaded

This method will return the payment methods that should be displayed based on the current client session data.

KOTLIN

fun onAvailablePaymentMethodsLoaded(
  paymentMethods: List<PrimerHeadlessUniversalCheckoutPaymentMethod>
)

Parameters

Hide Parameters

paymentMethods · List<PrimerHeadlessUniversalCheckoutPaymentMethod> · required

Hide PrimerHeadlessUniversalCheckoutPaymentMethod

paymentMethodType · String · required

A unique string identifier for the payment method.

supportedPrimerSessionIntents · List<PrimerSessionIntent> · required

A list of PrimerSessionIntent which defines what intents can be used with this payment method.

paymentMethodManagerCategories · PrimerPaymentMethodManagerCategory · required

A list which defines the payment method managers that can be used with this payment method.

Show PrimerPaymentMethodManagerCategory

PrimerPaymentMethodManagerCategory.NATIVE_UI

Indicates that the supported payment method manager for the payment method is PrimerHeadlessUniversalCheckoutNativeUiManager.

PrimerPaymentMethodManagerCategory.RAW_DATA

Indicates that the supported payment method manager for the payment method is PrimerHeadlessUniversalCheckoutRawDataManager.

requiredInputDataClass · KClass<out PrimerRawData>?

Indicates the subclass of the PrimerRawData that must be set using the PrimerHeadlessUniversalCheckoutRawManager.

onCheckoutCompleted

This method will be called when the payment has been completed, returning the payment’ data.

This method won’t be called when you are using PrimerPaymentHandling.MANUAL flow, or the PrimerSessionIntent.VAULT session intent.

KOTLIN

fun onCheckoutCompleted(checkoutData: PrimerCheckoutData)

Parameters

Hide Parameters

checkoutData · PrimerCheckoutData · required

Hide child attributes

payment · Payment · required

Hide child attributes

id · String · required

ID of created payment.

orderId · String · required

Order ID of created payment.

additionalInfo · PrimerCheckoutAdditionalInfo?

Hide direct subclasses

XenditCheckoutVoucherAdditionalInfo

Hide Properties

expiresAt · String · required

couponCode · String · required

retailerName · String · required

PromptPayCheckoutAdditionalInfo

Hide Properties

expiresAt · String · required

qrCodeUrl · String?

qrCodeBase64 · String · required

MultibancoCheckoutAdditionalInfo

Hide Properties

expiresAt · String · required

entity · String · required

reference · String · required

AchAdditionalInfo

Hide direct subclasses

ProvideActivityResultRegistry

Hide Properties

provide · (ActivityResultRegistry) -> Unit · required

Provides an ActivityResultRegistry to be used for ACH bank account selection.

DisplayMandate

Hide Properties

onAcceptMandate · suspend () -> Unit · required

Accepts the ACH mandate, completing the payment.

onDeclineMandate · suspend () -> Unit · required

Declines the ACH mandate, cancelling the payment.

onBeforePaymentCreated

This method will be called just before the payment gets created, and lets you decide whether you want to proceed with the payment creation.

This method will be called only when using the PrimerPaymentHandling.AUTO flow. Please note, that if you override this method, you must call one of the decisionHandler’s methods.

KOTLIN

fun onBeforePaymentCreated(
  paymentMethodData: PrimerPaymentMethodData,
  decisionHandler: PrimerPaymentCreationDecisionHandler
)

Parameters

Hide Parameters

paymentMethodData · PrimerPaymentMethodData · required

Hide child attributes

paymentMethodType · String · required

A unique string identifier for the payment method. (e.g. PAYPAL, GOOGLE_PAY)

decisionHandler · PrimerPaymentCreationDecisionHandler · required

Show Methods

continuePaymentCreation(idempotencyKey: String? = null)

Call continuePaymentCreation() when you want to continue with the payment creation. Optionally provide an idempotencyKey to prevent duplicate payments. The SDK attaches it as X-Idempotency-Key header on payment creation and resume requests. The same key is reused for the entire payment lifecycle and automatically cleared on completion or failure.

abortPaymentCreation(errorMessage)

Call abortPaymentCreation(errorMessage) when you want to abort the payment. Optionally you can provide an error message to get presented on the error screen.

Example

KOTLIN

class CheckoutActivity : AppCompatActivity() {
  // 👇 Add this
  private val listener = object : PrimerCheckoutListener {
    // 👇 Add this
    override fun onBeforePaymentCreated(
      paymentMethodData: PrimerPaymentMethodData,
      decisionHandler: PrimerPaymentCreationDecisionHandler
    ) {
      decisionHandler.continuePaymentCreation()
    }
  }
}

Example with Idempotency Key

KOTLIN

class CheckoutActivity : AppCompatActivity() {
  private val listener = object : PrimerCheckoutListener {
    override fun onBeforePaymentCreated(
      paymentMethodData: PrimerPaymentMethodData,
      decisionHandler: PrimerPaymentCreationDecisionHandler
    ) {
      val idempotencyKey = "${UUID.randomUUID()}"
      decisionHandler.continuePaymentCreation(idempotencyKey = idempotencyKey)
    }
  }
}

onCheckoutAdditionalInfoReceived

This callback is triggered when the payment is not authorized as it’s an asynchronous alternative payment method, such as a voucher payment method.

KOTLIN

fun onCheckoutAdditionalInfoReceived(additionalInfo: PrimerCheckoutAdditionalInfo)

Hide Parameters

additionalInfo · PrimerCheckoutAdditionalInfo · required

Hide direct subclasses

XenditCheckoutVoucherAdditionalInfo

Hide Properties

expiresAt · String · required

couponCode · String · required

retailerName · String · required

PromptPayCheckoutAdditionalInfo

Hide Properties

expiresAt · String · required

qrCodeUrl · String?

qrCodeBase64 · String · required

MultibancoCheckoutAdditionalInfo

Hide Properties

expiresAt · String · required

entity · String · required

reference · String · required

AchAdditionalInfo

Hide direct subclasses

ProvideActivityResultRegistry

Hide Properties

provide · (ActivityResultRegistry) -> Unit · required

Provides an ActivityResultRegistry to be used for ACH bank account selection.

DisplayMandate

Hide Properties

onAcceptMandate · suspend () -> Unit · required

Accepts the ACH mandate, completing the payment.

onDeclineMandate · suspend () -> Unit · required

Declines the ACH mandate, cancelling the payment.

onTokenizeSuccess

This method will be called with the when the payment method has been is tokenized, returning the payment method’s tokenization data. Use the token to create a payment on your backend. Make sure that you call the decisionHandler once your operation has been completed.

This method will be called when you are using PrimerPaymentHandling.MANUAL flow, or the PrimerSessionIntent.VAULT session intent.

KOTLIN

fun onTokenizeSuccess(
  paymentMethodTokenData: PrimerPaymentMethodTokenData,
  decisionHandler: PrimerResumeDecisionHandler
)

Parameters

Hide child attributes

paymentMethodTokenData · PrimerPaymentMethodTokenData · required

Show Properties

paymentInstrumentData · PaymentInstrumentData?

Show Properties

network · String?

The human readable representation of card network (e.g., Visa, Mastercard).

cardholderName · String?

The name of the cardholder.

first6Digits · Int?

The first 6 digits of the card number.

last4Digits · Int?

The last 4 digits of the card number.

accountNumberLast4Digits · Int?

The last 4 digits of the account number.

expirationMonth · Int?

The expiration month of the card, in 2-digit format.

expirationYear · Int?

The expiration year of the card, in 4-digit format.

externalPayerInfo · ExternalPayerInfo?

External information about the payer associated with the transaction.

Hide Properties

email · String

The payer’s email address.

externalPayerId · String?

The payer’s unique ID.

firstName · String?

The payer’s given name.

lastName · String?

The payer’s given surname.

klarnaCustomerToken · String?

sessionData · SessionData?

paymentMethodType · String?

A unique string identifier for the payment method. (e.g. PAYPAL, GOOGLE_PAY)

binData · BinData?

Additional BIN data.

Hide Properties

network · String?

The card network (e.g., VISA, MASTERCARD, AMEX).

bankName · String?

The name of the bank.

decisionHandler · PrimerResumeDecisionHandler · required

Show Methods

handleSuccess()

Call handleSuccess when you want to show the success screen, or finalize the flow successfully in case you have hidden the success screen.

handleFailure(errorMessage)

Call handleFailure when you want to show the error screen, or finalize the flow with error in case you have hidden the error screen.

continueWithNewClientToken(clientToken)

Call continueWithNewClientToken when the payment has entered in a state and a required action client token has been provided.

Example

KOTLIN

class CheckoutActivity : AppCompatActivity() {
  // 👇 Add this
  private val listener = object : PrimerCheckoutListener {
    // 👇 Add this
    override fun onTokenizeSuccess(
      paymentMethodTokenData: PrimerPaymentMethodTokenData,
      decisionHandler: PrimerResumeDecisionHandler
    ) {
      // Create your payment
      val paymentResponse =  //...
      if (paymentResponse.isSuccessful()) {
        // 👇 Call the decisionHandler to show the success screen
        decisionHandler.handleSuccess()
      } else if (paymentResponse.isPending()) {
        // 👇 Call the decisionHandler with the new client token to continue the flow
        decisionHandler.continueWithNewClientToken(paymentResponse.requiredAction.clientToken)
      } else {
        // 👇 Call the decisionHandler to show the error screen with your custom error message
        decisionHandler.handleFailure("Your error message.")
      }
    }
  }
}

onCheckoutResume

This method will be called providing a resumeToken so you can resume the payment.

This method will be called when you are using PrimerPaymentHandling.MANUAL flow and when the payment is in a state.

KOTLIN

fun onResumeSuccess(resumeToken: String, decisionHandler: PrimerResumeDecisionHandler)

Parameters

Hide parameters

decisionHandler · PrimerResumeDecisionHandler · required

Show Methods

handleSuccess()

Call handleSuccess when you want to show the success screen, or finalize the flow successfully in case you have hidden the success screen.

handleFailure(errorMessage)

Call handleFailure when you want to show the error screen, or finalize the flow with error in case you have hidden the error screen.

continueWithNewClientToken(clientToken)

Call continueWithNewClientToken when the payment has entered in a state and a required action client token has been provided.

Example

KOTLIN

class CheckoutActivity : AppCompatActivity() {
  // 👇 Add this
  private val listener = object : PrimerCheckoutListener {
    // 👇 Add this
    override fun onResumeSuccess(
      resumeToken: String,
      decisionHandler: PrimerResumeDecisionHandler
    ) {
      // Resume your payment
      val paymentResponse =  //...
      if (paymentResponse.isSuccessful()) {
        // 👇 Call the decisionHandler to show the success screen
        decisionHandler.handleSuccess()
      } else if (paymentResponse.isPending()) {
        // 👇 Call the decisionHandler with the new client token to continue the flow
        decisionHandler.continueWithNewClientToken(paymentResponse.requiredAction.clientToken)
      } else {
        // 👇 Call the decisionHandler to show the error screen with your custom error message
        decisionHandler.handleFailure("Your error message.")
      }
    }
  }
}

onResumePending

This callback is trigger when the payment is not authorized as it’s an asynchronous alternative payment method, such as a voucher payment method.

This method will be called only when using the PrimerPaymentHandling.MANUAL flow.

KOTLIN

fun onResumePending(additionalInfo: PrimerCheckoutAdditionalInfo)

Parameters

Hide child attributes

additionalInfo · PrimerCheckoutAdditionalInfo · required

Hide direct subclasses

XenditCheckoutVoucherAdditionalInfo

Hide Properties

expiresAt · String · required

couponCode · String · required

retailerName · String · required

PromptPayCheckoutAdditionalInfo

Hide Properties

expiresAt · String · required

qrCodeUrl · String?

qrCodeBase64 · String · required

MultibancoCheckoutAdditionalInfo

Hide Properties

expiresAt · String · required

entity · String · required

reference · String · required

AchAdditionalInfo

Hide direct subclasses

ProvideActivityResultRegistry

Hide Properties

provide · (ActivityResultRegistry) -> Unit · required

Provides an ActivityResultRegistry to be used for ACH bank account selection.

DisplayMandate

Hide Properties

onAcceptMandate · suspend () -> Unit · required

Accepts the ACH mandate, completing the payment.

onDeclineMandate · suspend () -> Unit · required

Declines the ACH mandate, cancelling the payment.

onBeforeClientSessionUpdated

This method will be called to notify you that the client session will be updated, e.g. a surcharge needs to be applied when a payment method has been chosen.

KOTLIN

fun onBeforeClientSessionUpdated()

onClientSessionUpdated

This method will be called to notify you that the client session has been updated, e.g. surcharge has been applied when a payment method has been chosen.

KOTLIN

fun onClientSessionUpdated(clientSession: PrimerClientSession)

Parameters

onFailed

This method will be called when an error occurs. It may return PrimerCheckoutData if the error occurs after the payment creation.

Please note, that if you override this method, you must call the errorHandler to finalize the flow.

KOTLIN

fun onFailed(error: PrimerError, checkoutData: PrimerCheckoutData?

Parameters

Hide child attributes

error · PrimerError · required

Show Properties

errorId · String · required

A unique error identifier.

errorCode · String?

A unique error code.

description · String · required

A error description.

recoverySuggestion · String?

A recovery suggestion for the given error. In case it’s present, use it to try to recover from error.

diagnosticsId · String · required

A unique diagnostics id for the given error.

checkoutData · PrimerCheckoutData?

Show Properties

payment · Payment · required

Hide child attributes

id · String · required

ID of created payment.

orderId · String · required

Order ID of created payment.

additionalInfo · PrimerCheckoutAdditionalInfo?

Hide direct subclasses

XenditCheckoutVoucherAdditionalInfo

Hide Properties

expiresAt · String · required

couponCode · String · required

retailerName · String · required

PromptPayCheckoutAdditionalInfo

Hide Properties

expiresAt · String · required

qrCodeUrl · String?

qrCodeBase64 · String · required

MultibancoCheckoutAdditionalInfo

Hide Properties

expiresAt · String · required

entity · String · required

reference · String · required

AchAdditionalInfo

Hide direct subclasses

ProvideActivityResultRegistry

Hide Properties

provide · (ActivityResultRegistry) -> Unit · required

Provides an ActivityResultRegistry to be used for ACH bank account selection.

DisplayMandate

Hide Properties

onAcceptMandate · suspend () -> Unit · required

Accepts the ACH mandate, completing the payment.

onDeclineMandate · suspend () -> Unit · required

Declines the ACH mandate, cancelling the payment.

decisionHandler · PrimerErrorDecisionHandler?

Show Methods

showErrorMessage(errorMessage: String | null)

Call with your custom error message.

Example

KOTLIN

class CheckoutActivity : AppCompatActivity() {
    // 👇 Add this
    private val listener = object : PrimerCheckoutListener {
        // 👇 Add this
        override fun onFailed(
            error: PrimerError,
            checkoutData: PrimerCheckoutData?,
            errorHandler: PrimerErrorDecisionHandler?
        ) {
            errorHandler?.showErrorMessage(null)
        }
    }
}