{"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":["Diagnose and resolve common Aeropay setup, verification, bank-linking, and transaction issues."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-handling","__idx":1},"children":["Error handling"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Aeropay failures are reported through different paths:"]},{"$$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":{"data-label":"Failure type"},"children":["Failure type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Where to handle it"},"children":["Where to handle it"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invalid component or SDK configuration"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Catch the exception thrown by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pxpCheckout.create(.aeropayButton, componentConfig:)"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Custom validation returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Handle it in your own ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onCustomValidation"]}," logic. No SDK error is raised."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Recognised shopper, user, OTP provider, bank account, or Aerosync error"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Handle ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transaction submission failure"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Handle ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSubmitError"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Shopper dismisses the popup"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Handle ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onCancel"]},". Cancellation isn't an error."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Inline field or OTP format error"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The component displays the message and prevents progression."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use these error paths in your integration:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"do {\n    let config = AeropayButtonComponentConfig()\n    config.onCancel = {\n        resetCheckoutState()\n    }\n    config.onPreAuthorisation = { true }\n    config.onPostAuthorisation = { result in\n        verifyPaymentOnBackend(result)\n    }\n    config.onSubmitError = { error in\n        guard let failed = error as? FailedSubmitResult else { return }\n        // Log failed.errorCode, failed.errorReason, and failed.correlationId in restricted logs\n        showPaymentError(\"Unable to complete the transaction.\")\n    }\n    config.onError = { _ in\n        showPaymentError(\"Unable to continue with Aeropay.\")\n    }\n    let aeropayButton = try pxpCheckout.create(.aeropayButton, componentConfig: config)\n} catch let error as BaseSdkException {\n    showAlternativePaymentMethods()\n}\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Don't show raw provider or SDK messages to shoppers. Map failures to approved user-facing messages and keep technical details in restricted logs."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-code-reference","__idx":2},"children":["Error code reference"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"setup-and-configuration","__idx":3},"children":["Setup and configuration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These SDK errors occur when creating the component:"]},{"$$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":{"data-label":"Error code"},"children":["Error code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Check"},"children":["Check"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0106"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unsupported Aeropay intent."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".authorisation"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".purchase"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".estimatedAuthorisation"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".payout"]},". With the current public ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AeropayIntentType"]}," cases, typed Aeropay creation won't hit this path."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0113"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Aeropay funding configuration is missing."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Confirm that the session contains non-empty ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalMerchantId"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["configurationId"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0114"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unsupported entry type."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionData.entryType"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".ecom"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0115"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Aeropay intent is missing."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionData.intent.aeropay"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0116"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unsupported currency."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionData.currency"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USD"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"aeropay-flow","__idx":4},"children":["Aeropay flow"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These errors can occur after the shopper starts the Aeropay flow:"]},{"$$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":{"data-label":"Error code"},"children":["Error code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Check"},"children":["Check"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1300"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Shopper data is invalid."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Correct values returned by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onGetShopper"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1301"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Aeropay user creation failed."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Check consumer values, provider details, credentials, and network status."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1302"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["User verification failed."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Confirm the OTP, network status, and provider response. Provider code ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AP112"]}," also surfaces as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1302"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1303"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Missing or invalid Aerosync payload (including bank-list load when no verified Aeropay user ID is available on the bank-selection screen), or the SDK can't parse a valid account-linking payload from the Aerosync success result."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Prefer this code when diagnosing a missing verified user ID on the live bank UI. Calls ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," in most cases; some link-bank / credentials paths show only inline or alert feedback without ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1304"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Aerosync failed."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Check network access, environment configuration, and the provider response."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1305"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Linking the bank account failed."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Retry linking and check PXP or Aeropay service status."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1306"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Retrieving bank accounts failed."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Check the user, provider response, session, and network."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1307"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The Aeropay user isn't active."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Remove the stored ID and offer the new-shopper flow."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1308"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Retrieving the Aeropay user failed."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Check the stored ID, session, network, and provider availability."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1311"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AeropayAerosyncConfigMissingException"]}," with message ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Aeropay Aerosync token and deeplink are required."]}," Uncommon on the current Aerosync screen callbacks for a missing user ID — don't use this as the primary missing-verification signal. Prefer ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1303"]}," for bank-list load without a verified user ID."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Confirm verification or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["userId"]}," first via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1303"]}," / shopper flow; treat ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1311"]}," as rare unless debugging helper code paths."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1319"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Aggregator credentials lookup failed."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Check the verified user, session, and provider availability."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Missing a verified Aeropay user ID on the bank-selection screen typically surfaces as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1303"]}," on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," when the bank list loads. Some link-bank / credentials paths show only inline or alert feedback without ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]},". Don't diagnose missing verification primarily via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1311"]},"."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Network or transport failures during these Aeropay service calls typically call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0500"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NetworkSdkException"]},"). Other mapped failures use the Aeropay-specific codes in the table."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Mapped failed Unity transaction responses call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSubmitError"]}," with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FailedSubmitResult"]}," and emit ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ComponentError"]}," analytics with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1326"]},". Network or transport failures after Unity submission also call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSubmitError"]},", but their analytics code can differ. Don't expect ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1326"]}," on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"collect-safe-diagnostic-information","__idx":5},"children":["Collect safe diagnostic information"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Record identifiers and configuration presence without logging credentials or personal data:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"func logAeropayDiagnostics(\n    session: SessionData,\n    transactionData: TransactionData,\n    environment: Environment\n) {\n    let aeropay = session.allowedFundingTypes?.payByBanks?.aeropay\n    // Log only:\n    // environment\n    // session.sessionId\n    // whether externalMerchantId and configurationId are present\n    // transactionData.currency\n    // transactionData.entryType\n    // transactionData.intent.aeropay\n    // transactionData.merchantTransactionId\n}\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Don't log ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hmacKey"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["encryptionKey"]},", PXP tokens, Aeropay credentials, shopper details, OTPs, user IDs, or bank account metadata."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If a PXP token or Aeropay secret may have been exposed:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Revoke or replace the affected credential."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Update the backend secret store and redeploy the affected service."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Review logs, analytics, screenshots, and support records for further exposure."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Retest session creation and the Aeropay flow with the replacement credential."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"portal-and-session-setup","__idx":6},"children":["Portal and session setup"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"aeropay-isnt-available-in-site-services","__idx":7},"children":["Aeropay isn't available in site services"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The likely cause is that Aeropay isn't enabled at merchant group level or your account isn't entitled to use the service."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Resolve the issue:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Go to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Merchant setup > Merchant groups"]}," in the Unity Portal."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Select the merchant group and open the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Services"]}," tab."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Add or enable ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Aeropay service"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Return to the site and configure the service."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/components/ios/aeropay/onboarding"},"children":["Aeropay onboarding"]}," for the complete steps."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"aeropay-is-missing-from-the-session","__idx":8},"children":["Aeropay is missing from the session"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The session doesn't contain ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allowedFundingTypes.payByBanks.aeropay"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Check that:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The session request uses the correct merchant and site."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Aeropay is active for that site."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Merchant ID, API key, API secret, and configuration ID are saved."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The session was created after the portal configuration was saved."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Session request: include a supported Aeropay intent (for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionMethod.intent.aeropay"]},"). iOS SDK: set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionData.intent.aeropay"]}," when building ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutConfig"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create a new session after correcting the service."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"sdk0113-during-component-creation","__idx":9},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0113"]}," during component creation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Inspect the session response for both Aeropay funding values:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"let aeropay = session.allowedFundingTypes?.payByBanks?.aeropay\nlet hasExternalMerchantId = !(aeropay?.externalMerchantId?.isEmpty ?? true)\nlet hasConfigurationId = !(aeropay?.configurationId?.isEmpty ?? true)\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalMerchantId"]}," is missing, check the Aeropay Merchant ID in the site configuration. If ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["configurationId"]}," is missing, check the Aerosync Configuration ID."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"button-and-popup-issues","__idx":10},"children":["Button and popup issues"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"button-doesnt-render","__idx":11},"children":["Button doesn't render"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Check the following causes:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create"]}," threw an exception that wasn't caught."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The component wasn't stored in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@State"]}," before ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["buildContent()"]}," ran."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The view left the hierarchy before creation finished."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The button is disabled, hidden, or covered by another view."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Custom styles hide the button against the checkout background."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create the component in a lifecycle-aware ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Task"]},", then render ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["buildContent()"]}," only after creation succeeds."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"tapping-the-button-does-nothing","__idx":12},"children":["Tapping the button does nothing"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Check whether:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The button is disabled."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A popup is already open."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A previous start operation is still loading."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onCustomValidation"]}," returned ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onGetShopper"]}," is waiting indefinitely."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Invalid shopper data caused ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1300"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A returning-user lookup is still running or failed."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onClick"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onCustomValidation"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," logging, then check Xcode console and network traffic for stalled requests."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"popup-closes-unexpectedly","__idx":13},"children":["Popup closes unexpectedly"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["User dismissals call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onCancel"]},". Successful payment dismissal is programmatic and doesn't call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onCancel"]},". In either case, restore the checkout so the shopper can continue or restart the flow."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If neither dismissal explains the outcome, check for:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Navigation away from the checkout screen."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["View recreation without restoring component state."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An unhandled exception."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Session or network failure."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"shopper-data-issues","__idx":14},"children":["Shopper data issues"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"sdk1300-before-the-popup-opens","__idx":15},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1300"]}," before the popup opens"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onGetShopper"]}," returned a non-empty invalid ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["firstName"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lastName"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["email"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["phoneNumber"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Check that:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Names contain only Unicode letters and spaces."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Email addresses match the SDK format and stay within 128 characters."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Phone numbers use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["+1"]}," followed by exactly ten digits."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Return empty values for unknown fields instead of placeholders such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["N/A"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"consumer-data-screen-still-appears-when-skipping","__idx":16},"children":["Consumer data screen still appears when skipping"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["skipConsumerDataCollection"]}," only skips the screen when all four fields are non-empty and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["editableFields"]}," is omitted, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nil"]},", or empty. If any field is missing or editable, the screen still appears."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"returning-shopper-issues","__idx":17},"children":["Returning-shopper issues"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"sdk1307-or-sdk1308","__idx":18},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1307"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1308"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The stored Aeropay user ID isn't usable."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Resolve the issue:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Remove the stored ID for that customer."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Start the new-shopper flow."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Save the new verified ID from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onUserVerificationSuccess"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"bank-linking-issues","__idx":19},"children":["Bank linking issues"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"aerosync-doesnt-open","__idx":20},"children":["Aerosync doesn't open"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Check that:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The shopper completed verification or entered with a valid ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["userId"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your app handles ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{callbackScheme}://aerosync/callback"]},", where the scheme comes from the SDK configuration and defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pxpcheckout"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The callback scheme is registered in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Info.plist"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CFBundleURLSchemes"]},"). Sample apps use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pxpcheckout"]},". If you set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PXP_CALLBACK_SCHEME"]}," in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sdk-config.json"]},", use the same value. A mismatched or missing URL type prevents Aerosync OAuth from returning to your app during UAT."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The URL scheme matches the SDK distribution you're using."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The SDK environment matches the Aeropay UAT or production configuration."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Missing a verified Aeropay user ID on the bank-selection screen typically surfaces as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1303"]}," on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," when the bank list loads. Some link-bank / credentials paths show only inline or alert feedback without ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]},". Don't diagnose missing verification primarily via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1311"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"bank-list-is-empty-on-payout","__idx":21},"children":["Bank list is empty on payout"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["By default, payouts hide bank linking. Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bankSelectionConfig.allowLinkBankOnPayout"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," if shoppers need to link an account during payout."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"transaction-issues","__idx":22},"children":["Transaction issues"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"transaction-never-submits","__idx":23},"children":["Transaction never submits"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Confirm that ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onPreAuthorisation"]}," is implemented and returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},". Omitting the callback or returning ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}," aborts submission without calling ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSubmitError"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onCancel"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," — the bank-selection screen stays open."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"submission-fails","__idx":24},"children":["Submission fails"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Handle ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSubmitError"]}," and cast to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FailedSubmitResult"]}," before reading ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorCode"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorReason"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["correlationId"]},". Those properties aren't on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BaseSubmitResult"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"config.onSubmitError = { error in\n    guard let failed = error as? FailedSubmitResult else { return }\n    // Log failed.errorCode, failed.errorReason, and failed.correlationId in restricted logs\n}\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Then verify the transaction state on your backend before showing a final result to the shopper."]}]},"headings":[{"value":"Troubleshooting","id":"troubleshooting","depth":1},{"value":"Error handling","id":"error-handling","depth":2},{"value":"Error code reference","id":"error-code-reference","depth":2},{"value":"Setup and configuration","id":"setup-and-configuration","depth":3},{"value":"Aeropay flow","id":"aeropay-flow","depth":3},{"value":"Collect safe diagnostic information","id":"collect-safe-diagnostic-information","depth":2},{"value":"Portal and session setup","id":"portal-and-session-setup","depth":2},{"value":"Aeropay isn't available in site services","id":"aeropay-isnt-available-in-site-services","depth":3},{"value":"Aeropay is missing from the session","id":"aeropay-is-missing-from-the-session","depth":3},{"value":"SDK0113 during component creation","id":"sdk0113-during-component-creation","depth":3},{"value":"Button and popup issues","id":"button-and-popup-issues","depth":2},{"value":"Button doesn't render","id":"button-doesnt-render","depth":3},{"value":"Tapping the button does nothing","id":"tapping-the-button-does-nothing","depth":3},{"value":"Popup closes unexpectedly","id":"popup-closes-unexpectedly","depth":3},{"value":"Shopper data issues","id":"shopper-data-issues","depth":2},{"value":"SDK1300 before the popup opens","id":"sdk1300-before-the-popup-opens","depth":3},{"value":"Consumer data screen still appears when skipping","id":"consumer-data-screen-still-appears-when-skipping","depth":3},{"value":"Returning-shopper issues","id":"returning-shopper-issues","depth":2},{"value":"SDK1307 or SDK1308","id":"sdk1307-or-sdk1308","depth":3},{"value":"Bank linking issues","id":"bank-linking-issues","depth":2},{"value":"Aerosync doesn't open","id":"aerosync-doesnt-open","depth":3},{"value":"Bank list is empty on payout","id":"bank-list-is-empty-on-payout","depth":3},{"value":"Transaction issues","id":"transaction-issues","depth":2},{"value":"Transaction never submits","id":"transaction-never-submits","depth":3},{"value":"Submission fails","id":"submission-fails","depth":3}],"frontmatter":{"seo":{"title":"Troubleshooting"}},"lastModified":"2026-08-11T10:42:42.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/checkout/components/ios/aeropay/troubleshooting","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}