{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["sub-heading","admonition"]},"type":"markdown"},"seo":{"title":"Troubleshooting","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":"troubleshooting","__idx":0},"children":["Troubleshooting"]},{"$$mdtype":"Tag","name":"SubHeading","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Learn how to diagnose and fix common issues with the Paze iOS component."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"exception-types-and-error-codes","__idx":1},"children":["Exception types and error codes"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"component-exceptions","__idx":2},"children":["Component exceptions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Paze iOS component surfaces ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BaseSdkException"]}," errors with structured codes for different failure scenarios:"]},{"$$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":{"width":"40%","data-label":"Exception"},"children":["Exception "]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Error code"},"children":["Error code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UnsupportedFundingTypePazeSdkException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0118"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Paze is not included in the allowed funding types for this session."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PazeLoadFailedException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1200"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Paze checkout session failed to start. For example, due to network issues or an error returned by the Paze API."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PazeConfigurationValidationFailedException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1202"]},"–",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1205"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1231"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1232"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Configuration validation failed. For example, missing client ID, invalid field lengths, invalid shipping countries, or empty cobrand names."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PazeMerchantCategoryCodeRequiredException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1202A"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantCategoryCode"]}," is missing from the session. Required on iOS for payment completion."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PazeInitializationFailedException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1206"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Paze initialisation failed."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PazeIdentityValidationFailedException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1209"]},"–",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1212"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Email or phone number validation failed. Check format and length requirements."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PazeCurrencyNotSupportedException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1213"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Paze only supports ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USD"]}," currency."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PazePaymentFailedException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1214"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Paze checkout or wallet flow failed before authorisation."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PazeCheckoutResponseMissingException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1215"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Paze checkout did not return a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkoutResponse"]}," for a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPLETE"]}," result."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PazeCompleteResponseMissingException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1216"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Paze ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["complete()"]}," did not return a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["completeResponse"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PazeCompleteSecuredPayloadMissingException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1219"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Paze ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["completeResponse"]}," did not contain a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["securedPayload"]}," for decryption."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PazeCompleteSecuredPayloadMissingException"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PazePaymentFailedException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1219"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1214"]}," (or provider error codes)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Token decryption failed. Check session encryption key and Paze wallet settings in Unity Portal. Surfaced via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," and the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PazeDecryptionFailed"]}," analytics event."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PazeTransactionFailedException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1235"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transaction submission failed. Surfaced via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSubmitError"]},", not ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]},". The callback typically receives a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FailedSubmitResult"]}," with gateway or provider error codes."]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["User cancellation isn't thrown as an exception. When the shopper dismisses the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ASWebAuthenticationSession"]},", the SDK calls ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onCheckoutIncomplete"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reason: \"User cancelled.\""]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-handling-best-practices","__idx":3},"children":["Error handling best practices"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"comprehensive-error-handler","__idx":4},"children":["Comprehensive error handler"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Route ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onCheckoutIncomplete"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSubmitError"]}," to appropriate user messaging and logging:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"config.onError = { error in\n    print(\"Paze error:\", error.errorCode, error.errorMessage)\n\n    switch error.errorCode {\n    case \"SDK0118\", \"SDK1202\":\n        hidePazeButton()\n        showAlternativePaymentMethods()\n    case \"SDK1202A\":\n        showMessage(\"Paze merchant category code is missing from the session.\")\n    case \"SDK1213\":\n        showMessage(\"Paze is only available for USD transactions.\")\n    case \"SDK1210\", \"SDK1212\":\n        showMessage(\"Please check your contact details and try again.\")\n    case \"SDK1214\", \"SDK1200\":\n        showMessage(\"Paze checkout failed. Please try again.\")\n    default:\n        showMessage(\"Payment could not be completed. Please try again.\")\n    }\n}\n\nconfig.onCheckoutIncomplete = { result async in\n    if result.reason?.lowercased().contains(\"cancel\") == true {\n        showMessage(\"Payment cancelled.\")\n    } else {\n        showMessage(\"Payment was not completed. Please try again.\")\n    }\n}\n\nconfig.onSubmitError = { submitResult async in\n    if let failed = submitResult as? FailedSubmitResult {\n        print(\"Submit error:\", failed.errorCode ?? \"\", failed.errorReason ?? \"\")\n    }\n    showMessage(\"Payment could not be processed. Please try another method.\")\n}\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"logging-for-support","__idx":5},"children":["Logging for support"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Include these fields when logging errors for PXP or Paze support:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"func logPazeError(_ error: BaseSdkException, context: [String: Any] = [:]) {\n    var payload: [String: Any] = [\n        \"errorCode\": error.errorCode,\n        \"errorMessage\": error.errorMessage,\n        \"timestamp\": ISO8601DateFormatter().string(from: Date())\n    ]\n    context.forEach { payload[$0.key] = $0.value }\n    // Send to your logging or crash reporting service\n    print(\"Paze support log:\", payload)\n}\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"portal-and-session-setup","__idx":6},"children":["Portal and session setup"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use this section when Paze isn't appearing in the Unity Portal, missing from your session response, or failing during component creation with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0118"]},". For portal setup steps, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/components/ios/paze/onboarding"},"children":["Onboarding"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"paze-service-not-visible-on-site","__idx":7},"children":["Paze service not visible on site"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Symptom:"]}," The Paze service doesn't appear in your site's Services tab."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Solution:"]}," Enable Paze at the merchant group level first (",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/components/ios/paze/onboarding#step-1-ensure-paze-is-enabled-at-the-merchant-group-level"},"children":["Onboarding, Step 1"]},"), then return to the site configuration."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"missing-client-id-in-session","__idx":8},"children":["Missing client ID in session"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Symptom:"]}," Session response doesn't include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allowedFundingTypes.wallets.paze.clientId"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Solution:"]}]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verify the client ID is saved in ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Paze Account Settings"]}," for the correct site."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create a new session after saving portal changes."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Confirm you are using the correct site name in your session request."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"sdk0118-on-create","__idx":9},"children":["SDK0118 on create"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Symptom:"]}," Component creation fails with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Paze is missing in allow funding types."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Solution:"]}," The session was created before Paze was configured, or Paze isn't enabled for the site. Complete ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/components/ios/paze/onboarding#step-3-configure-paze-on-your-site"},"children":["Onboarding, Steps 3–4"]},", then re-create the session and re-initialise the SDK."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"sdk1202-at-presentment","__idx":10},"children":["SDK1202 at presentment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Symptom:"]}," Presentment fails with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Missing session.allowedFundingTypes.wallets.paze.clientId"]}," and the button doesn't appear."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Solution:"]}," Confirm ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clientId"]}," is in the session response from your backend and passed through ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SessionData"]}," when initialising the SDK. Re-create the session after saving portal changes."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"sdk1202a-during-complete","__idx":11},"children":["SDK1202A during complete"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Symptom:"]}," Complete step fails after checkout returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPLETE"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Missing session.allowedFundingTypes.wallets.paze.merchantCategoryCode"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Solution:"]}," Include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantCategoryCode"]}," in your backend session response and pass it through ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SessionData"]}," when initialising the SDK. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/components/ios/paze/onboarding#step-4-verify-session-configuration"},"children":["Onboarding, Step 4"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"troubleshooting-common-issues","__idx":12},"children":["Troubleshooting common issues"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"paze-button-isnt-showing","__idx":13},"children":["Paze button isn't showing"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The symptoms of this are:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onPresentmentResolved(false)"]}," fires and no button appears in your SwiftUI view."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The Paze option isn't visible to shoppers."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"diagnostic-steps","__idx":14},"children":["Diagnostic steps"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Run these checks to narrow down why the button isn't visible:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"func diagnosePazePresentment(checkoutConfig: CheckoutConfig, componentConfig: PazeButtonComponentConfig) {\n    print(\"=== Paze Presentment Diagnostics ===\")\n\n    let paze = checkoutConfig.session.allowedFundingTypes?.wallets?.paze\n    print(\"Client ID:\", paze?.clientId?.isEmpty == false ? \"Present\" : \"Missing\")\n    print(\"MCC:\", paze?.merchantCategoryCode?.isEmpty == false ? \"Present\" : \"Missing (required at complete, not for button visibility)\")\n    print(\"Currency:\", checkoutConfig.transactionData.currency)\n    print(\"Amount:\", checkoutConfig.transactionData.amount)\n    print(\"Email:\", componentConfig.emailAddress ?? \"Not set\")\n    print(\"Phone:\", componentConfig.phoneNumber ?? \"Not set\")\n}\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Listen for presentment and error callbacks:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"config.onPresentmentResolved = { isVisible in\n    print(\"Presentment resolved:\", isVisible)\n}\n\nconfig.onError = { error in\n    print(\"Presentment error:\", error.errorCode, error.errorMessage)\n}\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"common-causes","__idx":15},"children":["Common causes"]},{"$$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":"Cause"},"children":["Cause"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Error code"},"children":["Error code"]},{"$$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":["Paze not in session at ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create()"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0118"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Enable Paze in Portal and include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clientId"]}," in session"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Missing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clientId"]}," at presentment"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1202"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Configure Paze Account Settings and re-create session"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Non-USD currency"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1213"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionData.currency"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"USD\""]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Invalid email or phone"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1210"]},"–",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1212"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Fix format. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/components/ios/paze/data-validation#identity-validation-rules"},"children":["Data validation"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clientName"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["siteName"]}," too long"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1203"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1204"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Shorten to 50 characters or fewer"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Statement descriptor too long"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1205"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Shorten ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentDescription"]}," to 25 characters or fewer"]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["On iOS, the button uses static presentment. It appears after SDK validation without calling Paze ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["canCheckout()"]},". If the button is hidden, check ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," for validation failures rather than wallet eligibility."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"solution-hide-paze-gracefully","__idx":16},"children":["Solution: hide Paze gracefully"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When Paze is unavailable, hide the button and show alternatives:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"config.onPresentmentResolved = { isVisible in\n    showPazeSection(isVisible)\n}\n\nconfig.onError = { error in\n    if [\"SDK0118\", \"SDK1202\", \"SDK1213\"].contains(error.errorCode) {\n        showPazeSection(false)\n        showAlternativePaymentMethods()\n    }\n}\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"checkout-fails-or-gets-cancelled","__idx":17},"children":["Checkout fails or gets cancelled"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The symptoms of this are:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The shopper taps the Paze button but checkout doesn't complete."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onCheckoutIncomplete"]}," fires unexpectedly."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The Paze web session opens but the shopper can't complete payment."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"diagnostic-steps-1","__idx":18},"children":["Diagnostic steps"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Instrument checkout callbacks to log each step:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"config.onPazeButtonClicked = { async in\n    print(\"Step 1: Button clicked\")\n    print(\"Currency:\", checkoutConfig.transactionData.currency)\n    print(\"Amount:\", checkoutConfig.transactionData.amount)\n}\n\nconfig.onCheckoutComplete = { result async in\n    print(\"Step 2: Checkout complete\")\n    print(\"Session ID:\", result.checkoutDecodedResponse?.sessionId ?? \"\")\n    return true\n}\n\nconfig.onCheckoutIncomplete = { result async in\n    print(\"Checkout incomplete:\", result.reason ?? \"\")\n}\n\nconfig.onError = { error in\n    print(\"Checkout error:\", error.errorCode, error.errorMessage)\n}\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"solutions","__idx":19},"children":["Solutions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Currency validation:"]}," Confirm ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionData.currency"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"USD\""]}," before showing the Paze section."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["User cancellation:"]}," When the shopper dismisses the web session, expect ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onCheckoutIncomplete"]}," with a cancellation reason — not ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"config.onCheckoutIncomplete = { result async in\n    if result.reason?.lowercased().contains(\"cancel\") == true {\n        showMessage(\"Payment cancelled. You can try again when ready.\")\n    } else {\n        showMessage(\"Unable to complete checkout. Please try a different payment method.\")\n    }\n}\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Merchant rejection:"]}," Returning ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}," from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onCheckoutComplete"]}," triggers ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onCheckoutIncomplete"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"config.onCheckoutComplete = { result async in\n    guard validateCheckout(result) else { return false }\n    return true\n}\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["UAT wallet access:"]}," In UAT, confirm the test shopper email or phone is provisioned for your Paze merchant account. Checkout may fail if the wallet account exists but isn't accessible to the merchant."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"app-doesnt-return-from-checkout","__idx":20},"children":["App doesn't return from checkout"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The symptoms of this are:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The Paze web session completes but your app doesn't resume."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Checkout hangs after the shopper finishes in the browser sheet."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onCheckoutComplete"]}," never fires."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"diagnostic-steps-2","__idx":21},"children":["Diagnostic steps"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Verify your URL callback scheme is registered:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"xml","header":{"controls":{"copy":{}}},"source":"<!-- Info.plist -->\n<key>CFBundleURLTypes</key>\n<array>\n    <dict>\n        <key>CFBundleURLSchemes</key>\n        <array>\n            <string>pxpcheckout</string>\n        </array>\n    </dict>\n</array>\n","lang":"xml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Confirm the scheme matches your SDK build configuration. The default callback URL is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pxpcheckout://paze"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"solutions-1","__idx":22},"children":["Solutions"]},{"$$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":"Issue"},"children":["Issue"]},{"$$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":["Scheme not in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Info.plist"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Register ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CFBundleURLSchemes"]}," before testing checkout"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Scheme mismatch"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Ensure ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PXP_CALLBACK_SCHEME"]}," matches your registered scheme"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Another app claims the scheme"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Use a unique scheme for your app"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Testing only in Simulator"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Test full return flow on a physical device"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Presentation context missing"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Present checkout from a view controller with a valid window"]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If multiple apps register the same URL scheme, iOS may route the callback to the wrong app. Use a scheme unique to your application."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"token-decryption-fails","__idx":23},"children":["Token decryption fails"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The symptoms of this are:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Checkout completes but payment doesn't process."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onPostDecryption"]}," never fires."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," fires or the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PazeDecryptionFailed"]}," analytics event is recorded."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"diagnostic-steps-3","__idx":24},"children":["Diagnostic steps"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Log each stage of the decryption flow:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"config.onCheckoutComplete = { result async in\n    print(\"Step 1: Checkout complete, merchant approved\")\n    return true\n}\n\nconfig.onComplete = { result async in\n    print(\"Step 2: Complete API succeeded\")\n    print(\"Secured payload present:\", result.completeDecodedResponse?.securedPayload != nil)\n}\n\nconfig.onPreDecryption = { async in\n    print(\"Step 3: Pre-decryption\")\n    let hasKey = !checkoutConfig.session.encryptionKey.isEmpty\n    print(\"Session encryption key present:\", hasKey)\n    return true\n}\n\nconfig.onPostDecryption = { payload async in\n    print(\"Step 4: Decryption successful\")\n    print(\"Network token present:\", !payload.fundingData.networkToken.isEmpty)\n}\n\nconfig.onError = { error in\n    print(\"Decryption or checkout error:\", error.errorCode, error.errorMessage)\n}\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"solutions-2","__idx":25},"children":["Solutions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["SDK-managed decryption:"]}," Return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onPreDecryption"]}," (default) and confirm ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["session.encryptionKey"]}," is present in the session from your backend."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Manual decryption:"]}," Return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}," from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onPreDecryption"]}," and decrypt ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["securedPayload"]}," on your backend. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/components/ios/paze/implementation#backend-decryption"},"children":["Backend decryption"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Missing secured payload:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1219"]}," means the complete response had no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["securedPayload"]},". Contact PXP support with the checkout session ID."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"authorisation-or-submission-fails","__idx":26},"children":["Authorisation or submission fails"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The symptoms of this are:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Decryption succeeds but the transaction doesn't complete."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSubmitError"]}," fires with error details."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSubmitError"]}," fires with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FailedSubmitResult"]}," details (typically gateway or provider codes such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DECLINED"]},", not ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1235"]},")."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"diagnostic-steps-4","__idx":27},"children":["Diagnostic steps"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"config.onPreAuthorisation = { async in\n    print(\"Pre-authorisation gate\")\n    return .proceed\n}\n\nconfig.onPostAuthorisation = { data async in\n    print(\"Authorisation result:\", data.systemTransactionId)\n}\n\nconfig.onSubmitError = { submitResult async in\n    if let failed = submitResult as? FailedSubmitResult {\n        print(\"Submit failed:\", failed.errorCode ?? \"\", failed.errorReason ?? \"\")\n    }\n}\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"solutions-3","__idx":28},"children":["Solutions"]},{"$$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":"Cause"},"children":["Cause"]},{"$$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":["Missing shopper data"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Implement ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onGetShopper"]}," on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutConfig"]}," with valid shopper details"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Pre-auth cancelled"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Returning ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".cancel"]}," from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onPreAuthorisation"]}," aborts submission intentionally"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Backend rejection"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Inspect ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failed.errorCode"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failed.errorReason"]}," from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSubmitError"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Session expired"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Create a new session and re-initialise the SDK"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"invalid-identity-format","__idx":29},"children":["Invalid identity format"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Symptom:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1210"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1212"]}," during presentment or checkout."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Solution:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Email: valid RFC 5322 format, 128 characters or fewer."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Phone: US E.164 without ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["+"]},", exactly ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1"]}," followed by 10 digits (e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["15551234567"]},")."]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"// Incorrect\nconfig.phoneNumber = \"+1 (555) 123-4567\"\n\n// Correct\nconfig.phoneNumber = \"15551234567\"\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"quick-reference","__idx":30},"children":["Quick reference"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"when-to-use-which-callback","__idx":31},"children":["When to use which callback"]},{"$$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":"Situation"},"children":["Situation"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Callback"},"children":["Callback"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Action"},"children":["Action"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Configuration or SDK error"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Show message, log ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorCode"]},", offer alternatives"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Shopper dismissed web checkout"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onCheckoutIncomplete"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Show cancellation message"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Merchant rejects checkout data"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onCheckoutComplete"]}," → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Triggers ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onCheckoutIncomplete"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Decryption failure"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PazeDecryptionFailed"]}," analytics"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Retry or offer alternative payment"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Unity submission failure"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSubmitError"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FailedSubmitResult"]},")"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Show failure message, log ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorCode"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorReason"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Button visibility"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onPresentmentResolved"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Show or hide Paze section"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-code-reference","__idx":32},"children":["Error code reference"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following tables list the most common Paze error codes surfaced through ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSubmitError"]},". For the complete SDK reference — including complete-step validation (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1222"]},"–",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1230"]},"), decode failures, and dynamic-presentment codes — see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/components/ios/paze/data-validation#full-paze-error-reference"},"children":["Full Paze error reference"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"component-creation-errors","__idx":33},"children":["Component creation errors"]},{"$$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":"Message"},"children":["Message"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Cause"},"children":["Cause"]}]}]},{"$$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":["SDK0118"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Paze is missing in allow funding types."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["session.allowedFundingTypes.wallets.paze.clientId"]}," is missing or empty at ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create(.pazeButton)"]}," time"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"presentment-errors","__idx":34},"children":["Presentment errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Presentment errors occur during component initialisation before the button is shown. The button remains hidden and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onPresentmentResolved(false)"]}," is called."]},{"$$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":"Message"},"children":["Message"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Cause"},"children":["Cause"]}]}]},{"$$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":["SDK1202"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Missing session.allowedFundingTypes.wallets.paze.clientId."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Paze ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clientId"]}," not in session data"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1203"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["client.name must be 50 characters or fewer."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutConfig.clientName"]}," too long"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1204"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["client.brandName must be 50 characters or fewer."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutConfig.siteName"]}," too long"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1205"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["client.statementDescriptor must be 25 characters or fewer."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentDescription"]}," too long"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1209"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["emailAddress must be 128 characters or fewer."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Email exceeds max length"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1210"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["emailAddress must be a valid RFC 5322 email address."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Invalid email format"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1211"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["phoneNumber must be 15 characters or fewer."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Phone exceeds max length"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1212"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["phoneNumber must be a US E.164 number without '+', for example 15551234567."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Invalid phone format"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1213"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Paze only supports USD currency. Received: '{currency}'."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Transaction currency is not USD"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1206"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Failed to initialize Paze SDK."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Generic presentment failure"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"checkout-and-payment-errors","__idx":35},"children":["Checkout and payment errors"]},{"$$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":"Message"},"children":["Message"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Cause"},"children":["Cause"]}]}]},{"$$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":["SDK1200"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Failed to load Paze SDK."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Session creation failed"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1214"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Paze checkout failed."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Generic checkout failure"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1215"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Paze checkout did not return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkoutResponse"]}," for a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPLETE"]}," result."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Missing checkout response"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1216"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Paze complete did not return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["completeResponse"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Missing complete response code"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1219"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Paze completeResponse did not contain ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["securedPayload"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Secured payload missing after complete"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1202A"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Missing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["session.allowedFundingTypes.wallets.paze.merchantCategoryCode"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["MCC not configured in session"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1231"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["acceptedShippingCountries"]}," contains invalid country codes: {invalidCountryCodes}."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Invalid ISO country codes"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1232"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cobrand.cobrandName"]}," is required for each cobrand entry."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Empty cobrand name"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1235"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Paze payment transaction failed."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Authorisation request failed. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSubmitError"]}," typically receives a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FailedSubmitResult"]}," with gateway or provider error codes"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Additional codes (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1201"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1207"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1208"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1217"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1218"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1220"]},"-",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1230"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1233"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1234"]},") are documented in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/components/ios/paze/data-validation#full-paze-error-reference"},"children":["Full Paze error reference"]},"."]}]},"headings":[{"value":"Troubleshooting","id":"troubleshooting","depth":1},{"value":"Exception types and error codes","id":"exception-types-and-error-codes","depth":2},{"value":"Component exceptions","id":"component-exceptions","depth":3},{"value":"Error handling best practices","id":"error-handling-best-practices","depth":2},{"value":"Comprehensive error handler","id":"comprehensive-error-handler","depth":3},{"value":"Logging for support","id":"logging-for-support","depth":3},{"value":"Portal and session setup","id":"portal-and-session-setup","depth":2},{"value":"Paze service not visible on site","id":"paze-service-not-visible-on-site","depth":3},{"value":"Missing client ID in session","id":"missing-client-id-in-session","depth":3},{"value":"SDK0118 on create","id":"sdk0118-on-create","depth":3},{"value":"SDK1202 at presentment","id":"sdk1202-at-presentment","depth":3},{"value":"SDK1202A during complete","id":"sdk1202a-during-complete","depth":3},{"value":"Troubleshooting common issues","id":"troubleshooting-common-issues","depth":2},{"value":"Paze button isn't showing","id":"paze-button-isnt-showing","depth":3},{"value":"Diagnostic steps","id":"diagnostic-steps","depth":4},{"value":"Common causes","id":"common-causes","depth":4},{"value":"Solution: hide Paze gracefully","id":"solution-hide-paze-gracefully","depth":4},{"value":"Checkout fails or gets cancelled","id":"checkout-fails-or-gets-cancelled","depth":3},{"value":"Diagnostic steps","id":"diagnostic-steps-1","depth":4},{"value":"Solutions","id":"solutions","depth":4},{"value":"App doesn't return from checkout","id":"app-doesnt-return-from-checkout","depth":3},{"value":"Diagnostic steps","id":"diagnostic-steps-2","depth":4},{"value":"Solutions","id":"solutions-1","depth":4},{"value":"Token decryption fails","id":"token-decryption-fails","depth":3},{"value":"Diagnostic steps","id":"diagnostic-steps-3","depth":4},{"value":"Solutions","id":"solutions-2","depth":4},{"value":"Authorisation or submission fails","id":"authorisation-or-submission-fails","depth":3},{"value":"Diagnostic steps","id":"diagnostic-steps-4","depth":4},{"value":"Solutions","id":"solutions-3","depth":4},{"value":"Invalid identity format","id":"invalid-identity-format","depth":3},{"value":"Quick reference","id":"quick-reference","depth":2},{"value":"When to use which callback","id":"when-to-use-which-callback","depth":3},{"value":"Error code reference","id":"error-code-reference","depth":2},{"value":"Component creation errors","id":"component-creation-errors","depth":3},{"value":"Presentment errors","id":"presentment-errors","depth":3},{"value":"Checkout and payment errors","id":"checkout-and-payment-errors","depth":3}],"frontmatter":{"seo":{"title":"Troubleshooting"}},"lastModified":"2026-06-30T10:00:28.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/checkout/components/ios/paze/troubleshooting","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}