{"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"},"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":["pxpSdk.create()"]},"."]}]},{"$$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":["Unexpected Aeropay result shape"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The component can show generic inline feedback without calling ",{"$$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 uses the popup close button"]},{"$$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 all three error paths in your integration:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"try {\n  const aeropayButton = pxpSdk.create('aeropay-button', {\n    onCancel: () => {\n      resetCheckoutState();\n    },\n    onPreAuthorisation: () => true,\n    onPostAuthorisation: (result) => {\n      const submitResult = result as {\n        merchantTransactionId: string;\n        systemTransactionId: string;\n      };\n      verifyPaymentOnBackend({\n        merchantTransactionId: submitResult.merchantTransactionId,\n        systemTransactionId: submitResult.systemTransactionId\n      });\n    },\n    onSubmitError: (error) => {\n      console.error('Aeropay submission failed', error);\n      showPaymentError('Unable to complete the transaction.');\n    },\n    onError: (error) => {\n      console.error('Aeropay flow failed', {\n        errorCode: error.ErrorCode,\n        message: error.message\n      });\n      showPaymentError('Unable to continue with Aeropay.');\n    }\n  });\n\n  aeropayButton.mount('aeropay-button-container');\n} catch (error) {\n  console.error('Aeropay configuration failed', error);\n  showAlternativePaymentMethods();\n}\n","lang":"typescript"},"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 or mounting 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"]},"."]}]},{"$$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":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0201"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Mount container wasn't found."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Add the container to the DOM before calling ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mount()"]}," and check its ID."]}]}]}]}]},{"$$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":["Inspect ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.details"]}," and 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 or aggregator-credential lookup failed."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Identify the active screen and inspect restricted error details. This code is used by both operations."]}]},{"$$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."]},{"$$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":["SDK1309"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The Aeropay user wasn't found."]},{"$$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":["SDK1310"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A truthy non-string ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["userId"]}," was supplied at runtime."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Pass a string. Falsy values, including an empty string, don't produce this error and start the new-shopper flow."]}]},{"$$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":["Aeropay transaction failure recorded for analytics."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Don't expect this code in the normal ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSubmitError"]}," callback. An ordinary failed transaction response passes a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FailedSubmitResult"]}," to that callback."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The component creates ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1311"]}," to emit ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ComponentError"]}," analytics after an ordinary failed transaction response. It doesn't pass that exception to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSubmitError"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Network failures can also produce ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0500"]},". Determine whether the failure occurred before transaction submission or during submission so you can handle it through the correct callback."]},{"$$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":"typescript","header":{"controls":{"copy":{}}},"source":"function logAeropayDiagnostics({\n  session,\n  transactionData,\n  environment\n}) {\n  const aeropay = session.allowedFundingTypes?.payByBanks?.aeropay;\n\n  console.log('Aeropay diagnostics', {\n    environment,\n    sessionId: session.sessionId,\n    hasExternalMerchantId: Boolean(aeropay?.externalMerchantId),\n    hasConfigurationId: Boolean(aeropay?.configurationId),\n    currency: transactionData.currency,\n    entryType: transactionData.entryType,\n    intent: transactionData.intent?.aeropay,\n    merchantTransactionId: transactionData.merchantTransactionId\n  });\n}\n","lang":"typescript"},"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/web/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":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionMethod.intent.aeropay"]}," contains a supported intent."]}]},{"$$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:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"const aeropay =\n  sessionResult.session.allowedFundingTypes?.payByBanks?.aeropay;\n\nconsole.log({\n  hasExternalMerchantId: Boolean(aeropay?.externalMerchantId),\n  hasConfigurationId: Boolean(aeropay?.configurationId)\n});\n","lang":"typescript"},"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":["pxpSdk.create()"]}," threw an exception that wasn't caught."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The mount container doesn't exist yet."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The container ID passed to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mount()"]}," doesn't match the DOM."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The component is disabled or hidden by application state."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Custom CSS hides the container or button."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A route change unmounted the component."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Mount only after the container exists:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"html","header":{"controls":{"copy":{}}},"source":"<div id=\"aeropay-button-container\"></div>\n","lang":"html"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"const aeropayButton = pxpSdk.create('aeropay-button', {\n  onPreAuthorisation: () => true\n});\n\naeropayButton.mount('aeropay-button-container');\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the container is missing, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mount()"]}," throws ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0201"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"clicking-the-button-does-nothing","__idx":12},"children":["Clicking 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":["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"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," logging, then check the browser network panel 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":["The popup close button calls ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onCancel"]},". Pressing Escape currently hides the popup without calling ",{"$$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 close action explains the outcome, check for:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A route change or component unmount."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Application code removing the container."]},{"$$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":["The SDK validates non-empty fields returned by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onGetShopper"]},". Inspect ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.details"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"onError: (error) => {\n  if (error.ErrorCode === 'SDK1300') {\n    console.error('Invalid shopper fields', error.details);\n    showPaymentError('Check your contact details and try again.');\n  }\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Apply these formats:"]},{"$$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":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required format"},"children":["Required format"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["firstName"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unicode letters and spaces, up to 100 characters"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lastName"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unicode letters and spaces, up to 100 characters"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["email"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A valid address containing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@"]}," and a domain dot, up to 128 characters"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["phoneNumber"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["+1"]}," followed by exactly 10 digits"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Empty or omitted values are collected in the popup. Invalid non-empty values stop the popup from opening."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"prefilled-fields-cant-be-edited","__idx":16},"children":["Prefilled fields can't be edited"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is the default behaviour. Add the fields to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["consumerDataCollectionConfig.editableFields"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"consumerDataCollectionConfig: {\n  editableFields: ['email', 'phoneNumber']\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"consumer-data-screen-appears-unexpectedly","__idx":17},"children":["Consumer data screen appears unexpectedly"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["skipConsumerDataCollection: true"]},", check that:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onGetShopper"]}," returns all four required fields."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Every field is non-empty and valid."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["consumerDataCollectionConfig.editableFields"]}," is empty or omitted."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Missing or empty values, or a non-empty ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["editableFields"]}," configuration, cause the component to show the consumer data collection screen. Invalid non-empty values supplied by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onGetShopper"]}," invoke ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1300"]}," and prevent the popup from opening."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"valid-customer-name-is-rejected","__idx":18},"children":["Valid customer name is rejected"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The current validator accepts Unicode letters and spaces only. Apostrophes, hyphens, digits, and other punctuation fail validation."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If legitimate customer names can't pass the field, capture the example without personal data and contact PXP support."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"otp-issues","__idx":19},"children":["OTP issues"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"otp-isnt-accepted","__idx":20},"children":["OTP isn't accepted"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The UI removes non-digit characters and enables ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Verify code"]}," only after all six-digit cells contain a value. If the shopper can't continue, check for an incomplete code. Empty or malformed-input messages are defensive validation and aren't normally shown through standard typing, pasting, or button use."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If a six-digit code fails:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Confirm that the shopper is using the most recent code."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check whether the code expired."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1302"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Inspect the network request and provider status."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Let the shopper resend after the countdown."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"resend-is-disabled","__idx":21},"children":["Resend is disabled"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The resend action remains disabled during its 59-second countdown and while a resend request is in progress."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If both resend and verification remain disabled, Aeropay may have reported the maximum number of attempts (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["providerResponseCode"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AP112"]},"). Close the flow and follow your approved recovery process."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"verification-fails-with-sdk1302","__idx":22},"children":["Verification fails with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1302"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1302"]}," is used for both OTP verification and aggregator-credential lookup. Use the active screen to identify the operation:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["On the OTP screen, check the code, attempt limit, and verification response."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["On the bank-linking screen, check the Aerosync credential request and configuration ID."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Don't infer the failing operation from the error code alone."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"returning-shopper-issues","__idx":23},"children":["Returning-shopper issues"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"bank-selection-doesnt-open","__idx":24},"children":["Bank selection doesn't open"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you supplied ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["userId"]},", check ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]},":"]},{"$$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":"20%","data-label":"Error"},"children":["Error "]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Recovery"},"children":["Recovery"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$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":["User isn't active. Remove the stored ID and start a 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":["Lookup failed. Check network and provider status before deciding whether to retry."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1309"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["User wasn't found. Remove the stored ID and start a new-shopper flow."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1310"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Validate that a truthy ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["userId"]}," is a string from the correct customer record. Falsy values start the new-shopper flow rather than producing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1310"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["userId"]}," is falsy, expect consumer data collection instead of direct bank selection."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Don't automatically fall back to another customer's ID or accept an ID supplied by the browser."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"bank-selection-and-aerosync-issues","__idx":25},"children":["Bank selection and Aerosync issues"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"bank-list-is-empty","__idx":26},"children":["Bank list is empty"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An empty list can mean that the shopper has no linked accounts or that retrieval failed."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Check whether:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The UI shows the expected empty state without ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," received ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1306"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The Aeropay user is active."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The request used the expected UAT or production environment."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Aeropay or PXP reported an outage."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For a payment, let the shopper link an account. For a payout, bank linking is hidden unless ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allowLinkBankOnPayout"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"aerosync-doesnt-open","__idx":27},"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":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["configurationId"]}," is present in the session."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Aggregator credentials were retrieved successfully."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Browser content-security or network controls don't block required provider resources."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Another link-bank operation isn't already loading."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The component hasn't been unmounted."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1302"]}," can indicate failed aggregator credentials. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1304"]}," indicates an Aerosync widget failure."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"linked-account-doesnt-appear","__idx":28},"children":["Linked account doesn't appear"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The widget can complete before PXP finishes linking and refreshing the bank list."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Wait for the loading state to finish. If the account still doesn't appear, check for:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1303"]}," for an invalid widget result."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1305"]}," for a link-account failure."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1306"]}," when refreshing bank accounts."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A connection ID missing from the provider result."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Don't ask the shopper to repeat linking until you know whether the first attempt completed."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"transaction-issues","__idx":29},"children":["Transaction issues"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"confirming-the-bank-doesnt-submit-a-transaction","__idx":30},"children":["Confirming the bank doesn't submit a transaction"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The most common cause is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onPreAuthorisation"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The SDK submits only when the callback returns a truthy value:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"onPreAuthorisation: async () => {\n  const result = await validateOrderOnBackend();\n  return result.approved;\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Check that:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The callback is configured."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Every code path returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An awaited backend request resolves."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Validation intentionally approves the current transaction."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The callback doesn't throw."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the callback is omitted or returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["undefined"]},", the SDK stops submission."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"onsubmiterror-runs","__idx":31},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSubmitError"]}," runs"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Ordinary failed transaction responses pass a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FailedSubmitResult"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSubmitError"]},". They don't pass the analytics-only ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1311"]}," exception. Inspect the payload shape before reading fields:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"onSubmitError: (error) => {\n  if (\n    typeof error === 'object' &&\n    error !== null &&\n    'errorCode' in error\n  ) {\n    console.error('PXP submission failure', {\n      errorCode: error.errorCode,\n      correlationId: error.correlationId,\n      httpStatusCode: error.httpStatusCode\n    });\n  } else {\n    console.error('SDK or network submission failure', error);\n  }\n\n  showPaymentError('Unable to complete the transaction.');\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For failed PXP responses, record ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorCode"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["correlationId"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["httpStatusCode"]},". For network failures, check connectivity, session validity, and whether the request reached PXP."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before retrying, retrieve the transaction from your backend using the existing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantTransactionId"]},". This prevents duplicate payments or payouts when the browser didn't receive the original response."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"onpostauthorisation-runs-but-the-order-isnt-confirmed","__idx":32},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onPostAuthorisation"]}," runs but the order isn't confirmed"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This normally means backend verification failed, is still pending, or found a mismatched transaction."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Check that your backend:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Uses the transaction identifiers from the callback only to retrieve the authoritative result."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Uses valid PXP API credentials."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Compares merchant, amount, currency, intent, and transaction state."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Correlates the transaction with the order or payout stored on your backend."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Returns a clear pending or failed state to the frontend."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Don't bypass backend verification to resolve the issue."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"payment-or-payout-may-have-been-submitted-twice","__idx":33},"children":["Payment or payout may have been submitted twice"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Stop automatic retries and retrieve every transaction associated with the merchant transaction identifier."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Check for:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Repeated button clicks."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Multiple mounted components."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A retry after a network timeout without checking transaction status."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Different ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantTransactionId"]}," values for the same order or payout."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Backend endpoints that don't enforce idempotency or duplicate protection."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Resolve the transaction state before allowing another attempt."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"analytics-issues","__idx":34},"children":["Analytics issues"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"expected-event-isnt-emitted","__idx":35},"children":["Expected event isn't emitted"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Check event-specific conditions:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PreAuthorisation"]}," requires ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onPreAuthorisation"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PostAuthorisation"]}," requires ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onPostAuthorisation"]}," and successful submission."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Aerosync events occur only during bank linking."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["User verification success doesn't have a dedicated SDK analytics event. Track it from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onUserVerificationSuccess"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Using the popup close button appears as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ComponentInteraction"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["interactionType: \"Close\""]}," and calls ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onCancel"]},". Pressing Escape currently hides the popup without this callback."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Log ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event.eventName"]}," temporarily to inspect the sequence. Remove verbose logging before production."]}]},"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":"Clicking the button does nothing","id":"clicking-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":"Prefilled fields can't be edited","id":"prefilled-fields-cant-be-edited","depth":3},{"value":"Consumer data screen appears unexpectedly","id":"consumer-data-screen-appears-unexpectedly","depth":3},{"value":"Valid customer name is rejected","id":"valid-customer-name-is-rejected","depth":3},{"value":"OTP issues","id":"otp-issues","depth":2},{"value":"OTP isn't accepted","id":"otp-isnt-accepted","depth":3},{"value":"Resend is disabled","id":"resend-is-disabled","depth":3},{"value":"Verification fails with SDK1302","id":"verification-fails-with-sdk1302","depth":3},{"value":"Returning-shopper issues","id":"returning-shopper-issues","depth":2},{"value":"Bank selection doesn't open","id":"bank-selection-doesnt-open","depth":3},{"value":"Bank selection and Aerosync issues","id":"bank-selection-and-aerosync-issues","depth":2},{"value":"Bank list is empty","id":"bank-list-is-empty","depth":3},{"value":"Aerosync doesn't open","id":"aerosync-doesnt-open","depth":3},{"value":"Linked account doesn't appear","id":"linked-account-doesnt-appear","depth":3},{"value":"Transaction issues","id":"transaction-issues","depth":2},{"value":"Confirming the bank doesn't submit a transaction","id":"confirming-the-bank-doesnt-submit-a-transaction","depth":3},{"value":"onSubmitError runs","id":"onsubmiterror-runs","depth":3},{"value":"onPostAuthorisation runs but the order isn't confirmed","id":"onpostauthorisation-runs-but-the-order-isnt-confirmed","depth":3},{"value":"Payment or payout may have been submitted twice","id":"payment-or-payout-may-have-been-submitted-twice","depth":3},{"value":"Analytics issues","id":"analytics-issues","depth":2},{"value":"Expected event isn't emitted","id":"expected-event-isnt-emitted","depth":3}],"frontmatter":{"seo":{"title":"Troubleshooting"}},"lastModified":"2026-08-04T12:13:26.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/checkout/components/web/aeropay/troubleshooting","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}