Skip to content

How it works

Learn about PXP's Aeropay component for Web.

Overview

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.

Shopper journeys

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

JourneyConfigurationExperience
New shopperDon'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 detailsReturn 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 shopperSet userId to a verified, active Aeropay user ID.The shopper goes directly to bank selection without completing data collection or OTP verification.

Payment flow

The Aeropay payment flow has five steps.

Step 1: Component initialisation

When you create and mount 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. Renders the Aeropay button.

Step 2: Shopper identification

When the shopper clicks the button, the SDK:

  1. Calls optional onCustomValidation. Return false to stop before the popup opens.
  2. Checks the component configuration for identification:
    • 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 onGetShopper 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 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.

Step 3: User verification

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.

Step 4: Bank selection

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.

Step 5: Transaction submission

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

  1. Calls onPreAuthorisation. Return true to continue or false to stop the transaction.
  2. Builds and submits the pay-by-bank transaction to PXP.
  3. Calls onPostAuthorisation after a successful submission or onSubmitError if submission fails.

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

Consumer data collection

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

Shopper dataComponent behaviour
onGetShopper isn't providedShows all fields as empty and editable.
Some required fields are providedPrefills and disables the valid provided fields. The missing fields remain editable.
All required fields are providedPrefills and disables all fields when they're valid, unless you include them in consumerDataCollectionConfig.editableFields.
All required fields are provided and skipConsumerDataCollection is trueCreates 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.

Returning shoppers

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.

Transaction intents

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

IntentDescription
AuthorisationAuthorise funds for later capture.
PurchaseComplete the payment immediately.
EstimatedAuthorisationSubmit an authorisation for an estimated amount.
PayoutSend 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.

Post-transaction operations

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:

  1. In the Unity Portal, go to Report & Search > Report.
  2. Find the transaction using the merchantTransactionId or systemTransactionId from onPostAuthorisation.
  3. 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.

What's next?

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.