Overview
Set the PrimerCheckoutListener 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.
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.
1fun onCheckoutCompleted(checkoutData: PrimerCheckoutData)Parameters
checkoutDataPrimerCheckoutDataRequired
paymentPaymentRequired
Properties
idStringRequired
ID of created payment.orderIdStringRequired
Order ID of created payment.additionalInfoPrimerCheckoutAdditionalInfo?
direct subclasses
XenditCheckoutVoucherAdditionalInfo
Properties
expiresAtStringRequired
couponCodeStringRequired
retailerNameStringRequired
PromptPayCheckoutAdditionalInfo
Properties
expiresAtStringRequired
qrCodeUrlString?
qrCodeBase64StringRequired
MultibancoCheckoutAdditionalInfo
Properties
expiresAtStringRequired
entityStringRequired
referenceStringRequired
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.
1234
fun onBeforePaymentCreated( paymentMethodData: PrimerPaymentMethodData, decisionHandler: PrimerPaymentCreationDecisionHandler)
Parameters
paymentMethodDataRequired
paymentMethodTypeStringRequired
A unique string identifier for the payment method. (e.g. PAYPAL, GOOGLE_PAY)
decisionHandlerPrimerPaymentCreationDecisionHandlerRequired
Methods
continuePaymentCreation()
Call continuePaymentCreation() when you want to continue with the payment creation.
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
123456789101112
class CheckoutActivity : AppCompatActivity() { // 👇 Add this private val listener = object : PrimerCheckoutListener { // 👇 Add this override fun onBeforePaymentCreated( paymentMethodData: PrimerPaymentMethodData, decisionHandler: PrimerPaymentCreationDecisionHandler ) { decisionHandler.continuePaymentCreation() } } }
onAdditionalInfoReceived
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.AUTO flow.
1fun onAdditionalInfoReceived(additionalInfo: PrimerCheckoutAdditionalInfo)Parameters
additionalInfoPrimerCheckoutAdditionalInfoRequired
direct subclasses
XenditCheckoutVoucherAdditionalInfo
Properties
expiresAtStringRequired
couponCodeStringRequired
retailerNameStringRequired
PromptPayCheckoutAdditionalInfo
Properties
expiresAtStringRequired
qrCodeUrlString?
qrCodeBase64StringRequired
MultibancoCheckoutAdditionalInfo
Properties
expiresAtStringRequired
entityStringRequired
referenceStringRequired
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.
1234
fun onTokenizeSuccess( paymentMethodTokenData: PrimerPaymentMethodTokenData, decisionHandler: PrimerResumeDecisionHandler)
Parameters
paymentMethodTokenDataPrimerPaymentMethodTokenDataRequired
Properties
tokenStringRequired
tokenTypeTokenTypeRequired
Cases
MULTI_USE
SINGLE_USE
analyticsIdStringRequired
paymentInstrumentTypeStringRequired
paymentInstrumentDataPaymentInstrumentData?
Properties
paymentMethodTypeString?
sessionInfoSessionInfo?
first6DigitsString?
last4DigitsString?
expirationMonthString?
expirationYearString?
cardholderNameString?
networkString?
binDataBinData?
externalPayerInfoExternalPayerInfo?
klarnaCustomerTokenString?
sessionDataSessionData?
hashedIdentifierString?
mncInt?
mccInt?
mxInt?
currencyCodeCurrency?
productIdString?
vaultDataVaultData?
threeDSecureAuthenticationAuthenticationDetails?
decisionHandlerPrimerResumeDecisionHandlerRequired
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 PENDING state and a required action client token has been provided.
Example
1234567891011121314151617181920212223
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.") } } }}
onResumeSuccess
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 PENDING state.
1fun onResumeSuccess(resumeToken: String, decisionHandler: PrimerResumeDecisionHandler)Parameters
parameters
resumeTokenStringRequired
decisionHandlerPrimerResumeDecisionHandlerRequired
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 PENDING state and a required action client token has been provided.
Example
1234567891011121314151617181920212223
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.
1fun onResumePending(additionalInfo: PrimerCheckoutAdditionalInfo)Parameters
additionalInfoPrimerCheckoutAdditionalInfoRequired
direct subclasses
XenditCheckoutVoucherAdditionalInfo
Properties
expiresAtStringRequired
couponCodeStringRequired
retailerNameStringRequired
PromptPayCheckoutAdditionalInfo
Properties
expiresAtStringRequired
qrCodeUrlString?
qrCodeBase64StringRequired
MultibancoCheckoutAdditionalInfo
Properties
expiresAtStringRequired
entityStringRequired
referenceStringRequired
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.
1fun 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.
1fun onClientSessionUpdated(clientSession: PrimerClientSession)Parameters
clientSessionPrimerClientSessionRequired
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.
1fun onFailed(error: PrimerError, checkoutData: PrimerCheckoutData?, errorHandler: PrimerErrorDecisionHandler?)Parameters
errorPrimerErrorRequired
Properties
errorIdStringRequired
A unique error identifier.descriptionStringRequired
A error description.recoverySuggestionString?
A recovery suggestion for the given error. In case it's present, use it to try to recover from error.diagnosticsIdStringRequired
A unique diagnostics id for the given error.checkoutDataPrimerCheckoutData?
Properties
paymentPaymentRequired
Properties
idStringRequired
ID of created payment.orderIdStringRequired
Order ID of created payment.additionalInfoPrimerCheckoutAdditionalInfo?
direct subclasses
XenditCheckoutVoucherAdditionalInfo
Properties
expiresAtStringRequired
couponCodeStringRequired
retailerNameStringRequired
PromptPayCheckoutAdditionalInfo
Properties
expiresAtStringRequired
qrCodeUrlString?
qrCodeBase64StringRequired
MultibancoCheckoutAdditionalInfo
Properties
expiresAtStringRequired
entityStringRequired
referenceStringRequired
decisionHandlerPrimerErrorDecisionHandler?
Methods
showErrorMessage(errorMessage: String?)
Call with your custom error message.Example
12345678910111213
class CheckoutActivity : AppCompatActivity() { // 👇 Add this private val listener = object : PrimerCheckoutListener { // 👇 Add this override fun onFailed( error: PrimerError, checkoutData: PrimerCheckoutData?, errorHandler: PrimerErrorDecisionHandler? ) { errorHandler?.showErrorMessage(null) } }}
onDismissed
This method will be called to notify you that the Primer SDK has been dismissed.
1fun onDismissed()