{"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 reports almost all errors through your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," callback. The only exceptions are two configuration checks that throw when you create Drop-in: empty ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sessionId"]}," or empty ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hmacKey"]},". Wrap ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutDropIn(config:)"]}," in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["do/catch"]}," to handle those."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Failures during ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["await dropIn.create()"]},", rendering, and payment processing do not throw. They arrive in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," instead. Plan your integration around that callback for runtime recovery and user messaging."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-callback","__idx":2},"children":["Error callback"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Register ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutDropInConfig"]}," alongside your other callbacks. Use it for every error that happens after you have constructed Drop-in, including render failures during ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create()"]}," and payment failures during checkout."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Reserve ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["do/catch"]}," for initialisation only. It catches the two missing-session exceptions above. Do not expect payment or render errors to bubble up as Swift throws."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"import PXPCheckoutSDK\n\ndo {\n    let config = CheckoutDropInConfig(\n        // ... other config\n        onError: { paymentMethod, error in\n            print(\"Payment failed: \\(error.errorMessage)\")\n            print(\"Error code: \\(error.errorCode)\")\n            \n            // Handle the error\n            showErrorMessage(error.errorMessage)\n        }\n    )\n    \n    let dropIn = try CheckoutDropIn(config: config)\n} catch {\n    // Initialisation failed: sessionId or hmacKey missing\n    print(\"Failed to initialise Drop-in: \\(error.localizedDescription)\")\n    showErrorMessage(\"Failed to load payment form. Please contact support.\")\n}\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"error-object-structure","__idx":3},"children":["Error object structure"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each error passed to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," is a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BaseSdkException"]},". Inspect these properties:"]},{"$$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":["errorMessage"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["String"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["A human-readable description of what went wrong."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorCode"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["String"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["An SDK code in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK####"]}," format (for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1114"]}," for authentication failure or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0500"]}," for a network error). Card and Paze authorisation failures may also return provider-specific codes through ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutDropInFailedSubmitResultSdkException"]},". Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorCode"]}," to branch your handling logic."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentMethod"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["DropInPaymentMethod?"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The payment method involved, or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nil"]}," when the error is not tied to a specific method (for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1100"]}," during ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create()"]},"). Raw values: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Card"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Paypal"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ApplePay"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-categories","__idx":4},"children":["Error categories"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Errors are grouped below by source and type."]},{"$$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 Drop-in component rendering."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"initialisation-errors-throws","__idx":6},"children":["Initialisation errors (throws)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These exceptions throw from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutDropIn(config:)"]}," when session credentials are missing:"]},{"$$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":["MissingConfigSessionIdException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0103"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["session.sessionId"]}," is empty."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Provide a valid ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SessionData"]}," object from your backend."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MissingConfigSessionHmackeyException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0104"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["session.hmacKey"]}," is empty."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Provide a valid HMAC key in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SessionData"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Other ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK01xx"]}," validation errors (for example missing funding types or intents for a component) surface during ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create()"]}," through ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]},", often wrapped in a render exception."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"drop-in-render-and-update-errors","__idx":7},"children":["Drop-in render and update errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These exceptions are delivered through ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]},", typically during ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["await dropIn.create()"]}," or when Drop-in updates session state. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentMethod"]}," is set when the failure is tied to a specific method."]},{"$$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":["Failed to retrieve Checkout Drop-In site configuration."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Check portal setup and network connectivity; retry ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create()"]},"."]}]},{"$$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 the card component."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Check session card configuration and funding types."]}]},{"$$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 the PayPal button."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Verify PayPal is enabled in the session."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutDropInFailedToRenderApplePaySdkException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1104"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Failed to render the Apple Pay button."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Check Apple Pay session and device configuration."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutDropInFailedToRenderCardOnFileSdkException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1105"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Failed to render saved cards."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Check token vault and shopper configuration."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutDropInFailedToRenderBillingAddressSdkException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1106"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Failed to render billing address fields."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Review billing address component configuration."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutDropInFailedToRenderCardBrandSelectorSdkException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1107"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Failed to render the card brand selector."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Check accepted card networks in session or config."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutDropInFailedToRenderCardSubmitSdkException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1108"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Failed to render the card submit button."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Check card component wiring and session."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutDropInFailedToRenderCardCofSubmitSdkException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1109"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Failed to render saved-card submit."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Check card-on-file configuration."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutDropInFailedToRenderCardConsentSdkException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1110"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Failed to render card consent UI."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Check site ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["storeCardConsent"]}," and shopper setup."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutDropInFailedToRenderPaypalConsentSdkException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1111"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Failed to render PayPal consent UI."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Check PayPal consent configuration."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutDropInFailedToUpdateBillingAddressSdkException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1112"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Failed to update billing address on the session."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Retry or create a new session."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutDropInFailedToUpdateAllowTransactionSdkException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1113"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Failed to update allow-transaction state (Apple Pay)."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Retry or create a new session."]}]},{"$$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":["SDK1120"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["PayPal only supports ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["entryType: .ecom"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Change ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["entryType"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".ecom"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutDropInComponentTypeMismatchSdkException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1121"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Internal component type mismatch."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Contact support with logs."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NoPaymentMethodsAvailableException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0204"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["No payment methods available for the session."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Enable at least one funding type in the session response."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example handling:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"onError: { paymentMethod, error in\n    if error.errorCode.hasPrefix(\"SDK110\") {\n        print(\"Rendering error: \\(error.errorMessage)\")\n        \n        // Log to monitoring\n        logger.error(\"Rendering error\", [\n            \"error_code\": error.errorCode,\n            \"message\": error.errorMessage\n        ])\n        \n        // Show generic error to user\n        Task { @MainActor in\n            showErrorMessage(\n                \"We're having trouble loading payment options. \" +\n                \"Please try again or contact support.\"\n            )\n        }\n    }\n}\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"payment-errors","__idx":8},"children":["Payment errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These errors occur when checkout reaches payment processing but the transaction does not complete. Drop-in maps most failures to a method-specific ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK111x"]}," code on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]},". When the gateway returns provider details, you may receive ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutDropInFailedSubmitResultSdkException"]}," with a provider-specific code instead of an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK111x"]}," value."]},{"$$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":["SDK1116"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Card payment failed."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#card-specific-error-detection-patterns"},"children":["card-specific patterns"]},"."]}]},{"$$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":["SDK1117"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["PayPal transaction failed."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Try again or use a different method."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutDropInApplePayPaymentFailedSdkException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1119"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Apple Pay transaction failed."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Try again or use a different method."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutDropInFailedSubmitResultSdkException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Provider code or method fallback"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Authorisation returned a failed submit result with provider details (card, PayPal, Apple Pay)."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Log ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.errorCode"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.errorMessage"]},". Offer a retry or another payment method."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"card-specific-error-detection-patterns","__idx":9},"children":["Card-specific error detection patterns"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Issuers and gateways format card decline messages differently. When you receive ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1116"]},", inspect ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.errorMessage"]}," to choose an appropriate response:"]},{"$$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.errorMessage"]}," contains ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"declined\""]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Try a different card or contact the 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.errorMessage"]}," contains ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"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.errorMessage"]}," contains ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"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.errorMessage"]}," contains ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"CVV\""]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"security code\""]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Check the 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.errorMessage"]}," contains ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"card number\""]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"invalid number\""]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Check the 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.errorMessage"]}," contains ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"expiry\""]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"expiration\""]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Check the expiry date and retry."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example handling:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"onError: { paymentMethod, error in\n    // Card-specific errors (message-based detection)\n    if error.errorCode == \"SDK1116\" {\n        // Card payment failed - check message for specifics\n        let userMessage: String\n        if error.errorMessage.localizedCaseInsensitiveContains(\"declined\") {\n            userMessage = \"Your card was declined. Please try a different card or \" +\n                         \"contact your bank for more information.\"\n            Task { @MainActor in\n                showErrorMessage(userMessage)\n                offerAlternativePaymentMethods()\n            }\n        } else if error.errorMessage.localizedCaseInsensitiveContains(\"insufficient funds\") {\n            userMessage = \"Insufficient funds. Please use a different payment method.\"\n            Task { @MainActor in\n                showErrorMessage(userMessage)\n                offerAlternativePaymentMethods()\n            }\n        } else if error.errorMessage.localizedCaseInsensitiveContains(\"expired\") {\n            userMessage = \"This card has expired. Please use a different card.\"\n            Task { @MainActor in\n                showErrorMessage(userMessage)\n            }\n        } else if error.errorMessage.localizedCaseInsensitiveContains(\"cvv\") ||\n                  error.errorMessage.localizedCaseInsensitiveContains(\"security code\") {\n            userMessage = \"Invalid security code. Please check the CVV on the back of \" +\n                         \"your card and try again.\"\n            Task { @MainActor in\n                showErrorMessage(userMessage)\n                // Keep same payment method selected for retry\n            }\n        } else {\n            userMessage = \"Card payment failed. Please check your details and try again.\"\n            Task { @MainActor in\n                showErrorMessage(userMessage)\n            }\n        }\n    }\n    \n    // Wallet payment errors\n    else if error.errorCode == \"SDK1117\" {\n        Task { @MainActor in\n            showErrorMessage(\n                \"PayPal payment failed. Please try again or use a different payment method.\"\n            )\n            offerAlternativePaymentMethods()\n        }\n    } else if error.errorCode == \"SDK1119\" {\n        Task { @MainActor in\n            showErrorMessage(\n                \"Apple Pay payment failed. Please try again or use a different payment method.\"\n            )\n            offerAlternativePaymentMethods()\n        }\n    } else if error.errorCode == \"SDK1123\" {\n        Task { @MainActor in\n            showErrorMessage(\n                \"Paze payment failed. Please try again or use a different payment method.\"\n            )\n            offerAlternativePaymentMethods()\n        }\n    } else if paymentMethod == .paze {\n        Task { @MainActor in\n            let userMessage: String\n            switch error.errorCode {\n            case \"SDK1124\":\n                userMessage = \"Paze is only available for e-commerce checkout.\"\n            case \"SDK1209\", \"SDK1210\", \"SDK1211\", \"SDK1212\":\n                userMessage = \"Invalid shopper identity: \\(error.errorMessage)\"\n            case \"SDK1213\":\n                userMessage = \"Paze is only available for USD transactions.\"\n            case \"SDK0118\":\n                userMessage = \"Paze client ID is missing from the session.\"\n            case \"SDK1202A\":\n                userMessage = \"Paze merchant category code is missing from the session.\"\n            default:\n                userMessage = error.errorMessage.localizedCaseInsensitiveContains(\"declined\")\n                    ? \"Payment declined. Please try a different payment method.\"\n                    : \"Paze payment failed: \\(error.errorMessage)\"\n            }\n            showErrorMessage(userMessage)\n            if error.errorCode != \"SDK1124\" {\n                offerAlternativePaymentMethods()\n            }\n        }\n    }\n}\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"authentication-errors","__idx":10},"children":["Authentication errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These errors relate to 3D Secure (3DS) authentication during card payments. Drop-in surfaces the primary failure as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutDropInAuthenticationFailedSdkException"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1114"]},"). Related codes from the authentication flow may also appear in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.errorCode"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.errorMessage"]},"."]},{"$$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 / code"},"children":["Exception / code"]},{"$$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":["SDK1114"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["3DS authentication failed."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Try again or use a different card."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Pre-Initiate Authentication failed"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0502"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The pre-initiate authentication step failed."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Try again or use a different card."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Authentication rejected"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0503"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The issuer or gateway rejected authentication."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Try again or use a different card."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Authentication failed"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0505"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Authentication did not complete successfully."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Try again or use a different card."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Failed to retrieve result"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0510"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The SDK could not retrieve the authentication result."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Check the connection and try again."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Challenge page failed to load"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0511"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The 3DS challenge page failed to load."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Check the connection and try again."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When no specific code is present, you can still detect common outcomes from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.errorMessage"]},". Treat the error as a timeout when the message contains ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"timeout\""]},". Treat it as a customer cancellation when the message contains ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"cancel\""]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example handling:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"onError: { paymentMethod, error in\n    if error.errorCode == \"SDK1114\" || \n       error.errorCode == \"SDK0502\" ||\n       error.errorCode == \"SDK0503\" ||\n       error.errorCode == \"SDK0505\" ||\n       error.errorCode == \"SDK0510\" ||\n       error.errorCode == \"SDK0511\" ||\n       error.errorMessage.localizedCaseInsensitiveContains(\"authentication\") {\n        if error.errorMessage.localizedCaseInsensitiveContains(\"timeout\") {\n            Task { @MainActor in\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        } else if error.errorMessage.localizedCaseInsensitiveContains(\"cancel\") {\n            Task { @MainActor in\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            Task { @MainActor in\n                showErrorMessage(\n                    \"3D Secure authentication failed. Please try again or use a \" +\n                    \"different card.\"\n                )\n            }\n            \n            // Track authentication failures (pseudo-code - use your analytics provider)\n            analytics.track(\"3ds_authentication_failed\", properties: [\n                \"timestamp\": Date().timeIntervalSince1970\n            ])\n        }\n    }\n}\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"authorisation-errors","__idx":11},"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":["SDK1115"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Payment authorisation failed."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Check the transaction details and retry."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"apple-pay-errors","__idx":12},"children":["Apple Pay errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Errors specific to Apple Pay configuration, availability, and processing."]},{"$$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":["ApplePayPaymentRequestApiNotSupportedException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0602"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Apple Pay is not available on this device or iOS version."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Use another payment method; test on a supported device with Apple Pay set up."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ApplePaySessionCancelledException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0615"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Customer cancelled the Apple Pay sheet."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["No action required — allow retry if needed."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ApplePayMerchantValidationFailedException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0616"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Apple Pay merchant validation failed."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Verify Apple Pay merchant configuration in the Unity Portal."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ApplePayCustomApiProcessingFailedException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0617"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Processing failed during Apple Pay payment."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Check logs and retry."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"system-errors","__idx":13},"children":["System errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These errors reflect network connectivity, session state, or platform availability rather than a declined payment. They can appear for any payment method, or before a method is selected (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentMethod"]}," may be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nil"]},")."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.errorCode"]}," where a code is listed. For message-based rows, inspect ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.errorMessage"]},":"]},{"$$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":"How to detect"},"children":["How to detect"]},{"$$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":["Network error"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.errorCode == \"SDK0500\""]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Check the connection and retry."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Session expired"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.errorMessage"]}," contains ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"session\""]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"expired\""]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Create a new session and reinitialise Drop-in."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Request timeout"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.errorMessage"]}," contains ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"timeout\""]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Check the connection and retry."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Service unavailable"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.errorMessage"]}," contains ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"unavailable\""]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"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":["Configuration error"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.errorCode"]}," starts with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"SDK01\""]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"SDK02\""]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Review your session and config. Contact support if the issue persists."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example handling:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"onError: { paymentMethod, error in\n    // Network and session errors\n    if error.errorCode == \"SDK0500\" {\n        Task { @MainActor in\n            showErrorMessage(\n                \"Network connection issue. Please check your internet connection \" +\n                \"and try again.\"\n            )\n            showRetryButton()\n        }\n    } else if error.errorMessage.localizedCaseInsensitiveContains(\"session\") ||\n              error.errorMessage.localizedCaseInsensitiveContains(\"expired\") {\n        Task { @MainActor in\n            showErrorMessage(\n                \"Your payment session has expired. Please reload checkout and \" +\n                \"try again.\"\n            )\n            showRefreshButton()\n        }\n    } else if error.errorMessage.localizedCaseInsensitiveContains(\"timeout\") {\n        Task { @MainActor in\n            showErrorMessage(\n                \"Request timed out. Please check your connection and try again.\"\n            )\n            showRetryButton()\n        }\n    } else if error.errorMessage.localizedCaseInsensitiveContains(\"unavailable\") ||\n              error.errorMessage.localizedCaseInsensitiveContains(\"service\") {\n        Task { @MainActor in\n            showErrorMessage(\n                \"Payment service is temporarily unavailable. Please try again in \" +\n                \"a few minutes.\"\n            )\n        }\n    } else if error.errorCode.hasPrefix(\"SDK01\") || error.errorCode.hasPrefix(\"SDK02\") {\n        Task { @MainActor in\n            showErrorMessage(\n                \"Payment configuration error. Please contact support for assistance.\"\n            )\n        }\n        \n        // Log critical error\n        logger.critical(\"Configuration error\", [\n            \"error_code\": error.errorCode,\n            \"message\": error.errorMessage\n        ])\n    }\n}\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-handling-patterns","__idx":14},"children":["Error handling patterns"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"basic-error-handling","__idx":15},"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":"swift","header":{"controls":{"copy":{}}},"source":"import PXPCheckoutSDK\n\nlet config = CheckoutDropInConfig(\n    // ... other config\n    onError: { paymentMethod, error in\n        // Log error for debugging\n        print(\"Payment error: \\(error.errorCode) - \\(error.errorMessage)\")\n        \n        // Show user-friendly message\n        Task { @MainActor in\n            showErrorNotification(error.errorMessage)\n            \n            // Re-enable payment button\n            enablePaymentButton()\n        }\n    }\n)\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"advanced-error-handling-with-recovery","__idx":16},"children":["Advanced error handling with recovery"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Implement retry logic, alternative payment methods, and error categorisation."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Don't automatically resubmit payments from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," without explicit user confirmation. The following retry logic is for transient network errors only. Payment failures require user action—show an error message and let them manually retry or choose an alternative payment method."]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"var retryCount = 0\nlet maxRetries = 3\n\nlet config = CheckoutDropInConfig(\n    // ... other config\n    onError: { paymentMethod, error in\n        // Log to monitoring service\n        logErrorToMonitoring([\n            \"category\": \"payment_error\",\n            \"error_code\": error.errorCode,\n            \"message\": error.errorMessage,\n            \"device_model\": UIDevice.current.model,\n            \"timestamp\": Date().timeIntervalSince1970\n        ])\n        \n        // Track analytics (pseudo-code - use your analytics provider)\n        analytics.track(\"payment_failed\", properties: [\n            \"error_code\": error.errorCode,\n            \"error_message\": error.errorMessage,\n            \"retry_count\": retryCount\n        ])\n        \n        // Check if error is retryable (network issues, timeouts only)\n        let isNetworkError = error.errorCode == \"SDK0500\"\n        let isTimeout = error.errorMessage.localizedCaseInsensitiveContains(\"timeout\")\n        let isRetryable = isNetworkError || isTimeout || \n                         error.errorMessage.localizedCaseInsensitiveContains(\"unavailable\")\n        \n        // Implement retry logic for transient errors only\n        if isRetryable && retryCount < maxRetries {\n            retryCount += 1\n            \n            Task { @MainActor in\n                showWarningMessage(\n                    \"Connection issue (attempt \\(retryCount)/\\(maxRetries)). \" +\n                    \"Please try your payment again.\"\n                ) {\n                    // Retry the payment\n                    retryPayment()\n                }\n            }\n            return\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        let userMessage: String\n        switch error.errorCode {\n        case \"SDK0500\":\n            userMessage = \"Network connection issue. Please check your internet connection and try again.\"\n        case \"SDK1114\":\n            userMessage = \"3D Secure authentication failed. Please try again or use a different card.\"\n        case \"SDK1115\":\n            userMessage = \"Payment authorisation failed. Please check your details and try again.\"\n        case \"SDK1116\":\n            // Card payment failed - check message for specifics\n            if error.errorMessage.localizedCaseInsensitiveContains(\"declined\") {\n                userMessage = \"Your card was declined. Please try a different card or contact your bank.\"\n            } else if error.errorMessage.localizedCaseInsensitiveContains(\"insufficient funds\") {\n                userMessage = \"Insufficient funds. Please use a different payment method.\"\n            } else if error.errorMessage.localizedCaseInsensitiveContains(\"expired\") {\n                userMessage = \"This card has expired. Please use a different card.\"\n            } else if error.errorMessage.localizedCaseInsensitiveContains(\"cvv\") ||\n                      error.errorMessage.localizedCaseInsensitiveContains(\"security code\") {\n                userMessage = \"Invalid security code. Please check the CVV on your card and try again.\"\n            } else if error.errorMessage.localizedCaseInsensitiveContains(\"card number\") {\n                userMessage = \"Invalid card number. Please check and try again.\"\n            } else if error.errorMessage.localizedCaseInsensitiveContains(\"expiry\") ||\n                      error.errorMessage.localizedCaseInsensitiveContains(\"expiration\") {\n                userMessage = \"Invalid expiry date. Please check and try again.\"\n            } else {\n                userMessage = \"Card payment failed. Please check your details and try again.\"\n            }\n        case \"SDK1117\":\n            userMessage = \"PayPal payment failed. Please try again or use a different payment method.\"\n        case \"SDK1119\":\n            userMessage = \"Apple Pay payment failed. Please try again or use a different payment method.\"\n        case \"SDK1122\":\n            userMessage = \"Paze is unavailable. Please choose another payment method.\"\n        case \"SDK1123\":\n            userMessage = \"Paze payment failed. Please try again or use a different payment method.\"\n        case \"SDK1124\":\n            userMessage = \"Paze is only available for e-commerce checkout.\"\n        case \"SDK1209\", \"SDK1210\", \"SDK1211\", \"SDK1212\":\n            userMessage = \"Invalid shopper identity: \\(error.errorMessage)\"\n        case \"SDK1213\":\n            userMessage = \"Paze is only available for USD transactions.\"\n        case \"SDK0118\":\n            userMessage = \"Paze client ID is missing from the session.\"\n        case \"SDK1202A\":\n            userMessage = \"Paze merchant category code is missing from the session.\"\n        default:\n            // Check by message content for scenarios without specific codes\n            if error.errorMessage.localizedCaseInsensitiveContains(\"timeout\") {\n                userMessage = \"Request timed out. Please check your internet connection and try again.\"\n            } else if error.errorMessage.localizedCaseInsensitiveContains(\"session\") ||\n                      error.errorMessage.localizedCaseInsensitiveContains(\"expired\") {\n                userMessage = \"Your payment session has expired. Please reload checkout.\"\n            } else if error.errorMessage.localizedCaseInsensitiveContains(\"unavailable\") {\n                userMessage = \"Payment service temporarily unavailable. Please try again in a few minutes.\"\n            } else if error.errorCode.hasPrefix(\"SDK01\") || error.errorCode.hasPrefix(\"SDK02\") {\n                userMessage = \"Payment configuration error. Please contact support.\"\n            } else {\n                userMessage = error.errorMessage\n            }\n        }\n        \n        Task { @MainActor in\n            showErrorMessage(userMessage)\n            \n            // Offer alternative payment methods for certain errors\n            let shouldOfferAlternatives = \n                error.errorCode == \"SDK1116\" || // Card payment failed\n                error.errorCode == \"SDK1117\" || // PayPal failed\n                error.errorCode == \"SDK1119\" || // Apple Pay failed\n                error.errorCode == \"SDK1122\" || // Paze unavailable\n                error.errorCode == \"SDK0118\" || // Paze clientId missing at create\n                error.errorCode == \"SDK1123\" || // Paze failed\n                error.errorCode == \"SDK1209\" || error.errorCode == \"SDK1210\" ||\n                error.errorCode == \"SDK1211\" || error.errorCode == \"SDK1212\" ||\n                error.errorCode == \"SDK1213\" ||\n                error.errorCode == \"SDK1202A\" ||\n                error.errorMessage.localizedCaseInsensitiveContains(\"declined\") ||\n                error.errorMessage.localizedCaseInsensitiveContains(\"insufficient funds\")\n            \n            if shouldOfferAlternatives {\n                showAlternativePaymentMethods()\n            }\n            \n            // Show retry button for network/timeout errors\n            let shouldShowRetry = \n                error.errorCode == \"SDK0500\" ||\n                error.errorMessage.localizedCaseInsensitiveContains(\"timeout\") ||\n                error.errorMessage.localizedCaseInsensitiveContains(\"unavailable\")\n            \n            if shouldShowRetry {\n                showRetryButton()\n            }\n            \n            // Show refresh button for session errors\n            if error.errorMessage.localizedCaseInsensitiveContains(\"session\") ||\n               error.errorMessage.localizedCaseInsensitiveContains(\"expired\") {\n                showRefreshButton()\n            }\n            \n            // Re-enable payment form\n            enablePaymentForm()\n        }\n    }\n)\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"error-logging-to-monitoring-service","__idx":17},"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":"swift","header":{"controls":{"copy":{}}},"source":"import FirebaseCrashlytics\n\nlet config = CheckoutDropInConfig(\n    // ... other config\n    onError: { paymentMethod, error in\n        // Log to Firebase Crashlytics\n        Crashlytics.crashlytics().setCustomValue(error.errorCode, forKey: \"error_code\")\n        Crashlytics.crashlytics().setCustomValue(error.errorMessage, forKey: \"error_message\")\n        Crashlytics.crashlytics().record(\n            error: NSError(\n                domain: \"CheckoutDropIn\",\n                code: -1,\n                userInfo: [\n                    NSLocalizedDescriptionKey: \"Payment error: \\(error.errorCode) - \\(error.errorMessage)\"\n                ]\n            )\n        )\n        \n        // Log to custom monitoring service\n        Task {\n            do {\n                try await logErrorToBackend([\n                    \"type\": \"payment_error\",\n                    \"error_code\": error.errorCode,\n                    \"message\": error.errorMessage,\n                    \"device_model\": UIDevice.current.model,\n                    \"os_version\": UIDevice.current.systemVersion,\n                    \"timestamp\": Date().timeIntervalSince1970\n                ])\n            } catch {\n                // Silently fail - don't disrupt user experience\n                print(\"Failed to log error: \\(error.localizedDescription)\")\n            }\n        }\n        \n        // Show error to user\n        Task { @MainActor in\n            showErrorMessage(error.errorMessage)\n        }\n    }\n)\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"complete-error-handling-example","__idx":18},"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":"swift","header":{"controls":{"copy":{}}},"source":"import PXPCheckoutSDK\nimport FirebaseCrashlytics\n\nvar retryCount = 0\nlet maxRetries = 3\n\nlet config = CheckoutDropInConfig(\n    // ... other config\n    onError: { paymentMethod, error in\n        // 1. Log error for debugging\n        print(\"Payment error: \\(error.errorCode) - \\(error.errorMessage)\")\n        if let method = paymentMethod {\n            print(\"Payment method: \\(method)\")\n        } else {\n            print(\"No payment method (initialisation/configuration error)\")\n        }\n        \n        // 2. Send to monitoring service\n        Crashlytics.crashlytics().setCustomValue(error.errorCode, forKey: \"error_code\")\n        Crashlytics.crashlytics().setCustomValue(error.errorMessage, forKey: \"error_message\")\n        Crashlytics.crashlytics().setCustomValue(retryCount, forKey: \"retry_count\")\n        Crashlytics.crashlytics().record(\n            error: NSError(\n                domain: \"CheckoutDropIn\",\n                code: -1,\n                userInfo: [NSLocalizedDescriptionKey: \"Payment error: \\(error.errorCode)\"]\n            )\n        )\n        \n        // 3. Track analytics (pseudo-code - use your analytics provider)\n        analytics.track(\"payment_failed\", properties: [\n            \"error_code\": error.errorCode,\n            \"error_message\": error.errorMessage,\n            \"payment_method\": paymentMethod ?? \"none\",\n            \"retry_count\": retryCount,\n            \"timestamp\": Date().timeIntervalSince1970\n        ])\n        \n        // 4. Clear any loading state\n        Task { @MainActor in\n            hideLoadingOverlay()\n        }\n        \n        // 5. Implement retry logic for transient errors only\n        let isNetworkError = error.errorCode == \"SDK0500\"\n        let isTimeout = error.errorMessage.localizedCaseInsensitiveContains(\"timeout\")\n        let isUnavailable = error.errorMessage.localizedCaseInsensitiveContains(\"unavailable\")\n        \n        if (isNetworkError || isTimeout || isUnavailable) && retryCount < maxRetries {\n            retryCount += 1\n            \n            Task { @MainActor in\n                showNotification(\n                    type: .warning,\n                    message: \"Connection issue (attempt \\(retryCount)/\\(maxRetries)). \" +\n                             \"Please try again.\"\n                ) {\n                    retryPayment()\n                }\n            }\n            return\n        }\n        \n        // Reset retry count\n        retryCount = 0\n        \n        // 6. Show user-friendly error messages\n        let userMessage: String\n        switch error.errorCode {\n        case \"SDK0500\":\n            userMessage = \"Network error. Please check your connection and try again.\"\n        case \"SDK1114\":\n            userMessage = \"3D Secure authentication failed. Please try again.\"\n        case \"SDK1115\":\n            userMessage = \"Payment authorisation failed. Please check your details and try again.\"\n        case \"SDK1116\":\n            // Card payment failed - check message\n            if error.errorMessage.localizedCaseInsensitiveContains(\"declined\") {\n                userMessage = \"Your card was declined. Please try a different card or contact your bank.\"\n            } else if error.errorMessage.localizedCaseInsensitiveContains(\"insufficient funds\") {\n                userMessage = \"Insufficient funds. Please use a different payment method.\"\n            } else if error.errorMessage.localizedCaseInsensitiveContains(\"expired\") {\n                userMessage = \"This card has expired. Please use a different card.\"\n            } else if error.errorMessage.localizedCaseInsensitiveContains(\"cvv\") {\n                userMessage = \"Invalid security code. Please check and try again.\"\n            } else {\n                userMessage = \"Card payment failed. Please check your details and try again.\"\n            }\n        case \"SDK1117\":\n            userMessage = \"PayPal payment failed. Please try again or use a different method.\"\n        case \"SDK1119\":\n            userMessage = \"Apple Pay payment failed. Please try again or use a different method.\"\n        case \"SDK1122\":\n            userMessage = \"Paze is unavailable. Please choose another payment method.\"\n        case \"SDK1123\":\n            userMessage = \"Paze payment failed. Please try again or use a different method.\"\n        case \"SDK1124\":\n            userMessage = \"Paze is only available for e-commerce checkout.\"\n        case \"SDK1209\", \"SDK1210\", \"SDK1211\", \"SDK1212\":\n            userMessage = \"Invalid shopper identity: \\(error.errorMessage)\"\n        case \"SDK1213\":\n            userMessage = \"Paze is only available for USD transactions.\"\n        case \"SDK0118\":\n            userMessage = \"Paze client ID is missing from the session.\"\n        case \"SDK1202A\":\n            userMessage = \"Paze merchant category code is missing from the session.\"\n        default:\n            if error.errorMessage.localizedCaseInsensitiveContains(\"session\") ||\n               error.errorMessage.localizedCaseInsensitiveContains(\"expired\") {\n                userMessage = \"Session expired. Please reload checkout.\"\n            } else if error.errorCode.hasPrefix(\"SDK01\") || error.errorCode.hasPrefix(\"SDK02\") {\n                userMessage = \"Configuration error. Please contact support.\"\n            } else if paymentMethod == .paze && error.errorMessage.localizedCaseInsensitiveContains(\"declined\") {\n                userMessage = \"Payment declined. Please try a different payment method.\"\n            } else {\n                userMessage = error.errorMessage\n            }\n        }\n        \n        // 7. Show error to user\n        Task { @MainActor in\n            showNotification(\n                type: .error,\n                title: \"Payment failed\",\n                message: userMessage,\n                duration: 8.0\n            )\n            \n            // 8. Offer recovery options\n            let shouldOfferAlternatives = \n                error.errorCode == \"SDK1116\" || \n                error.errorCode == \"SDK1117\" || \n                error.errorCode == \"SDK1119\" ||\n                error.errorCode == \"SDK1122\" ||\n                error.errorCode == \"SDK0118\" ||\n                error.errorCode == \"SDK1123\" ||\n                error.errorCode == \"SDK1209\" || error.errorCode == \"SDK1210\" ||\n                error.errorCode == \"SDK1211\" || error.errorCode == \"SDK1212\" ||\n                error.errorCode == \"SDK1213\" ||\n                error.errorCode == \"SDK1202A\" ||\n                error.errorMessage.localizedCaseInsensitiveContains(\"declined\") ||\n                error.errorMessage.localizedCaseInsensitiveContains(\"insufficient funds\")\n            \n            if shouldOfferAlternatives {\n                showAlternativePaymentMethods()\n            }\n            \n            let shouldShowRetry = \n                error.errorCode == \"SDK0500\" ||\n                error.errorMessage.localizedCaseInsensitiveContains(\"timeout\")\n            \n            if shouldShowRetry {\n                showRetryButton()\n            }\n            \n            if error.errorMessage.localizedCaseInsensitiveContains(\"session\") ||\n               error.errorMessage.localizedCaseInsensitiveContains(\"expired\") {\n                showRefreshButton()\n            }\n            \n            // 9. Re-enable UI\n            enablePaymentForm()\n            enableSubmitButton()\n        }\n    }\n)\n","lang":"swift"},"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/ios/cards"},"children":["Card"]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/drop-in/ios/paypal"},"children":["PayPal"]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/drop-in/ios/apple-pay"},"children":["Apple 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":"Initialisation errors (throws)","id":"initialisation-errors-throws","depth":4},{"value":"Drop-in render and update errors","id":"drop-in-render-and-update-errors","depth":4},{"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":"Apple Pay errors","id":"apple-pay-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-07-14T09:12:22.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/checkout/drop-in/ios/error-handling","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}