Guides

API Quick Start

Suggest Edits

Basic API Flow

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

Authenticate Merchant & Fetch Token

The POST /token endpoint is used to authenticate API integrators for every Aeropay endpoint. The token scope determines who is acting on the system: merchant, user, or userForMerchant (white labeled user). The scope will determine what endpoints are available.

All tokens have a time to live (TTL) of 30 minutes.

POST /token

curl --request POST \
     --url https://staging-api.aeropay.com/token \
     --header 'Content-Type: application/json' \
     --header 'accept: application/json' \
     --data '
{
  "scope": "merchant",
  "api_key": "api-key-ab1341-asdflk3",
  "api_secret": "api-secret-ab1341-asdflk3",
  "id": "1456"
}
'

Create User

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 /user endpoint. The authorizationToken used to create a user must be a merchant-scoped token.

The userId returned from this call is required to reference the user within the Aeropay system. If a user already has an account with Aeropay, their existing account information will be returned.

POST /user

curl --request POST \
     --url https://staging-api.aeropay.com/user \
     --header 'Content-Type: application/json' \
     --header 'accept: application/json' \
     --header 'authorizationToken: Bearer {{token}}' \
     --data '
{
  "first_name": "Jane",
  "last_name": "Doe",
  "phone_number": "+11234567890",
  "email": "[email protected]"
}
'

Link User Bank Account

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

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

The GET /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, the GET /linkAccountFromAggregator endpoint will connect the user's bank to their Aeropay account.

Understand how to launch our aggregator widget.

GET /aggregatorCredentials

curl --request GET \
     --url 'https://staging-api.aeropay.com/aggregatorCredentials?aggregator=aerosync' \
     --header 'Content-Type: application/json' \
     --header 'accept: application/json' \
     --header 'authorizationToken: Bearer {{token}}'

POST /linkAccountFromAggregator

curl --request POST \
     --url https://staging-api.aeropay.com/linkAccountFromAggregator \
     --header 'Content-Type: application/json' \
     --header 'accept: application/json' \
     --header 'authorizationToken: Bearer {{token}}' \
     --data '
{
  "externalBankAccountId": "externalBankAccountId",
  "user_id": "1234",
  "user_password": "password",
  "accountId": "accountId",
  "providerAccountId": "providerAccountId",
  "token": "token"
}
'

Make a Payment

Once a user has a linked bank, they can begin to make transactions.

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

Option 1: Regular Transaction

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

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

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

POST /transaction

curl --request POST \
     --url https://staging-api.aeropay.com/transaction \
     --header 'Content-Type: application/json' \
     --header 'accept: application/json' \
     --header 'X-AP-Version: 2023-06-05' \
     --header 'authorizationToken: Bearer {{token}}' \
     --data '
{
  "attributes": {
    "tip": {
      "selection": {
        "tipAmount": "1.00",
        "label": "$1.00"
      }
    }
  },
  "amount": "10.00",
  "merchantId": "12345",
  "uuid": "transaction-UUID"
}
'

Option 2: Preauthorized Transaction

Preauthorized transactions do not initiate the movement of any funds, but instead store the details of a transaction that must be captured later by an employee.

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

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

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

POST /preauthTransaction

curl --request POST \
     --url https://staging-api.aeropay.com/preauthTransaction \
     --header 'Content-Type: application/json' \
     --header 'accept: application/json' \
     --header 'authorizationToken: Bearer {{token}}' \
     --data '
{
  "merchantId": "1235",
  "bankAccountId": "1234567",
  "amount": "10.00"
}
'

Option 3: 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 /user endpoint to fetch User's actively linked bank accounts. The bankAccountId returned from this endpoint can be used to call thePOST /payoutTransaction endpoint and initiate a payout transaction.

POST /payoutTransaction

curl --request POST \
     --url https://staging-api.aeropay.com/payoutTransaction \
     --header 'Content-Type: application/json' \
     --header 'accept: application/json' \
     --header 'X-AP-Version: 2023-06-05' \
     --header 'authorizationToken: Bearer {{token}}' \
     --data '
{
  "userId": "4567",
  "amount": "10.00",
  "bankAccountId": "27381938"
}
'

Updated about 1 month ago