Troubleshooting

Aeropay failures are reported through different paths:

Use these error paths in your integration:

do {
    let config = AeropayButtonComponentConfig()
    config.onCancel = {
        resetCheckoutState()
    }
    config.onPreAuthorisation = { true }
    config.onPostAuthorisation = { result in
        verifyPaymentOnBackend(result)
    }
    config.onSubmitError = { error in
        guard let failed = error as? FailedSubmitResult else { return }
        // Log failed.errorCode, failed.errorReason, and failed.correlationId in restricted logs
        showPaymentError("Unable to complete the transaction.")
    }
    config.onError = { _ in
        showPaymentError("Unable to continue with Aeropay.")
    }
    let aeropayButton = try pxpCheckout.create(.aeropayButton, componentConfig: config)
} catch let error as BaseSdkException {
    showAlternativePaymentMethods()
}

Don't show raw provider or SDK messages to shoppers. Map failures to approved user-facing messages and keep technical details in restricted logs.

These SDK errors occur when creating the component:

These errors can occur after the shopper starts the Aeropay flow:

Missing a verified Aeropay user ID on the bank-selection screen typically surfaces as SDK1303 on onError when the bank list loads. Some link-bank / credentials paths show only inline or alert feedback without onError. Don't diagnose missing verification primarily via SDK1311.

Mapped failed Unity transaction responses call onSubmitError with a FailedSubmitResult and emit ComponentError analytics with SDK1326. Network or transport failures after Unity submission also call onSubmitError, but their analytics code can differ. Don't expect SDK1326 on onError.

Record identifiers and configuration presence without logging credentials or personal data:

func logAeropayDiagnostics(
    session: SessionData,
    transactionData: TransactionData,
    environment: Environment
) {
    let aeropay = session.allowedFundingTypes?.payByBanks?.aeropay
    // Log only:
    // environment
    // session.sessionId
    // whether externalMerchantId and configurationId are present
    // transactionData.currency
    // transactionData.entryType
    // transactionData.intent.aeropay
    // transactionData.merchantTransactionId
}

Don't log hmacKey, encryptionKey, PXP tokens, Aeropay credentials, shopper details, OTPs, user IDs, or bank account metadata.

If a PXP token or Aeropay secret may have been exposed:

1. Revoke or replace the affected credential.
2. Update the backend secret store and redeploy the affected service.
3. Review logs, analytics, screenshots, and support records for further exposure.
4. Retest session creation and the Aeropay flow with the replacement credential.

The likely cause is that Aeropay isn't enabled at merchant group level or your account isn't entitled to use the service.

Resolve the issue:

1. Go to Merchant setup > Merchant groups in the Unity Portal.
2. Select the merchant group and open the Services tab.
3. Add or enable Aeropay service.
4. Return to the site and configure the service.

See Aeropay onboarding for the complete steps.

The session doesn't contain allowedFundingTypes.payByBanks.aeropay.

Check that:

1. The session request uses the correct merchant and site.
2. Aeropay is active for that site.
3. Merchant ID, API key, API secret, and configuration ID are saved.
4. The session was created after the portal configuration was saved.
5. Session request: include a supported Aeropay intent (for example transactionMethod.intent.aeropay). iOS SDK: set transactionData.intent.aeropay when building CheckoutConfig.

Create a new session after correcting the service.

Inspect the session response for both Aeropay funding values:

let aeropay = session.allowedFundingTypes?.payByBanks?.aeropay
let hasExternalMerchantId = !(aeropay?.externalMerchantId?.isEmpty ?? true)
let hasConfigurationId = !(aeropay?.configurationId?.isEmpty ?? true)

If externalMerchantId is missing, check the Aeropay Merchant ID in the site configuration. If configurationId is missing, check the Aerosync Configuration ID.

Check the following causes:

• create threw an exception that wasn't caught.
• The component wasn't stored in @State before buildContent() ran.
• The view left the hierarchy before creation finished.
• The button is disabled, hidden, or covered by another view.
• Custom styles hide the button against the checkout background.

Create the component in a lifecycle-aware Task, then render buildContent() only after creation succeeds.

Check whether:

• The button is disabled.
• A popup is already open.
• A previous start operation is still loading.
• onCustomValidation returned false.
• onGetShopper is waiting indefinitely.
• Invalid shopper data caused SDK1300.
• A returning-user lookup is still running or failed.

Add onClick, onCustomValidation, and onError logging, then check Xcode console and network traffic for stalled requests.

User dismissals call onCancel. Successful payment dismissal is programmatic and doesn't call onCancel. In either case, restore the checkout so the shopper can continue or restart the flow.

If neither dismissal explains the outcome, check for:

• Navigation away from the checkout screen.
• View recreation without restoring component state.
• An unhandled exception.
• Session or network failure.

onGetShopper returned a non-empty invalid firstName, lastName, email, or phoneNumber.

Check that:

• Names contain only Unicode letters and spaces.
• Email addresses match the SDK format and stay within 128 characters.
• Phone numbers use +1 followed by exactly ten digits.

Return empty values for unknown fields instead of placeholders such as N/A.

skipConsumerDataCollection only skips the screen when all four fields are non-empty and editableFields is omitted, nil, or empty. If any field is missing or editable, the screen still appears.

The stored Aeropay user ID isn't usable.

Resolve the issue:

1. Remove the stored ID for that customer.
2. Start the new-shopper flow.
3. Save the new verified ID from onUserVerificationSuccess.

Check that:

• The shopper completed verification or entered with a valid userId.
• Your app handles {callbackScheme}://aerosync/callback, where the scheme comes from the SDK configuration and defaults to pxpcheckout.
• The callback scheme is registered in Info.plist (CFBundleURLSchemes). Sample apps use pxpcheckout. If you set PXP_CALLBACK_SCHEME in sdk-config.json, use the same value. A mismatched or missing URL type prevents Aerosync OAuth from returning to your app during UAT.
• The URL scheme matches the SDK distribution you're using.
• The SDK environment matches the Aeropay UAT or production configuration.

Missing a verified Aeropay user ID on the bank-selection screen typically surfaces as SDK1303 on onError when the bank list loads. Some link-bank / credentials paths show only inline or alert feedback without onError. Don't diagnose missing verification primarily via SDK1311.

By default, payouts hide bank linking. Set bankSelectionConfig.allowLinkBankOnPayout to true if shoppers need to link an account during payout.

Confirm that onPreAuthorisation is implemented and returns true. Omitting the callback or returning false aborts submission without calling onSubmitError, onCancel, or onError — the bank-selection screen stays open.

Handle onSubmitError and cast to FailedSubmitResult before reading errorCode, errorReason, and correlationId. Those properties aren't on BaseSubmitResult.

config.onSubmitError = { error in
    guard let failed = error as? FailedSubmitResult else { return }
    // Log failed.errorCode, failed.errorReason, and failed.correlationId in restricted logs
}

Then verify the transaction state on your backend before showing a final result to the shopper.