> ## Documentation Index
> Fetch the complete documentation index at: https://primer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# PrimerHeadlessUniversalCheckoutListener
export const TxnTag = ({status}) => {
const getStyles = status => {
const baseStyle = {
display: 'inline-block',
padding: '4px 8px',
borderRadius: '4px',
fontSize: '13px',
fontWeight: '400'
};
switch (status) {
case "PENDING":
return {
...baseStyle,
backgroundColor: '#ececec',
color: '#9f9f9f'
};
case "AUTHORIZED":
return {
...baseStyle,
backgroundColor: '#ecfdf5',
color: '#047857'
};
case "SETTLED":
case "PARTIALLY_SETTLED":
return {
...baseStyle,
backgroundColor: '#ecfdf5',
color: '#047857'
};
case "DECLINED":
case "FAILED":
return {
...baseStyle,
backgroundColor: '#fef2f2',
color: '#dc2626'
};
case "CANCELLED":
return {
...baseStyle,
backgroundColor: '#fefce8',
color: '#d78203'
};
case "SETTLING":
return {
...baseStyle,
backgroundColor: '#e0f2fe',
color: '#0c4a6e'
};
default:
return {
...baseStyle,
backgroundColor: '#f3f4f6',
color: '#374151'
};
}
};
return {status};
};
## 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 KOTLIN theme={"dark"}
fun onAvailablePaymentMethodsLoaded(
paymentMethods: List
)
```
### Parameters
A unique string identifier for the payment method.
A list of PrimerSessionIntent which defines what intents can be used with this payment method.
{}
{}
A list which defines the payment method managers that can be used with this payment method.
Indicates that the supported payment method manager for the payment method is [PrimerHeadlessUniversalCheckoutNativeUiManager](/sdk/android/v2.x.x/primer-headless-checkout/native-ui-manager/newInstance).
Indicates that the supported payment method manager for the payment method is [PrimerHeadlessUniversalCheckoutRawDataManager](/sdk/android/v2.x.x/primer-headless-checkout/raw-data-manager/newInstance).
Indicates the subclass of the PrimerRawData that must be set using the [PrimerHeadlessUniversalCheckoutRawManager](/sdk/android/v2.x.x/primer-headless-checkout/raw-data-manager/setRawData).
## 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](/sdk/android/v2.x.x/common-objects/PrimerSettings), or the
`PrimerSessionIntent.VAULT` [session
intent](/sdk/android/v2.x.x/common-objects/PrimerSessionIntent).
```kotlin KOTLIN theme={"dark"}
fun onCheckoutCompleted(checkoutData: PrimerCheckoutData)
```
### Parameters
ID of created payment.
Order ID of created payment.
Provides an ActivityResultRegistry to be used for ACH bank account
selection.
Accepts the ACH mandate, completing the payment.
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](/sdk/android/v2.x.x/common-objects/PrimerSettings). Please note,
that if you `override` this method, you **must** call one of the
decisionHandler's methods.
```kotlin KOTLIN theme={"dark"}
fun onBeforePaymentCreated(
paymentMethodData: PrimerPaymentMethodData,
decisionHandler: PrimerPaymentCreationDecisionHandler
)
```
### Parameters
A unique string identifier for the payment method. (e.g. `PAYPAL`, `GOOGLE_PAY`)
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.
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 KOTLIN theme={"dark"}
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 KOTLIN theme={"dark"}
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 KOTLIN theme={"dark"}
fun onCheckoutAdditionalInfoReceived(additionalInfo: PrimerCheckoutAdditionalInfo)
```
Provides an ActivityResultRegistry to be used for ACH bank account
selection.
Accepts the ACH mandate, completing the payment.
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](/sdk/android/v2.x.x/common-objects/PrimerSettings), or the
`PrimerSessionIntent.VAULT` [session
intent](/sdk/android/v2.x.x/common-objects/PrimerSessionIntent).
```kotlin KOTLIN theme={"dark"}
fun onTokenizeSuccess(
paymentMethodTokenData: PrimerPaymentMethodTokenData,
decisionHandler: PrimerResumeDecisionHandler
)
```
### Parameters
{}
{}
{}
{}
{}
The human readable representation of card network (e.g., Visa, Mastercard).
The name of the cardholder.
The first 6 digits of the card number.
The last 4 digits of the card number.
The last 4 digits of the account number.
The expiration month of the card, in 2-digit format.
The expiration year of the card, in 4-digit format.
External information about the payer associated with the transaction.
The payer's email address.
The payer's unique ID.
The payer's given name.
The payer's given surname.
A unique string identifier for the payment method. (e.g. `PAYPAL`,
`GOOGLE_PAY`)
Additional BIN data.
The card network (e.g., VISA, MASTERCARD, AMEX).
The name of the bank.
{}
{}
Call `handleSuccess` when you want to show the success screen, or finalize the flow successfully in case you have hidden the success screen.
Call `handleFailure` when you want to show the error screen, or finalize the flow with error in case you have hidden the error screen.
Call `continueWithNewClientToken` when the payment has entered in a state and a required action client token has been provided.
### Example
```kotlin KOTLIN theme={"dark"}
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](/api-reference/v2.4/api-reference/payments-api/resume-a-payment).
This method **will** be called when you are using
`PrimerPaymentHandling.MANUAL`
[flow](/sdk/android/v2.x.x/common-objects/PrimerSettings) and when the
payment is in a state.
```kotlin KOTLIN theme={"dark"}
fun onResumeSuccess(resumeToken: String, decisionHandler: PrimerResumeDecisionHandler)
```
### Parameters
{}
Call `handleSuccess` when you want to show the success screen, or finalize the flow successfully in case you have hidden the success screen.
Call `handleFailure` when you want to show the error screen, or finalize the flow with error in case you have hidden the error screen.
Call `continueWithNewClientToken` when the payment has entered in a state and a required action client token has been provided.
### Example
```kotlin KOTLIN theme={"dark"}
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](/sdk/android/v2.x.x/common-objects/PrimerSettings).
```kotlin KOTLIN theme={"dark"}
fun onResumePending(additionalInfo: PrimerCheckoutAdditionalInfo)
```
### Parameters
Provides an ActivityResultRegistry to be used for ACH bank account
selection.
Accepts the ACH mandate, completing the payment.
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 KOTLIN theme={"dark"}
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 KOTLIN theme={"dark"}
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 KOTLIN theme={"dark"}
fun onFailed(error: PrimerError, checkoutData: PrimerCheckoutData?
```
### Parameters
A unique error identifier.
A unique error code.
A error description.
A recovery suggestion for the given error. In case it's present, use it to try
to recover from error.
A unique diagnostics id for the given error.
ID of created payment.
Order ID of created payment.
Provides an ActivityResultRegistry to be used for ACH bank account
selection.
Accepts the ACH mandate, completing the payment.
Declines the ACH mandate, cancelling the payment.
Call with your custom error message.
### Example
```kotlin KOTLIN theme={"dark"}
class CheckoutActivity : AppCompatActivity() {
// 👇 Add this
private val listener = object : PrimerCheckoutListener {
// 👇 Add this
override fun onFailed(
error: PrimerError,
checkoutData: PrimerCheckoutData?,
errorHandler: PrimerErrorDecisionHandler?
) {
errorHandler?.showErrorMessage(null)
}
}
}
```