{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["sub-heading","br","details","admonition"]},"type":"markdown"},"seo":{"title":"Error handling","description":"Transform your commerce with PXP's unified platform—seamless payments, real-time insights, and global growth in one powerful integration.","lang":"en-UK","siteUrl":"https://developer.pxp.io","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"error-handling","__idx":0},"children":["Error handling"]},{"$$mdtype":"Tag","name":"SubHeading","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Understand error types, handle payment failures, and implement proper error recovery."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":1},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Drop-in provides comprehensive error handling through the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," callback. All payment failures, validation errors, and SDK exceptions are caught and delivered through this unified interface, making error handling consistent across all payment methods."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-callback","__idx":2},"children":["Error callback"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All errors are delivered through the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," callback:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","header":{"controls":{"copy":{}}},"source":"import com.pxp.checkout.checkoutdropin.CheckoutDropIn\nimport com.pxp.checkout.exceptions.BaseSdkException\n\nval checkoutDropIn = CheckoutDropIn.initialize(\n    context = context,\n    config = CheckoutDropInConfig(\n        // ... other config\n        onError = { error ->\n            Log.e(\"CheckoutDropIn\", \"Payment failed: ${error.message}\")\n            Log.e(\"CheckoutDropIn\", \"Error code: ${error.code}\")\n            \n            // Handle the error\n            showErrorMessage(error.message)\n        }\n    )\n)\n","lang":"kotlin"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"error-object-structure","__idx":3},"children":["Error object structure"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Property"},"children":["Property"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["String"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Human-readable error message describing what went wrong."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["String"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["SDK error code in format ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK####"]}," (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'SDK1113'"]}," for authentication failed, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'SDK0500'"]}," for network error). Use this for programmatic error handling."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-categories","__idx":4},"children":["Error categories"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Errors are organised into four main categories based on their source and nature."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"configuration-errors","__idx":5},"children":["Configuration errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Errors that occur during SDK initialisation or component rendering due to invalid configuration."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Exception"},"children":["Exception"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Error code"},"children":["Error code"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Solution"},"children":["Solution"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutDropInConfigNotFoundSdkException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1100"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Drop-in configuration not found or invalid."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Verify initialisation parameters."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutDropInFailedToRenderCardSdkException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1101"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Failed to render card component."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Check session configuration for card support."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutDropInFailedToRenderPaypalSdkException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1102"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Failed to render PayPal button."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Verify PayPal is enabled in session."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutDropInFailedToRenderGooglePaySdkException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1103"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Failed to render Google Pay button."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Check Google Pay configuration."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutDropInInvalidPaypalEntryTypeSdkException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1118"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["PayPal only supports Ecom entry type."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Change ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["entryType"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EntryType.Ecom"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example handling:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","header":{"controls":{"copy":{}}},"source":"onError = { error ->\n    if (error.code.startsWith(\"SDK110\")) {\n        Log.e(\"CheckoutDropIn\", \"Rendering error: ${error.message}\")\n        \n        // Log to monitoring\n        logger.error(\"Rendering error\", mapOf(\n            \"error_code\" to error.code,\n            \"message\" to error.message\n        ))\n        \n        // Show generic error to user\n        showErrorMessage(\n            \"We're having trouble loading payment options. \" +\n            \"Please refresh the page or contact support.\"\n        )\n    }\n}\n","lang":"kotlin"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"payment-errors","__idx":6},"children":["Payment errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Errors that occur during payment processing for specific payment methods."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Exception"},"children":["Exception"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Error code"},"children":["Error code"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"User action"},"children":["User action"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutDropInCardPaymentFailedSdkException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1115"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Card payment failed (see detection patterns below)."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["See card-specific patterns below."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutDropInPaypalPaymentFailedSdkException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1116"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["PayPal transaction failed."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Try again or use different method."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutDropInGooglePayPaymentFailedSdkException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1117"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Google Pay transaction failed."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Try again or use different method."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"card-specific-error-detection-patterns","__idx":7},"children":["Card-specific error detection patterns"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Since card errors come from providers with varying message formats, use message-based detection:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Scenario"},"children":["Scenario"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Detection approach"},"children":["Detection approach"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"User action"},"children":["User action"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Card declined"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.message"]}," contains \"declined\""]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Try a different card or contact bank."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Insufficient funds"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.message"]}," contains \"insufficient funds\""]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Use a different payment method."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Expired card"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.message"]}," contains \"expired\""]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Use a different card."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Invalid CVV"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.message"]}," contains \"CVV\" or \"security code\""]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Check security code and retry."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Invalid card number"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.message"]}," contains \"card number\" or \"invalid number\""]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Check card number and retry."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Invalid expiry"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.message"]}," contains \"expiry\" or \"expiration\""]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Check expiry date and retry."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example handling:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","header":{"controls":{"copy":{}}},"source":"onError = { error ->\n    // Card-specific errors (message-based detection)\n    if (error.code == \"SDK1115\") {\n        // Card payment failed - check message for specifics\n        when {\n            error.message.contains(\"declined\", ignoreCase = true) -> {\n                showErrorMessage(\n                    \"Your card was declined. Please try a different card or \" +\n                    \"contact your bank for more information.\"\n                )\n                offerAlternativePaymentMethods()\n            }\n            error.message.contains(\"insufficient funds\", ignoreCase = true) -> {\n                showErrorMessage(\n                    \"Insufficient funds. Please use a different payment method.\"\n                )\n                offerAlternativePaymentMethods()\n            }\n            error.message.contains(\"expired\", ignoreCase = true) -> {\n                showErrorMessage(\n                    \"This card has expired. Please use a different card.\"\n                )\n            }\n            error.message.contains(\"cvv\", ignoreCase = true) || \n            error.message.contains(\"security code\", ignoreCase = true) -> {\n                showErrorMessage(\n                    \"Invalid security code. Please check the CVV on the back of \" +\n                    \"your card and try again.\"\n                )\n                // Keep same payment method selected for retry\n            }\n            else -> {\n                showErrorMessage(\n                    \"Card payment failed. Please check your details and try again.\"\n                )\n            }\n        }\n    }\n    \n    // Wallet payment errors\n    else if (error.code == \"SDK1116\") {\n        showErrorMessage(\n            \"PayPal payment failed. Please try again or use a different payment method.\"\n        )\n        offerAlternativePaymentMethods()\n    } else if (error.code == \"SDK1117\") {\n        showErrorMessage(\n            \"Google Pay payment failed. Please try again or use a different payment method.\"\n        )\n        offerAlternativePaymentMethods()\n    }\n}\n","lang":"kotlin"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"authentication-errors","__idx":8},"children":["Authentication errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Errors related to 3D Secure (3DS) authentication for card payments."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Exception"},"children":["Exception"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Error code"},"children":["Error code"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"User action"},"children":["User action"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutDropInAuthenticationFailedSdkException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1113"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["3DS authentication failed."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Try again or use different card."]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Authentication timeout and cancellation are also reported through ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.message"]},". Check the message content for these scenarios:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Timeout: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.message"]}," contains \"timeout\""]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Cancelled: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.message"]}," contains \"cancel\""]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example handling:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","header":{"controls":{"copy":{}}},"source":"onError = { error ->\n    if (error.code == \"SDK1113\" || \n        error.message.contains(\"authentication\", ignoreCase = true)) {\n        when {\n            error.message.contains(\"timeout\", ignoreCase = true) -> {\n                showErrorMessage(\n                    \"3D Secure authentication timed out. Please check your \" +\n                    \"internet connection and try again.\"\n                )\n                \n                // Offer retry\n                showRetryButton()\n            }\n            error.message.contains(\"cancel\", ignoreCase = true) -> {\n                showErrorMessage(\n                    \"Authentication was cancelled. Please try again to complete \" +\n                    \"your payment.\"\n                )\n                \n                // Don't show error as prominently - user intentionally cancelled\n                showInfoMessage(\"You can retry your payment when ready.\")\n            }\n            else -> {\n                showErrorMessage(\n                    \"3D Secure authentication failed. Please try again or use a \" +\n                    \"different card.\"\n                )\n                \n                // Track authentication failures\n                analytics.track(\"3ds_authentication_failed\", mapOf(\n                    \"timestamp\" to System.currentTimeMillis()\n                ))\n            }\n        }\n    }\n}\n","lang":"kotlin"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"authorisation-errors","__idx":9},"children":["Authorisation errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Errors that occur during payment authorisation."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Exception"},"children":["Exception"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Error code"},"children":["Error code"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Solution"},"children":["Solution"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutDropInAuthorisationFailedSdkException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1114"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Payment authorisation failed."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Check transaction details and retry."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"system-errors","__idx":10},"children":["System errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Errors related to network connectivity, session state, and system availability."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Error code"},"children":["Error code"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Detection approach"},"children":["Detection approach"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"User action"},"children":["User action"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0500"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Network error code"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Check connection and retry."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Message-based"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.message"]}," contains \"session\" or \"expired\""]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Refresh page and retry."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Message-based"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.message"]}," contains \"timeout\""]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Check connection and retry."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Message-based"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.message"]}," contains \"unavailable\" or \"service\""]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Try again later."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK01XX"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK02XX"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Configuration error codes (01XX = SDK, 02XX = Component)"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Contact support."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example handling:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","header":{"controls":{"copy":{}}},"source":"onError = { error ->\n    // Network and session errors\n    when {\n        error.code == \"SDK0500\" -> {\n            showErrorMessage(\n                \"Network connection issue. Please check your internet connection \" +\n                \"and try again.\"\n            )\n            showRetryButton()\n        }\n        error.message.contains(\"session\", ignoreCase = true) || \n        error.message.contains(\"expired\", ignoreCase = true) -> {\n            showErrorMessage(\n                \"Your payment session has expired. Please refresh the page and \" +\n                \"try again.\"\n            )\n            showRefreshButton()\n        }\n        error.message.contains(\"timeout\", ignoreCase = true) -> {\n            showErrorMessage(\n                \"Request timed out. Please check your connection and try again.\"\n            )\n            showRetryButton()\n        }\n        error.message.contains(\"unavailable\", ignoreCase = true) || \n        error.message.contains(\"service\", ignoreCase = true) -> {\n            showErrorMessage(\n                \"Payment service is temporarily unavailable. Please try again in \" +\n                \"a few minutes.\"\n            )\n        }\n        error.code.startsWith(\"SDK01\") || error.code.startsWith(\"SDK02\") -> {\n            showErrorMessage(\n                \"Payment configuration error. Please contact support for assistance.\"\n            )\n            \n            // Log critical error\n            logger.critical(\"Configuration error\", mapOf(\n                \"error_code\" to error.code,\n                \"message\" to error.message\n            ))\n        }\n    }\n}\n","lang":"kotlin"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-handling-patterns","__idx":11},"children":["Error handling patterns"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"basic-error-handling","__idx":12},"children":["Basic error handling"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The simplest error handling pattern shows user-friendly messages and logs errors for debugging."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","header":{"controls":{"copy":{}}},"source":"import com.pxp.checkout.exceptions.BaseSdkException\n\nval checkoutDropIn = CheckoutDropIn.initialize(\n    context = context,\n    config = CheckoutDropInConfig(\n        // ... other config\n        onError = { error ->\n            // Log error for debugging\n            Log.e(\"CheckoutDropIn\", \"Payment error: ${error.code} - ${error.message}\")\n            \n            // Show user-friendly message\n            showErrorNotification(error.message ?: \"Payment failed. Please try again.\")\n            \n            // Re-enable payment button\n            enablePaymentButton()\n        }\n    )\n)\n","lang":"kotlin"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"advanced-error-handling-with-recovery","__idx":13},"children":["Advanced error handling with recovery"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Implement retry logic, alternative payment methods, and error categorisation."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","header":{"controls":{"copy":{}}},"source":"var retryCount = 0\nconst val MAX_RETRIES = 3\n\nval checkoutDropIn = CheckoutDropIn.initialize(\n    context = context,\n    config = CheckoutDropInConfig(\n        // ... other config\n        onError = { error ->\n            // Log to monitoring service\n            logErrorToMonitoring(mapOf(\n                \"category\" to \"payment_error\",\n                \"error_code\" to error.code,\n                \"message\" to error.message,\n                \"user_agent\" to Build.MODEL,\n                \"timestamp\" to System.currentTimeMillis()\n            ))\n            \n            // Track analytics\n            analytics.track(\"payment_failed\", mapOf(\n                \"error_code\" to error.code,\n                \"error_message\" to error.message,\n                \"retry_count\" to retryCount\n            ))\n            \n            // Check if error is retryable (network issues, timeouts)\n            val isNetworkError = error.code == \"SDK0500\"\n            val isTimeout = error.message.contains(\"timeout\", ignoreCase = true)\n            val isRetryable = isNetworkError || isTimeout || \n                             error.message.contains(\"unavailable\", ignoreCase = true)\n            \n            // Implement retry logic\n            if (isRetryable && retryCount < MAX_RETRIES) {\n                retryCount++\n                \n                showWarningMessage(\n                    \"Connection issue (attempt $retryCount/$MAX_RETRIES). \" +\n                    \"Please try your payment again.\"\n                ) {\n                    // Retry the payment\n                    retryPayment()\n                }\n                return@CheckoutDropInConfig\n            }\n            \n            // Reset retry count for non-retryable errors\n            retryCount = 0\n            \n            // Show user-friendly error messages based on error code and message\n            val userMessage = when {\n                // Check by SDK error code\n                error.code == \"SDK0500\" ->\n                    \"Network connection issue. Please check your internet connection and try again.\"\n                error.code == \"SDK1113\" ->\n                    \"3D Secure authentication failed. Please try again or use a different card.\"\n                error.code == \"SDK1114\" ->\n                    \"Payment authorisation failed. Please check your details and try again.\"\n                error.code == \"SDK1115\" -> {\n                    // Card payment failed - check message for specifics\n                    when {\n                        error.message.contains(\"declined\", ignoreCase = true) ->\n                            \"Your card was declined. Please try a different card or contact your bank.\"\n                        error.message.contains(\"insufficient funds\", ignoreCase = true) ->\n                            \"Insufficient funds. Please use a different payment method.\"\n                        error.message.contains(\"expired\", ignoreCase = true) ->\n                            \"This card has expired. Please use a different card.\"\n                        error.message.contains(\"cvv\", ignoreCase = true) || \n                        error.message.contains(\"security code\", ignoreCase = true) ->\n                            \"Invalid security code. Please check the CVV on your card and try again.\"\n                        error.message.contains(\"card number\", ignoreCase = true) ->\n                            \"Invalid card number. Please check and try again.\"\n                        error.message.contains(\"expiry\", ignoreCase = true) || \n                        error.message.contains(\"expiration\", ignoreCase = true) ->\n                            \"Invalid expiry date. Please check and try again.\"\n                        else ->\n                            \"Card payment failed. Please check your details and try again.\"\n                    }\n                }\n                error.code == \"SDK1116\" ->\n                    \"PayPal payment failed. Please try again or use a different payment method.\"\n                error.code == \"SDK1117\" ->\n                    \"Google Pay payment failed. Please try again or use a different payment method.\"\n                // Check by message content for scenarios without specific codes\n                error.message.contains(\"timeout\", ignoreCase = true) ->\n                    \"Request timed out. Please check your internet connection and try again.\"\n                error.message.contains(\"session\", ignoreCase = true) || \n                error.message.contains(\"expired\", ignoreCase = true) ->\n                    \"Your payment session has expired. Please refresh the page.\"\n                error.message.contains(\"unavailable\", ignoreCase = true) ->\n                    \"Payment service temporarily unavailable. Please try again in a few minutes.\"\n                error.code.startsWith(\"SDK01\") || error.code.startsWith(\"SDK02\") ->\n                    \"Payment configuration error. Please contact support.\"\n                else -> error.message\n            }\n            \n            showErrorMessage(userMessage)\n            \n            // Offer alternative payment methods for certain errors\n            val shouldOfferAlternatives = \n                error.code == \"SDK1115\" || // Card payment failed\n                error.code == \"SDK1116\" || // PayPal failed\n                error.code == \"SDK1117\" || // Google Pay failed\n                error.message.contains(\"declined\", ignoreCase = true) ||\n                error.message.contains(\"insufficient funds\", ignoreCase = true)\n            \n            if (shouldOfferAlternatives) {\n                showAlternativePaymentMethods()\n            }\n            \n            // Show retry button for network/timeout errors\n            val shouldShowRetry = \n                error.code == \"SDK0500\" ||\n                error.message.contains(\"timeout\", ignoreCase = true) ||\n                error.message.contains(\"unavailable\", ignoreCase = true)\n            \n            if (shouldShowRetry) {\n                showRetryButton()\n            }\n            \n            // Show refresh button for session errors\n            if (error.message.contains(\"session\", ignoreCase = true) || \n                error.message.contains(\"expired\", ignoreCase = true)) {\n                showRefreshButton()\n            }\n            \n            // Re-enable payment form\n            enablePaymentForm()\n        }\n    )\n)\n","lang":"kotlin"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"error-logging-to-monitoring-service","__idx":14},"children":["Error logging to monitoring service"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Integrate with monitoring services like Firebase Crashlytics or custom logging."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","header":{"controls":{"copy":{}}},"source":"import com.google.firebase.crashlytics.FirebaseCrashlytics\n\nval checkoutDropIn = CheckoutDropIn.initialize(\n    context = context,\n    config = CheckoutDropInConfig(\n        // ... other config\n        onError = { error ->\n            // Log to Firebase Crashlytics\n            FirebaseCrashlytics.getInstance().apply {\n                setCustomKey(\"error_code\", error.code)\n                setCustomKey(\"error_message\", error.message)\n                recordException(Exception(\"Payment error: ${error.code} - ${error.message}\"))\n            }\n            \n            // Log to custom monitoring service\n            lifecycleScope.launch {\n                try {\n                    logErrorToBackend(mapOf(\n                        \"type\" to \"payment_error\",\n                        \"error_code\" to error.code,\n                        \"message\" to error.message,\n                        \"url\" to currentActivity,\n                        \"device_model\" to Build.MODEL,\n                        \"os_version\" to Build.VERSION.RELEASE,\n                        \"timestamp\" to System.currentTimeMillis()\n                    ))\n                } catch (e: Exception) {\n                    // Silently fail - don't disrupt user experience\n                    Log.e(\"CheckoutDropIn\", \"Failed to log error\", e)\n                }\n            }\n            \n            // Show error to user\n            showErrorMessage(error.message)\n        }\n    )\n)\n","lang":"kotlin"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"complete-error-handling-example","__idx":15},"children":["Complete error handling example"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here's a production-ready error handling implementation:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","header":{"controls":{"copy":{}}},"source":"import com.pxp.checkout.checkoutdropin.CheckoutDropIn\nimport com.pxp.checkout.exceptions.BaseSdkException\nimport com.google.firebase.crashlytics.FirebaseCrashlytics\n\nvar retryCount = 0\nconst val MAX_RETRIES = 3\n\nval checkoutDropIn = CheckoutDropIn.initialize(\n    context = context,\n    config = CheckoutDropInConfig(\n        // ... other config\n        onError = { error ->\n            // 1. Log error for debugging\n            Log.e(\"CheckoutDropIn\", \"Payment error: ${error.code} - ${error.message}\")\n            \n            // 2. Send to monitoring service\n            FirebaseCrashlytics.getInstance().apply {\n                setCustomKey(\"error_code\", error.code)\n                setCustomKey(\"error_message\", error.message)\n                setCustomKey(\"retry_count\", retryCount)\n                recordException(Exception(\"Payment error: ${error.code}\"))\n            }\n            \n            // 3. Track analytics\n            analytics.track(\"payment_failed\", mapOf(\n                \"error_code\" to error.code,\n                \"error_message\" to error.message,\n                \"retry_count\" to retryCount,\n                \"timestamp\" to System.currentTimeMillis()\n            ))\n            \n            // 4. Clear any loading state\n            hideLoadingOverlay()\n            \n            // 5. Implement retry logic for transient errors\n            val isNetworkError = error.code == \"SDK0500\"\n            val isTimeout = error.message.contains(\"timeout\", ignoreCase = true)\n            val isUnavailable = error.message.contains(\"unavailable\", ignoreCase = true)\n            \n            if ((isNetworkError || isTimeout || isUnavailable) && retryCount < MAX_RETRIES) {\n                retryCount++\n                \n                showNotification(\n                    type = NotificationType.WARNING,\n                    message = \"Connection issue (attempt $retryCount/$MAX_RETRIES). \" +\n                             \"Please try again.\"\n                ) {\n                    retryPayment()\n                }\n                return@CheckoutDropInConfig\n            }\n            \n            // Reset retry count\n            retryCount = 0\n            \n            // 6. Show user-friendly error messages\n            val userMessage = when {\n                // Check by SDK error code\n                error.code == \"SDK0500\" ->\n                    \"Network error. Please check your connection and try again.\"\n                error.code == \"SDK1113\" ->\n                    \"3D Secure authentication failed. Please try again.\"\n                error.code == \"SDK1114\" ->\n                    \"Payment authorisation failed. Please check your details and try again.\"\n                error.code == \"SDK1115\" -> {\n                    // Card payment failed - check message\n                    when {\n                        error.message.contains(\"declined\", ignoreCase = true) ->\n                            \"Your card was declined. Please try a different card or contact your bank.\"\n                        error.message.contains(\"insufficient funds\", ignoreCase = true) ->\n                            \"Insufficient funds. Please use a different payment method.\"\n                        error.message.contains(\"expired\", ignoreCase = true) ->\n                            \"This card has expired. Please use a different card.\"\n                        error.message.contains(\"cvv\", ignoreCase = true) ->\n                            \"Invalid security code. Please check and try again.\"\n                        else ->\n                            \"Card payment failed. Please check your details and try again.\"\n                    }\n                }\n                error.code == \"SDK1116\" ->\n                    \"PayPal payment failed. Please try again or use a different method.\"\n                error.code == \"SDK1117\" ->\n                    \"Google Pay payment failed. Please try again or use a different method.\"\n                error.message.contains(\"session\", ignoreCase = true) || \n                error.message.contains(\"expired\", ignoreCase = true) ->\n                    \"Session expired. Please refresh the page.\"\n                error.code.startsWith(\"SDK01\") || error.code.startsWith(\"SDK02\") ->\n                    \"Configuration error. Please contact support.\"\n                else -> error.message\n            }\n            \n            // 7. Show error to user\n            showNotification(\n                type = NotificationType.ERROR,\n                title = \"Payment failed\",\n                message = userMessage,\n                duration = 8000\n            )\n            \n            // 8. Offer recovery options\n            val shouldOfferAlternatives = \n                error.code == \"SDK1115\" || \n                error.code == \"SDK1116\" || \n                error.code == \"SDK1117\" ||\n                error.message.contains(\"declined\", ignoreCase = true) ||\n                error.message.contains(\"insufficient funds\", ignoreCase = true)\n            \n            if (shouldOfferAlternatives) {\n                showAlternativePaymentMethods()\n            }\n            \n            val shouldShowRetry = \n                error.code == \"SDK0500\" ||\n                error.message.contains(\"timeout\", ignoreCase = true)\n            \n            if (shouldShowRetry) {\n                showRetryButton()\n            }\n            \n            if (error.message.contains(\"session\", ignoreCase = true) || \n                error.message.contains(\"expired\", ignoreCase = true)) {\n                showRefreshButton()\n            }\n            \n            // 9. Re-enable UI\n            enablePaymentForm()\n            enableSubmitButton()\n        }\n    )\n)\n","lang":"kotlin"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For specific error codes and exceptions related to individual payment methods, see the payment method documentation: ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/drop-in/android/cards"},"children":["Card"]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/drop-in/android/paypal"},"children":["PayPal"]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/drop-in/android/google-pay"},"children":["Google Pay"]},"."]}]}]},"headings":[{"value":"Error handling","id":"error-handling","depth":1},{"value":"Overview","id":"overview","depth":2},{"value":"Error callback","id":"error-callback","depth":2},{"value":"Error object structure","id":"error-object-structure","depth":3},{"value":"Error categories","id":"error-categories","depth":2},{"value":"Configuration errors","id":"configuration-errors","depth":3},{"value":"Payment errors","id":"payment-errors","depth":3},{"value":"Card-specific error detection patterns","id":"card-specific-error-detection-patterns","depth":4},{"value":"Authentication errors","id":"authentication-errors","depth":3},{"value":"Authorisation errors","id":"authorisation-errors","depth":3},{"value":"System errors","id":"system-errors","depth":3},{"value":"Error handling patterns","id":"error-handling-patterns","depth":2},{"value":"Basic error handling","id":"basic-error-handling","depth":3},{"value":"Advanced error handling with recovery","id":"advanced-error-handling-with-recovery","depth":3},{"value":"Error logging to monitoring service","id":"error-logging-to-monitoring-service","depth":3},{"value":"Complete error handling example","id":"complete-error-handling-example","depth":2}],"frontmatter":{"seo":{"title":"Error handling"}},"lastModified":"2026-05-20T14:05:06.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/checkout/drop-in/android/error-handling","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}