Troubleshooting

Aeropay failures are reported through different paths:

Use these error paths in your integration:

import com.pxp.checkout.types.ComponentType
import com.pxp.checkout.components.aeropaybutton.types.AeropayButtonComponentConfig
import com.pxp.checkout.exceptions.BaseSdkException
import com.pxp.checkout.models.FailedSubmitResult
import com.pxp.checkout.models.MerchantSubmitResult

try {
    val aeropayButton = checkout.createComponent(
        ComponentType.AERO_PAY_BUTTON,
        AeropayButtonComponentConfig().apply {
            onCancel = {
                resetCheckoutState()
            }
            onPreAuthorisation = { true }
            onPostAuthorisation = { result: MerchantSubmitResult ->
                verifyPaymentOnBackend(result)
            }
            onSubmitError = { error ->
                if (error is FailedSubmitResult) {
                    showPaymentError("Unable to complete the transaction.")
                }
            }
            onError = { error ->
                showPaymentError("Unable to continue with Aeropay.")
            }
        },
    )
} catch (error: 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:

SDK13xx codes apply to recognised API or provider failure responses. Network or transport errors on the same operations can call onError with SDK0500 (or SDK0000) instead. Check error.errorCode in logs.

Mapped failed Unity transaction responses call onSubmitError with a FailedSubmitResult and emit ComponentError analytics with SDK1326. Network or transport failures 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:

import com.pxp.checkout.models.Environment
import com.pxp.checkout.models.SessionConfig
import com.pxp.checkout.models.TransactionData

fun logAeropayDiagnostics(
    session: SessionConfig,
    transactionData: TransactionData,
    environment: Environment,
) {
    val 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. The session response includes allowedFundingTypes.payByBanks.aeropay with non-empty externalMerchantId and configurationId.
6. PxpSdkConfig.transactionData.intent.aeropay is set to a supported AeropayIntentType before createComponent() (missing → SDK0115).

For the backend session request shape (including transactionMethod.intent.aeropay in the Sessions API JSON), see Onboarding — Verify session configuration.

Create a new session after correcting the service.

Inspect the session response for both Aeropay funding values:

val aeropay = session.allowedFundingTypes?.payByBanks?.aeropay
val hasExternalMerchantId = !aeropay?.externalMerchantId.isNullOrBlank()
val hasConfigurationId = !aeropay?.configurationId.isNullOrBlank()

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:

• createComponent() threw an exception that wasn't caught.
• The component wasn't stored in Compose state before Content() ran.
• The composable left the composition before creation finished.
• The button is disabled or covered by another view.
• Custom styles hide the button against the checkout background.

Create the component in a lifecycle-aware scope, then render Content() 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 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.
• Invalid shopper data caused SDK1300.
• A returning-user lookup is still running or failed.

Add onClick, onCustomValidation, and onError logging, then check Logcat 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.
• Process or Activity 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.

In restricted logs, inspect error.details on the BaseSdkException passed to onError to see which prefilled field failed validation.

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

The stored Aeropay user ID isn't usable. SDK1307 means the user exists but isn't active. SDK1308 means the user API returned a recognised failure response. Network or transport errors on the same lookup call onError with SDK0500 (or SDK0000), not SDK1308.

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.
• An Activity is available to host the redirect. Missing host Activity produces SDK1311.
• Bank linking returns to checkout after Aerosync. The SDK handles pxpcheckout://aerosync/callback through the library manifest. If linking fails to resume, check for Activity lifecycle issues (SDK1311) or environment mismatch, not missing merchant URI registration.
• The SDK environment matches the Aeropay UAT or production configuration.

Widget-level Aerosync failures call onError with SDK1304 and emit AerosyncFailed analytics. They may not emit ComponentError. Don't rely on ComponentError alone when diagnosing bank-linking failures.

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 stops submission without calling onSubmitError.

Handle onSubmitError and inspect FailedSubmitResult.errorCode, errorReason, and correlationId in restricted logs. Then verify the transaction state on your backend before showing a final result to the shopper.