Learn about PXP's Aeropay component for Web.
Aeropay is a US pay-by-bank payment method. PXP's Aeropay component renders a payment button and guides shoppers through identity verification, bank account selection, and transaction submission in a popup.
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).
- 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.
Aeropay supports USD transactions with the Ecom entry type. Your session must include Aeropay in the allowedFundingTypes.
The component adapts the checkout flow based on whether the shopper has a verified Aeropay user ID:
| Journey | Configuration | Experience |
|---|---|---|
| New shopper | Don't set userId. | The shopper provides their details, verifies their identity with an OTP, and selects or links a bank account. |
| New shopper with known details | Return all required details from onGetShopper. You can also set skipConsumerDataCollection to true. | The component prefills valid shopper details. When data collection is skipped, the flow starts with OTP verification. |
| Returning shopper | Set userId to a verified, active Aeropay user ID. | The shopper goes directly to bank selection without completing data collection or OTP verification. |
The Aeropay payment flow has five steps.
When you create and mount the component, the SDK:
- Validates the session and transaction configuration.
- Confirms that the currency is
USDand the entry type isEcom. - Confirms that the session contains the Aeropay funding configuration.
- Renders the Aeropay button.
When the shopper clicks the button, the SDK:
- Calls optional
onCustomValidation. Returnfalseto stop before the popup opens. - Checks the component configuration for identification:
- If
userIdcontains a verified, active Aeropay user ID, the SDK opens the bank selection screen. - If
userIdisn't set, the SDK gets available shopper details fromonGetShopperand starts the new-shopper flow.
- If
For a new shopper, the component collects their first name, last name, email address, and phone number. You can prefill these fields through onGetShopper when their values are valid. If a supplied name, email address, or phone number is non-empty but invalid, the SDK invokes onError with SDK1300 and doesn't open the popup.
The component creates the Aeropay user and sends an OTP to the shopper's phone by SMS. 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. Set bankSelectionConfig.allowLinkBankOnPayout to true to let shoppers link a bank account during a payout flow.
After the shopper selects a bank account and confirms the transaction, the SDK:
- Calls
onPreAuthorisation. Returntrueto continue orfalseto stop the transaction. - Builds and submits the pay-by-bank transaction to PXP.
- Calls
onPostAuthorisationafter a successful submission oronSubmitErrorif submission fails.
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 onGetShopper to determine how the data collection screen behaves:
| Shopper data | Component behaviour |
|---|---|
onGetShopper isn't provided | Shows all fields as empty and editable. |
| Some required fields are provided | Prefills and disables the valid provided fields. The missing fields remain editable. |
| All required fields are provided | Prefills and disables all fields when they're valid, unless you include them in consumerDataCollectionConfig.editableFields. |
All required fields are provided and skipConsumerDataCollection is true | Creates the Aeropay user in the background and opens the OTP verification screen when all fields are valid. editableFields must be omitted or empty. |
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 an empty array.
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 doesn't exist or isn't active, the component calls onError and doesn't open the popup. 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:
| Intent | Description |
|---|---|
Authorisation | Authorise funds for later capture. |
Purchase | Complete the payment immediately. |
EstimatedAuthorisation | Submit an authorisation for an estimated amount. |
Payout | Send funds to the shopper's selected bank account. |
In the session request, set transactionMethod.intent.aeropay. When initialising the SDK, set transactionData.intent.aeropay to the corresponding IntentType value.
After a successful Aeropay transaction, you can perform follow-up actions manually in the Unity Portal under Report & Search > Report. Available actions depend on the transaction intent and current state.
These actions include:
- Capture: Capture funds for an authorised transaction.
- Increment: Increase the authorised amount.
- Void: Cancel an authorisation before it's captured.
- Refund: Return funds for a captured or purchased transaction.
A Purchase captures funds at submission, so it doesn't need a separate capture. Payout follow-up options differ from authorisation and purchase flows.
To take an action:
- In the Unity Portal, go to Report & Search > Report.
- Find the transaction using the
merchantTransactionIdorsystemTransactionIdfromonPostAuthorisation. - Open the transaction details and choose the required action.
Always verify the transaction on your backend before fulfilling an order or confirming a payout. Use reporting for operational follow-up after that verification.
Continue with the Aeropay integration guides:
- Onboarding: Configure Aeropay in the Unity Portal.
- Implementation: Integrate and mount the Aeropay button.
- Configuration: Customise the component's appearance and behaviour.
- Events: Handle component callbacks and transaction results.