# 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:

| 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. |


## 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 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.

## 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:

| 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.

## 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](/guides/checkout/components/web/aeropay/onboarding):** Configure Aeropay in the Unity Portal.
* **[Implementation](/guides/checkout/components/web/aeropay/implementation):** Integrate and mount the Aeropay button.
* **[Configuration](/guides/checkout/components/web/aeropay/configuration):** Customise the component's appearance and behaviour.
* **[Events](/guides/checkout/components/web/aeropay/events):** Handle component callbacks and transaction results.