{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["sub-heading"]},"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":["checkout.createComponent()"]},"."]}]},{"$$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":"kotlin","header":{"controls":{"copy":{}}},"source":"import com.pxp.checkout.types.ComponentType\nimport com.pxp.checkout.components.aeropaybutton.types.AeropayButtonComponentConfig\nimport com.pxp.checkout.exceptions.BaseSdkException\nimport com.pxp.checkout.models.FailedSubmitResult\nimport com.pxp.checkout.models.MerchantSubmitResult\n\ntry {\n    val aeropayButton = checkout.createComponent(\n        ComponentType.AERO_PAY_BUTTON,\n        AeropayButtonComponentConfig().apply {\n            onCancel = {\n                resetCheckoutState()\n            }\n            onPreAuthorisation = { true }\n            onPostAuthorisation = { result: MerchantSubmitResult ->\n                verifyPaymentOnBackend(result)\n            }\n            onSubmitError = { error ->\n                if (error is FailedSubmitResult) {\n                    showPaymentError(\"Unable to complete the transaction.\")\n                }\n            }\n            onError = { error ->\n                showPaymentError(\"Unable to continue with Aeropay.\")\n            }\n        },\n    )\n} catch (error: BaseSdkException) {\n    showAlternativePaymentMethods()\n}\n","lang":"kotlin"},"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":["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":["EntryType.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":["Aerosync returned an invalid payload."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Retry bank linking and inspect the widget result without logging bank data."]}]},{"$$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. Also emitted as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AerosyncFailed"]}," analytics. Widget-level failures call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1304"]},"; they may not emit ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ComponentError"]},". Listen for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AerosyncFailed"]},", not only ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ComponentError"]},"."]},{"$$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 with a recognised API failure response."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Check the stored ID, session, and provider availability. Network or transport errors on the same lookup call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0500"]}," (or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0000"]},"), not ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1308"]},"."]}]},{"$$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":["Aerosync couldn't launch because no host Activity was available."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ensure the component runs while an Activity is available to host the Aerosync redirect."]}]},{"$$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":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1326"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unity transaction submission returned a failed response mapped to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FailedSubmitResult"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Handle ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSubmitError"]},". Inspect ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorCode"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorReason"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["correlationId"]}," in restricted logs, then verify the transaction on your backend. Not delivered through ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK13xx"]}," codes apply to recognised API or provider failure responses. Network or transport errors on the same operations can call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0500"]}," (or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0000"]},") instead. Check ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.errorCode"]}," in logs."]},{"$$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":"Codes"},"children":["Codes"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"API or provider failure"},"children":["API or provider failure"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Transport failure"},"children":["Transport failure"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1301"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1302"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1305"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1306"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1319"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Recognised API failure responses"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0500"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0000"]}]}]},{"$$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":["Recognised get-user API failure"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0500"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0000"]}]}]}]}]}]},{"$$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 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":"kotlin","header":{"controls":{"copy":{}}},"source":"import com.pxp.checkout.models.Environment\nimport com.pxp.checkout.models.SessionConfig\nimport com.pxp.checkout.models.TransactionData\n\nfun logAeropayDiagnostics(\n    session: SessionConfig,\n    transactionData: TransactionData,\n    environment: Environment,\n) {\n    val 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":"kotlin"},"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/android/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":["The session response includes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allowedFundingTypes.payByBanks.aeropay"]}," with non-empty ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalMerchantId"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["configurationId"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PxpSdkConfig.transactionData.intent.aeropay"]}," is set to a supported ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AeropayIntentType"]}," before ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["createComponent()"]}," (missing → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0115"]},")."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For the backend session request shape (including ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionMethod.intent.aeropay"]}," in the Sessions API JSON), see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/components/android/aeropay/onboarding#step-4-verify-session-configuration"},"children":["Onboarding — Verify session configuration"]},"."]},{"$$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":"kotlin","header":{"controls":{"copy":{}}},"source":"val aeropay = session.allowedFundingTypes?.payByBanks?.aeropay\nval hasExternalMerchantId = !aeropay?.externalMerchantId.isNullOrBlank()\nval hasConfigurationId = !aeropay?.configurationId.isNullOrBlank()\n","lang":"kotlin"},"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":["createComponent()"]}," threw an exception that wasn't caught."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The component wasn't stored in Compose state before ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Content()"]}," ran."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The composable left the composition before creation finished."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The button is disabled 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 scope, then render ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Content()"]}," 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"]}," performs synchronous work. Blocking calls inside it (network requests, locks) stall the flow before the popup opens. Prefetch shopper data before the tap or return cached values quickly."]},{"$$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 Logcat 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":["Process or Activity 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":"p","attributes":{},"children":["In restricted logs, inspect ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.details"]}," on the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BaseSdkException"]}," passed to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," to see which prefilled field failed validation."]},{"$$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":["null"]},", 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":"code","attributes":{},"children":["SDK1307"]}," means the user exists but isn't active. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1308"]}," means the user API returned a recognised failure response. Network or transport errors on the same lookup call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0500"]}," (or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0000"]},"), not ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1308"]},"."]},{"$$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":["An Activity is available to host the redirect. Missing host Activity produces ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1311"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Bank linking returns to checkout after Aerosync. The SDK handles ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pxpcheckout://aerosync/callback"]}," through the library manifest. If linking fails to resume, check for Activity lifecycle issues (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1311"]},") or environment mismatch, not missing merchant URI registration."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The SDK environment matches the Aeropay UAT or production configuration."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Widget-level Aerosync failures call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1304"]}," and emit ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AerosyncFailed"]}," analytics. They may not emit ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ComponentError"]},". Don't rely on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ComponentError"]}," alone when diagnosing bank-linking failures."]},{"$$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"]}," stops submission without calling ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSubmitError"]},"."]},{"$$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 inspect ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FailedSubmitResult.errorCode"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorReason"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["correlationId"]}," in restricted logs. 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-13T10:57:11.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/checkout/components/android/aeropay/troubleshooting","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}