Understand error types, handle payment failures, and implement proper error recovery.
Drop-in delivers almost all failures through the onError callback. onError is (PaymentMethod?, BaseSdkException) -> Unit. Branch on error.errorCode (and error.message when useful). paymentMethod is null for initialisation or cross-method errors. For Aeropay failures, it's PaymentMethod.AEROPAY.
Shopper cancellation of PayPal, Google Pay, or Aeropay popups is delivered via methodConfig.global.onCancel, not onError. See onCancel. Card or 3DS abandonment still uses onError.
Register onError on CheckoutDropInConfig:
import android.util.Log
import com.pxp.checkout.checkoutdropin.CheckoutDropIn
import com.pxp.checkout.checkoutdropin.types.CheckoutDropInConfig
import com.pxp.checkout.checkoutdropin.types.PaymentMethod
import com.pxp.checkout.exceptions.BaseSdkException
import com.pxp.checkout.exceptions.SdkErrorCodes
val checkoutDropIn = CheckoutDropIn.initialize(
context = context,
config = CheckoutDropInConfig(
// ... other config
onError = { paymentMethod, error ->
Log.e(
"CheckoutDropIn",
"Payment failed [${paymentMethod?.value}]: ${error.errorCode}: ${error.message}"
)
// Handle the error (define showErrorMessage in your activity/fragment)
showErrorMessage(error.message)
}
)
)Inspect these properties on BaseSdkException:
| Property | Description |
|---|---|
messageString? | Human-readable error message describing what went wrong. Nullable in Kotlin (Exception.message); use null-safe checks when matching substrings. |
errorCodeString | SDK error code in format SDK#### (e.g., SDK1113 for authentication failed). Network failures may appear as SDK0500 or SDK0550 (SdkErrorCodes.NETWORK_ERROR). Check the message if you need to distinguish network from other uses of SDK0500. Use errorCode for programmatic handling. |
detailsAny? | Optional extra context (e.g., field-level Aeropay consumer validation for SDK1300). |
Errors are organised into four main categories based on their source and nature. Tables list error codes. Handle them via error.errorCode on BaseSdkException.
Errors that occur during SDK initialisation or component rendering due to invalid configuration.
| Error code | Description | Solution |
|---|---|---|
SDK1100 | Drop-in configuration not found or invalid. | Verify initialisation parameters. |
SDK1101 | Failed to render card component. | Check session configuration for card support. |
SDK1102 | Failed to render PayPal button. | Verify PayPal is enabled in session. |
SDK1103 | Failed to render Google Pay button. | Check Google Pay configuration. |
SDK1118 | PayPal only supports Ecom entry type. | Change entryType to EntryType.Ecom. |
SDK1119 | No payment methods available after create() (empty or unsupported session funding). | Enable at least one funding type in the session, or allow at least one card section to render. |
SDK1125 | Failed to render Aeropay component. Merchants see SDK1125 on error.errorCode. Related setup failures may appear on error.cause as SDK0113 (blank credentials) or SDK0115 (missing aeropayDropInIntent). | Verify allowedFundingTypes.payByBanks.aeropay has non-blank externalMerchantId and configurationId, and set aeropayDropInIntent. Wrong currency or entry type surfaces as SDK0116 or SDK0114 instead. See Aeropay. |
Aeropay entry-type failures use SDK0114 (typically with paymentMethod == PaymentMethod.AEROPAY). Card and Google Pay authorisation failures use SDK1114, which is a different code.
Example handling:
onError = { paymentMethod, error ->
if (error.errorCode.startsWith("SDK110") ||
error.errorCode == "SDK1119" ||
error.errorCode == "SDK1125") {
Log.e("CheckoutDropIn", "Rendering error: ${error.message}")
logger.error("Rendering error", mapOf(
"error_code" to error.errorCode,
"message" to error.message,
"payment_method" to (paymentMethod?.value ?: "none")
))
showErrorMessage(
"We're having trouble loading payment options. " +
"Please refresh the page or contact support."
)
}
}Errors that occur during payment processing for specific payment methods.
| Error code | Description | User action |
|---|---|---|
SDK1115 | Card payment failed (see detection patterns below). | See card-specific patterns below. |
SDK1116 | PayPal transaction failed. | Try again or use a different method. |
SDK1117 | Google Pay transaction failed. | Try again or use a different method. |
SDK1126 | Aeropay payment failed (generic Drop-in fallback when a more specific Aeropay error isn't available). | Try again or use a different method. See Aeropay. |
Other Aeropay codes on onError with paymentMethod == PaymentMethod.AEROPAY include create-time consumer validation (SDK1300 when non-empty onGetShopper fields are invalid) and popup-flow failures (e.g., SDK1302 OTP, SDK1304 Aerosync, SDK1307 user not active). See Aeropay for the full list.
Since card errors come from providers with varying message formats, use message-based detection:
| Scenario | Detection approach | User action |
|---|---|---|
| Card declined | error.message contains "declined" | Try a different card or contact bank. |
| Insufficient funds | error.message contains "insufficient funds" | Use a different payment method. |
| Expired card | error.message contains "expired" | Use a different card. |
| Invalid CVV | error.message contains "CVV" or "security code" | Check security code and retry. |
| Invalid card number | error.message contains "card number" or "invalid number" | Check card number and retry. |
| Invalid expiry | error.message contains "expiry" or "expiration" | Check expiry date and retry. |
Example handling:
onError = { paymentMethod, error ->
if (error.errorCode == "SDK1115") {
when {
error.message?.contains("declined", ignoreCase = true) == true -> {
showErrorMessage(
"Your card was declined. Please try a different card or " +
"contact your bank for more information."
)
offerAlternativePaymentMethods()
}
error.message?.contains("insufficient funds", ignoreCase = true) == true -> {
showErrorMessage(
"Insufficient funds. Please use a different payment method."
)
offerAlternativePaymentMethods()
}
error.message?.contains("expired", ignoreCase = true) == true -> {
showErrorMessage(
"This card has expired. Please use a different card."
)
}
error.message?.contains("cvv", ignoreCase = true) == true ||
error.message?.contains("security code", ignoreCase = true) == true -> {
showErrorMessage(
"Invalid security code. Please check the CVV on the back of " +
"your card and try again."
)
}
else -> {
showErrorMessage(
"Card payment failed. Please check your details and try again."
)
}
}
} else if (error.errorCode == "SDK1116") {
showErrorMessage(
"PayPal payment failed. Please try again or use a different payment method."
)
offerAlternativePaymentMethods()
} else if (error.errorCode == "SDK1117") {
showErrorMessage(
"Google Pay payment failed. Please try again or use a different payment method."
)
offerAlternativePaymentMethods()
} else if (error.errorCode == "SDK1126" || paymentMethod == PaymentMethod.AEROPAY) {
when (error.errorCode) {
"SDK0114" -> showErrorMessage("Pay by Bank is only available for e-commerce checkout.")
"SDK0116" -> showErrorMessage("Pay by Bank only supports USD.")
// Create/render failures surface as SDK1125; underlying SDK0113/SDK0115 may be on error.cause
"SDK1125" ->
showErrorMessage("Pay by Bank is unavailable. Please choose another payment method.")
"SDK1300" -> showErrorMessage(
"Pay by Bank could not start. Check shopper name, email, and US phone (+1 + 10 digits), " +
"or set methodConfig.aeropay.userId."
)
"SDK1126" -> showErrorMessage("Pay by Bank payment failed. Please try again.")
else -> showErrorMessage(error.message)
}
offerAlternativePaymentMethods()
}
}For Aeropay, you can also branch on paymentMethod == PaymentMethod.AEROPAY and handle SDK0114 (entry type), SDK0116 (currency), SDK1300 (invalid shopper data at load), SDK1125 (create failure), and SDK1126 (payment fallback). See Aeropay.
Errors related to 3D Secure (3DS) authentication for card payments.
| Error code | Description | User action |
|---|---|---|
SDK1113 | Drop-in authentication gate failed (card 3DS / integrated authentication, or Google Pay auth evaluation when authentication cannot proceed). | Try again or use a different payment method. |
Authentication timeout and cancellation are also reported through error.message. Check the message content for these scenarios:
- Timeout:
error.messagecontains "timeout" - Cancelled:
error.messagecontains "cancel"
Example handling:
onError = { paymentMethod, error ->
if (error.errorCode == "SDK1113" ||
error.message?.contains("authentication", ignoreCase = true) == true) {
when {
error.message?.contains("timeout", ignoreCase = true) == true -> {
showErrorMessage(
"3D Secure authentication timed out. Please check your " +
"internet connection and try again."
)
showRetryButton()
}
error.message?.contains("cancel", ignoreCase = true) == true -> {
showErrorMessage(
"Authentication was cancelled. Please try again to complete " +
"your payment."
)
showInfoMessage("You can retry your payment when ready.")
}
else -> {
showErrorMessage(
"Authentication failed. Please try again or use a " +
"different payment method."
)
analytics.track("3ds_authentication_failed", mapOf(
"timestamp" to System.currentTimeMillis()
))
}
}
}
}Errors that occur during payment authorisation.
| Error code | Description | Solution |
|---|---|---|
SDK1114 | Payment authorisation failed (card and Google Pay paths). | Check transaction details and retry. Not the same as Aeropay entry-type SDK0114. |
Errors related to network connectivity, session state, and system availability.
| Error code or detection | Description | User action |
|---|---|---|
SDK0500 or SDK0550 | Network failure. Runtime Drop-in paths often surface SDK0500 via NetworkSdkException. SdkErrorCodes.NETWORK_ERROR is SDK0550. When errorCode == "SDK0500", also check the message. The same code is used for invalid transaction amount in some contexts. | Check connection and retry. |
| Message-based | error.message contains "session" or "expired" | Refresh page and retry. |
| Message-based | error.message contains "timeout" | Check connection and retry. |
| Message-based | error.message contains "unavailable" or "service" | Try again later. |
SDK01XX or SDK02XX | Configuration error codes (01XX is SDK, 02XX is Component) | Contact support. For Aeropay, SDK0114 (non-Ecom) and SDK0116 (non-USD) surface directly via onError. Blank credentials (SDK0113) and missing intent (SDK0115) can also appear as Drop-in SDK1125. See Aeropay. |
Example handling:
onError = { paymentMethod, error ->
when {
error.errorCode == SdkErrorCodes.NETWORK_ERROR ||
(error.errorCode == "SDK0500" &&
error.message?.contains("network", ignoreCase = true) == true) -> {
showErrorMessage(
"Network connection issue. Please check your internet connection " +
"and try again."
)
showRetryButton()
}
error.message?.contains("Session has expired", ignoreCase = true) == true -> {
showErrorMessage(
"Your payment session has expired. Please refresh the page and " +
"try again."
)
showRefreshButton()
}
error.message?.contains("timeout", ignoreCase = true) == true -> {
showErrorMessage(
"Request timed out. Please check your connection and try again."
)
showRetryButton()
}
error.message?.contains("unavailable", ignoreCase = true) == true ||
error.message?.contains("service", ignoreCase = true) == true -> {
showErrorMessage(
"Payment service is temporarily unavailable. Please try again in " +
"a few minutes."
)
}
error.errorCode.startsWith("SDK01") || error.errorCode.startsWith("SDK02") -> {
showErrorMessage(
"Payment configuration error. Please contact support for assistance."
)
logger.critical("Configuration error", mapOf(
"error_code" to error.errorCode,
"message" to error.message
))
}
}
}The simplest pattern logs the error and shows a user-friendly message:
import android.util.Log
import com.pxp.checkout.checkoutdropin.CheckoutDropIn
import com.pxp.checkout.checkoutdropin.types.CheckoutDropInConfig
import com.pxp.checkout.exceptions.BaseSdkException
val checkoutDropIn = CheckoutDropIn.initialize(
context = context,
config = CheckoutDropInConfig(
// ... other config
onError = { paymentMethod, error ->
Log.e("CheckoutDropIn", "Payment error: ${error.errorCode}: ${error.message}")
showErrorNotification(error.message ?: "Payment failed. Please try again.")
enablePaymentButton()
}
)
)Implement retry logic, alternative payment methods, and error categorisation:
import com.pxp.checkout.exceptions.SdkErrorCodes
private const val MAX_RETRIES = 3
var retryCount = 0
val checkoutDropIn = CheckoutDropIn.initialize(
context = context,
config = CheckoutDropInConfig(
// ... other config
onError = { paymentMethod, error ->
logger.error("Payment error", mapOf(
"error_code" to error.errorCode,
"message" to error.message,
"payment_method" to (paymentMethod?.value ?: "none")
))
val isNetworkError =
error.errorCode == SdkErrorCodes.NETWORK_ERROR || // SDK0550
(error.errorCode == "SDK0500" &&
(error.message?.contains("network", ignoreCase = true) == true))
val isTimeout = error.message?.contains("timeout", ignoreCase = true) == true
val isRetryable = isNetworkError || isTimeout ||
error.message?.contains("unavailable", ignoreCase = true) == true
if (isRetryable && retryCount < MAX_RETRIES) {
retryCount++
showWarningMessage(
"Connection issue (attempt $retryCount of $MAX_RETRIES). " +
"Please try your payment again."
) {
retryPayment()
}
} else {
retryCount = 0
val userMessage = when {
error.errorCode == SdkErrorCodes.NETWORK_ERROR ||
(error.errorCode == "SDK0500" &&
error.message?.contains("network", ignoreCase = true) == true) ->
"Network connection issue. Please check your internet connection and try again."
error.errorCode == "SDK1113" ->
"Authentication failed. Please try again or use a different payment method."
error.errorCode == "SDK1115" -> {
when {
error.message?.contains("declined", ignoreCase = true) == true ->
"Your card was declined. Please try a different card."
error.message?.contains("insufficient funds", ignoreCase = true) == true ->
"Insufficient funds. Please use a different payment method."
else ->
"Card payment failed. Please check your details and try again."
}
}
error.errorCode == "SDK1116" ->
"PayPal payment failed. Please try again or use a different payment method."
error.errorCode == "SDK1117" ->
"Google Pay payment failed. Please try again or use a different payment method."
error.errorCode == "SDK1125" ->
"Aeropay could not be loaded. Check session credentials and intent."
error.errorCode == "SDK1300" ->
"Pay by Bank could not start. Check shopper name, email, and US phone (+1 + 10 digits), or set methodConfig.aeropay.userId."
error.errorCode == "SDK1126" ->
"Pay by Bank payment failed. Please try again or use a different payment method."
else -> error.message
}
showErrorMessage(userMessage)
if (error.errorCode == "SDK1115" ||
error.errorCode == "SDK1116" ||
error.errorCode == "SDK1117" ||
error.errorCode == "SDK1125" ||
error.errorCode == "SDK1126") {
offerAlternativePaymentMethods()
}
enablePaymentButton()
}
}
)
)Branch on payment method when you need Aeropay-specific messaging:
import com.pxp.checkout.checkoutdropin.types.PaymentMethod
onError = { paymentMethod, error ->
if (paymentMethod == PaymentMethod.AEROPAY) {
when (error.errorCode) {
"SDK0114" -> showErrorMessage("Pay by Bank is only available for e-commerce checkout.")
"SDK0116" -> showErrorMessage("Pay by Bank only supports USD.")
"SDK1300" -> showErrorMessage("Invalid shopper details: ${error.message}")
"SDK1125" -> showErrorMessage("Pay by Bank is unavailable. Please choose another method.")
"SDK1126" -> showErrorMessage("Pay by Bank payment failed. Please try again.")
else -> showErrorMessage(error.message)
}
}
}Always verify successful payments on your backend before fulfilling orders. Frontend callbacks can be manipulated. See Events for onSuccess verification guidance.