How it works

Aeropay is a US pay-by-bank payment method. PXP's Aeropay button component for Android renders a payment button and guides shoppers through identity verification, bank account selection, and transaction submission in a modal bottom sheet.

With the Aeropay component, you can benefit from:

• Pay-by-bank checkout: Allow shoppers to pay directly from a linked bank account.
• Built-in verification: Collect shopper details and verify new Aeropay users with a one-time passcode (OTP) sent to the shopper's phone.
• Bank linking: Let shoppers link a bank account through the embedded Aerosync experience.
• Faster returning-shopper flows: Use a verified Aeropay user ID to skip data collection and OTP verification.
• Flexible transaction processing: Support authorisations, purchases, estimated authorisations, and payouts.
• Customisable presentation: Configure the button, popup, form fields, OTP screen, and bank selection screen.

The component adapts the checkout flow based on whether the shopper has a verified Aeropay user ID.

Provide shopper details through PxpSdkConfig.onGetShopper when initialising PxpCheckout. Component-only settings such as userId, skipConsumerDataCollection, and consumerDataCollectionConfig are configured on AeropayButtonComponentConfig.

The Aeropay payment flow has five steps.

When you create the component, the SDK:

1. Validates the session and transaction configuration.
2. Confirms that the currency is USD and the entry type is Ecom.
3. Confirms that the session contains the Aeropay funding configuration.
4. Makes the Aeropay button available to render with Content().

If session funding, transactionData.intent.aeropay, currency, or entry type are invalid, createComponent(ComponentType.AERO_PAY_BUTTON, …) throws a BaseSdkException (e.g., SDK0113, SDK0114, SDK0115, or SDK0116) and the button isn't created. Handle these at creation time. AeropayButtonComponentConfig.onError is for runtime failures after the component exists (e.g., invalid prefilled shopper data with SDK1300).

When the shopper taps the button, the SDK runs optional onCustomValidation, then checks the component configuration:

• If userId contains a verified, active Aeropay user ID, the SDK opens the bank selection screen.
• If userId isn't set, the SDK gets available shopper details from PxpSdkConfig.onGetShopper (when configured) and starts the new-shopper flow.

For a new shopper, the component collects their first name, last name, email address, and phone number. You can prefill these fields through PxpSdkConfig.onGetShopper when their values are valid. If a supplied name, email address, or phone number is non-empty but invalid, the SDK invokes AeropayButtonComponentConfig.onError with a BaseSdkException (errorCode = SDK1300) and doesn't open the popup.

The component creates the Aeropay user and sends an OTP to the shopper's phone. After the shopper enters the correct code, the SDK calls onUserVerificationSuccess with the verified user details.

Store the returned user.id securely if you want to use the returning-shopper flow on future visits.

The component loads the shopper's linked bank accounts. The shopper can select an existing account or link a new one through Aerosync.

For payouts, the bank-linking option is hidden by default. Assign a BankSelectionConfig and set allowLinkBankOnPayout to true to let shoppers link a bank account during a payout flow:

config.bankSelectionConfig = BankSelectionConfig(allowLinkBankOnPayout = true)

After the shopper selects a bank account and confirms the transaction, the SDK:

1. Calls onPreAuthorisation (required for submission). Return true to submit; otherwise the flow stops.
2. Builds and submits the pay-by-bank transaction to PXP.
3. Calls onPostAuthorisation (optional) after a successful MerchantSubmitResult.
4. Calls onSubmitError (optional) when submission returns a failed result or network error.

Configure onPreAuthorisation on AeropayButtonComponentConfig and return true to allow the SDK to submit the transaction. If the callback isn't set, or it returns false, the SDK doesn't call the PXP API and the popup stays open. For callback details, see Events and Implementation.

// Required for payment submission — return true to proceed.
// If omitted or returns false, the SDK does not submit and the popup stays open.
config.onPreAuthorisation = { true }

Always verify the transaction on your backend before fulfilling an order or confirming a payout.

When userId isn't set, the SDK uses the result from PxpSdkConfig.onGetShopper to determine how the data collection screen behaves:

The required shopper details are firstName, lastName, email, and phoneNumber. Providing all four fields doesn't skip the data collection screen by itself. You must also set skipConsumerDataCollection to true and omit editableFields or set it to null or an empty list.

phoneNumber from onGetShopper must be a valid US E.164 value (e.g., +15550123456) when prefilled. Invalid non-empty values trigger SDK1300 before the popup opens. When skipConsumerDataCollection is true, the phone number must also normalise to a non-empty E.164 value or the skip path isn't taken.

When editableFields is null or empty, prefilled fields are read-only. Add a field to editableFields only when the shopper needs to change it.

For a returning shopper, pass the verified Aeropay user ID to the component as userId. The SDK validates that the user is active before opening bank selection.

If the user isn't active, AeropayButtonComponentConfig.onError receives SDK1307. If the get-user API returns a recognised failure (including user not found), onError receives SDK1308. Network or transport errors on the same call use SDK0500 or SDK0000. The popup doesn't open in these cases. Your application should then offer an appropriate recovery path, such as starting a new-shopper flow.

Configure the Aeropay intent in both the session request and the SDK's transaction data:

In the session request, set transactionMethod.intent.aeropay. When initialising the SDK, set transactionData.intent.aeropay to the corresponding AeropayIntentType value. Button and action labels adapt for payout flows, for example Withdraw by Bank instead of Pay by bank.

Continue with the Aeropay integration guides:

• Onboarding: Configure Aeropay in the Unity Portal.
• Implementation: Integrate and render the Aeropay button.
• Configuration: Customise the component's appearance and behaviour.
• Events: Handle component callbacks and transaction results.