API Quick Start

Basic API Flow

The following flow visualizes a basic new user flow through user creation, bank connections, and transaction creation.

User Creation

Aeropay users are individuals, uniquely identified by a phone number, who can link bank accounts and make transactions. If you are opting for white-labeled user creation in your application, you'll need to create a user before initiating a preauthorized transaction.

An Aeropay account can be created on behalf of a user using the POST /v2/user endpoint. The authorization token used to create a user must be a merchant-scoped token.

The user.id returned from this call is required to reference the user within the Aeropay system.

The response also includes mfaType. If mfaType is sms or email, Aeropay has sent the user a one-time code, and the user is not connected to your merchant until you verify that code with POST /v2/confirmUser. If mfaType is null, no code was sent and no confirmation is needed. See New & Network Users for the full flow.

Bank Linking

Once a user has been created, they can go through the flow to link their bank account.

The authorization token used to act on behalf of a user must be a userForMerchant-scoped token.

The GET /v2/aggregatorCredentials endpoint will return the necessary URL to launch the aggregator widget. Launching the aggregator widget will allow the User to securely link their bank account through their bank’s website. After the aggregator widget is closed, call POST /v2/linkAccountFromAggregator with the connectionId returned by the widget to connect the user's bank to their Aeropay account.

Understand how to launch our aggregator widget.

Transaction

Once a user has a linked bank, they can begin to make transactions. See below some details on each transaction type, or skip right to the transaction guides: Standard Transaction Guide, Payout Transaction Guide, Preauth Transaction Guide, Subscription Transaction Guide

amount.amount is an integer in cents (for example, 1234 = $12.34). Decimal values are rejected. currency currently supports USD only.

Option 1: Standard Transaction

To create a standard transaction, use the GET /v2/bankAccounts endpoint to fetch user's linked bank accounts. The bankAccountId returned from this endpoint can be used to call thePOST /v2/transaction endpoint to specify the bank account used in the transaction.

Tipping and invoicing information can be added to transactions in the attributes of the POST /v2/transaction body.

Before creating the transaction, you must request a new userForMerchant-scoped token if your token has expired.

curl --request POST \
     --url https://api.sandbox-pay.aero.inc/v2/transaction \
     --header 'Content-Type: application/json' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {{token}}' \
     --header 'Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000' \
     --data '
{                
    "bankAccountId": {{bankAccountTransactionId}},
    "merchantId": {{merchantId}},
    "amount": {
      "amount" : 1234,
      "currency": "USD"
    },
    "referenceId": "Testing V2"
}
'

Option 2: Payout Transaction

Payout transactions are payments that flow from merchant to User. These types of transactions may be used for withdrawals or rewards.

To create a payout transactions, use the GET /v2/bankAccounts endpoint to fetch User's actively linked bank accounts. The bankAccountId returned from this endpoint can be used to call thePOST /v2/payoutTransaction endpoint and initiate a payout transaction.

curl --request POST \
     --url https://api.sandbox-pay.aero.inc/v2/payoutTransaction \
     --header 'Content-Type: application/json' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {{merchant token}}' \
     --header 'Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000' \
     --data '
{
  "userId": "bc81e829-d35b-43cb-acb9-d218674878be",
  "bankAccountId": 27381938,
  "amount": {
      "currency": "USD",
      "amount": 10
  },
  "merchantId" : 12345,
  "rtp": true,
  "referenceId": "newReferenceID-TestingEA"
}
'

Option 3: Preauthorized Transaction

Preauthorized transactions do not initiate the movement of any funds, but instead store the details of a transaction that is captured later, once the order is fulfilled. Capture is typically done by an employee in the Aeropay Merchant Portal, or by your POS or ordering platform calling POST /v2/capturePreauthTransaction when the order is completed.

To create a preauthorized transactions, use the GET /v2/bankAccounts endpoint to fetch User's actively linked bank accounts. The bankAccountId returned from this endpoint can be used to call thePOST /v2/preauthTransaction endpoint and create a preauthorized transaction.

Tipping and invoicing information can be added to transactions in the attributes of the POST /v2/preauthTransaction body.

See Manage Transactions for more detail on capturing or updating preauthorized transactions.

curl --location --globoff 'https://api.sandbox-pay.aero.inc/v2/preauthTransaction' \
--header 'Content-Type: application/json' \
--header 'authorization: Bearer {{userForMerchantScope token}}' \
--header 'Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000' \
--data '{
    "bankAccountId": {{bankAccountTransactionId}},
    "merchantId": {{mainMerchantId}},
    "amount": {
        "currency": "USD",
        "amount": 222
    },
    "description": "DESCRIPTION",
    "attributes": {
        "key": {
            "value": "KEY VALUE",
            "description": "KEY DESCRIPTION"
        }
    },
    "referenceId": "Testing V2"
}'