2025-11-14 Release Notes - V2 API

Aeropay v2 APIs

Aeropay has released a new major version of our API documentation: v2. This update is Aeropay's first major version update of all API endpoints. The v2 API endpoints are more efficient, standardized, and secure.

Notable changes from v1 to v2

RESTful API URIs

Aeropay has updated the API URIs to more RESTful.

Standardized Error Messages

All error messages follow the same standard format, below.

// example error message 1
{
    "error": {
        "help": "contact [email protected] for help",
        "code": "AP113",
        "message": "User does not exist"
    }
}

// example error message 2
{
    "error": {
        "code": "AP701",
        "message": "Improperly formatted parameter: ['id']"
    }
}

Transaction Identifiers

In the Aeropay v1 (old) API, transaction UUID values were merchant identifiers and unique transaction identifiers.

In v2 API, transaction UUIDs are still unique, idempotent values for transactions. But the referenceId field, a new parameter, is used as a merchant identifier of a transaction.

curl --location 'baseURL/v2/transaction' \
--header 'Content-Type: application/json' \
--header 'authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhdXRoIjoiMSIsInN1YiI6InVzZXJmb3JtZXJjaGFudCIsImp0aSI6IjQ4NDAxNDA1LWM1YWUtNGJjNS04MTI1LTBlYWYwMTkwNGUyNSIsImV4cCI6MTc2MTE3MDcyNiwidXNlcm5hbWUiOiJkNWUxN2NiZi05MmFkLTQ0ZTctYjQ4My0xOWRiYTdhZGFhYTQiLCJtZXRhZGF0YSI6eyJtZXJjaGFudF9pZCI6MTA1N319.5awUg674NNgui81jylKPBMYmUpwOLidGpINPXv5SaQA' \
--data '{                
    "bankAccountId": 1717,
    "merchantId": 1057,
    "amount": {
        "amount": 1200, // amount in pennies
        "currency": "USD"
    },
    "referenceId": "eae2e262-7931-44d9-af42-8531e242b465"
}'

User Identifiers

In the Aeropay v2 API userId values will all follow standard UUID format. In v1 API, userIds were integers.

User MFA Flow

In the Aeropay v2 API, Aeropay added support for SMS 2FA on both new and network users. By default, SMS 2FA will be sent for all new and existing network users when POST /v2/user is called.

mfaType

The new mfaType parameter can have a value of 'sms', 'email', or null, and can be used to determine both if an MFA code as been sent and by what protocol.

When migrating from v1 to v2 endpoints, your current logic to look for 'existingUser' can be replaced with looking for a non-null mfaType.

bankAccounts

The response structure for POST /v2/user has also been updated to remove the bankAccounts array. A user's linked bankAccounts are now fetched from a new endpoint GET /v2/bankAccounts.

When migrating from v1 to v2 endpoints, you will now rely on the new bankAccounts endpoint to fetch and display a user's linked banks.

Idempotency-Key Header Support

V2 introduces support for the Idempotency-Key header on POST /v2/reverseTransaction. When included, Aeropay stores the response for that key and returns the same outcome on any retry, preventing duplicate refunds on network errors or timeouts. The same key cannot be used with a different request body. Idempotency is optional; if no key is sent, duplicate protection is not applied.

Aerosync SDK Upgrade

Aeropay v2 APIs require most up to date Aerosync SDK versions (Web NPM v2.0+, React Native v4.0+, etc). If you are migrating from v1 to v2 APIs, you must also migrate to the latest Aerosync SDK versions.

🚧

Failure to configure the Aerosync SDK per the V2 guide may result in incorrect onSuccess callback data that does not match the expected V2 format.

When migrating to V2, ensure your widget configuration includes:

• token from GET /v2/aggregatorCredentials
• aeroPassUserUuid from POST /v2/user response
• configurationId (replaces consumerId from earlier versions)

Missing these parameters will cause unexpected callback structure.

This applies to all Aerosync SDKs: Web NPM, React Native, Android, iOS, and Flutter. See the V2 Integration Guide for complete configuration details.

Additional Changes from v1 to v2

• Authentication header — header key renamed from authorizationToken to authorization
• Amount format — amount is no longer a string in dollars; v2 expects an object with value in pennies and a currency code
• /reverseTransaction — changed from a GET to a POST
• /linkAccountFromAggregator — no longer accepts user_id and user_password; v2 expects connectionId from the Aerosync SDK (v2.0+ only)