Aeropay

This page provides an overview of the payments methods provided by the Aeropay adapter in the IXOPAY platform. It also includes a full list of all configuration options available to you when integrating Aeropay within your payments landscape, as well as an overview of the parameters required when submitting a transaction via IXOPAY's API.

Payment Methods

Payment Method	Transaction Flows	Transaction Types
ACH Direct Debit	Full-Page Redirect, payment.js	Register, Debit, Preauthorize, Capture, Payout, Refund, Void

Integration Guide

Aeropay uses the AeroSync widget to let users link their bank account. The flow has four steps: register the user once, prepare the widget for each checkout, let the user link their bank, then submit the transaction.

Step 1: Register the user

Call the register transaction once per customer. The following customer fields are required:

Field	Description
customer.firstName	Customer's first name
customer.lastName	Customer's last name
customer.billingPhone	Customer's phone number
customer.email	Customer's email address

After the register call, Aeropay sends the customer a one-time SMS code to verify their phone number. The gateway will return a redirectUrl pointing to an MFA page (multi-factor authentication) where the customer enters this code to complete the verification.

On success, the register transaction UUID is the customer's Aeropay user identifier. Pass it as referenceUuid on all subsequent transactions for that customer.

Step 2: Prepare the transaction

Call prepareDebit (or preparePreauthorize) to obtain the widget token.

{
    "merchantTransactionId": "order-12345",
    "amount": "9.99",
    "currency": "USD",
    "referenceUuid": "a1b2c3d4e5f6a1b2c3d4"
}

The response includes:

Field	Description
widgetToken	JWT used to initialize the AeroSync widget
extraData.userId	Aeropay user identifier
extraData.bankAccounts	Array of previously linked bank accounts (present only when at least one exists). Each entry contains bankAccountId, bank name, and masked account details. Example:

{
    "bankAccounts": [
        {
            "bankAccountId": 1234567,
            "bankName": "Example Bank",
            "accountLast4": "1234",
            "name": "Checking Account",
            "isSelected": true,
            "accountType": "checking",
            "status": "verified",
            "createdDate": "2026-01-01T00:00:00+00:00",
            "connectionId": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
        }
    ]
}

If bankAccounts is non-empty, present the existing accounts to the user. If the user selects one, skip the widget entirely and pass the chosen bankAccountId directly in the debit call via extraData.bankAccountId. If the user wants to link a new account instead, proceed to Step 3 as normal.

Step 3: Load the widget

​1. Embed payment.js in your page:

<script data-main="payment-js" src="https://gateway.ixopay.com/js/integrated/payment.1.3.min.js"></script>

note

The data-main="payment-js" attribute is required.

​2. Add a container element for the widget:

<div id="aeropayWidget"></div>

​3. Initialize with the widgetToken from the prepare response:

<script>
    var payment = new PaymentJs('1.3');

    var completeHandler = function (connectionId, event) {
        // connectionId identifies the linked bank account
        // Send it to the Transaction API via extraData.connectionId
    };

    var errorHandler = function (error) {
        // Handle widget or SDK errors
    };

    var closeHandler = function () {
        // Called when the user closes the widget without completing
    };

    payment.initAeropay(
        'public-integration-key',  // connector token
        'aeropayWidget',           // container element ID
        widgetToken,               // from prepareDebit/preparePreauthorize response
        completeHandler,
        errorHandler,
        closeHandler
    );
</script>

Step 4: Submit the transaction

Pass the connectionId from completeHandler to the Transaction API:

{
    "extraData": {
        "connectionId": "<connectionId>"
    }
}

If the user has already linked a bank account (from extraData.bankAccounts), you can skip the widget and pass the bankAccountId directly instead:

{
    "extraData": {
        "bankAccountId": "<bankAccountId>"
    }
}

Options

The optional parameters that initAeropay accepts:

Key	Type	Description
iframeTitle	string	Accessible title for the widget iframe. Defaults to Connect Bank
configurationId	string	AeroSync configuration ID for widget customization
width	string	Widget iframe width in pixels (e.g. 375px)
height	string	Widget iframe height in pixels (e.g. 688px)
deeplink	string	Mobile deep link URL to resume the flow after OAuth authentication. Required for native mobile apps
zIndex	string	CSS z-index override for the widget iframe. Defaults to 1
manualLinkOnly	boolean	Restrict the widget to manual bank linking only
handleOAuthManually	boolean	Prevent the widget from automatically launching the OAuth window. Use with onEvent to handle the OAuth URL manually (e.g. in native mobile browsers)
style	object	Style overrides passed to the AeroSync widget (bgColor, opacity, width, height)
onLoad	function	Called when the widget is fully loaded
onEvent	function	Called on widget lifecycle events. Receives { type, payload: { pageTitle, onLoadApi } }. Useful for intercepting OAuth redirects on mobile

<script>
    var aeropayOptions = {
        iframeTitle: 'Connect your bank',
        configurationId: 'your-config-id',
        width: '375px',
        height: '688px',
        onLoad: function () {
            console.log('Widget ready');
        },
        onEvent: function (event) {
            // Intercept OAuth redirect in native mobile apps
            if (event.payload.pageTitle === 'launchExternalWindow') {
                openInAppBrowser(event.payload.onLoadApi);
            }
        },
    };

    payment.initAeropay(
        'public-integration-key',
        'aeropayWidget',
        widgetToken,
        completeHandler,
        errorHandler,
        closeHandler,
        aeropayOptions
    );
</script>

Transaction API Additional Parameters

When calling debit or preauthorize, the following extraData keys are supported:

Key	Description
connectionId	The connection ID returned by the widget completeHandler. Pass this when the user linked a new bank account via the widget
bankAccountId	ID of a previously linked bank account from prepareDebit / preparePreauthorize response extraData.bankAccounts. Pass this to skip the widget for returning users

note

Exactly one of connectionId or bankAccountId must be provided. If connectionId is passed, Aeropay will link the bank account and return a bankAccountId that can be reused on subsequent transactions.

Payout

Payouts are supported as a standard payout transaction. The following extraData keys are supported:

Key	Type	Description
bankAccountId	string	ID of the destination bank account to pay out to
rtp	boolean	When true, sends the payout via Real-Time Payments (RTP) for near-instant settlement instead of standard ACH

{
    "extraData": {
        "bankAccountId": "<bankAccountId>",
        "rtp": true
    }
}

note

A successful payout response does not guarantee final settlement. Aeropay may reverse an approved payout after the fact (e.g. due to a compliance hold), which will update the transaction status to error via a webhook notification. Monitor for asynchronous status changes on payout transactions.