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

Note that if the user you are creating already has an account with Aeropay, their existing account information will be returned.

Step 1 - Generate a Merchant Token

The POST /v2/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.

HTTP request

Sandbox - POST https://api.sandbox-pay.aero.inc/v2/token

Production - POST https://api.aeropay.com/v2/token

Request parameters

Parameter	Required?	Type	Description
apiKey	Yes	String	API Key or user email
apiSecret	Yes	String	API Secret or user password
scope	Yes	String	Type of token requested
id	Only for merchant & userForMerchant scope	String	Merchant Id
userId	Only for userForMerchant scope	String	Id of user

HTTP status and error codes

HTTP status	Error Code	Meaning	Resolution	Message
400	AP002	API credentials are invalid	Confirm correct api key, api secret, and environment	Invalid API key or secret key
400	AP700	Scope is invalid	User either merchant or userForMerchant scope	Invalid scope
400	AP700	Scope is not provided	User either merchant or userForMerchant scope	Missing required Parameter: 'scope'
400	AP700	Missing apiSecret	Make sure to define a valid string for apiSecret	Missing required Parameter: 'apiSecret'
400	AP700	Missing apiKey	Make sure to define a valid string for apiKey	Missing required Parameter: 'apiKey'
400	AP700	Missing userId	Make sure to define a valid userId (for userForMerchant token)	Missing required Parameter: 'userId'

Code Example - Request

curl --request POST \
     --url https://api.sandbox-pay.aero.inc/v2/token \
     --header 'Content-Type: application/json' \
     --header 'accept: application/json' \
     --data '
{
    "apiKey" : "key",
    "apiSecret" : "secret",
    "scope" : "merchant",
    "id" : 1057
}
'

Code Example - Response

{
    "TTL": 1800,
    "token": "eyJ0eXAiOiJKN7YiLCJhbGciOiJIUzI1NiJ9.eyJhdXRoIjoiNDgiLCJzdWIiOiJtZXJjaGFudCIsImp0aSI6ImZhNGY2NzRmLTJkOTEtNGExNS05OTk3LTc1NWI2ZTYyZDhkYiIsImV4cCI6MTY5NDAzNTc2MSwidXNlcm5hbWUiOiJ1cy1lYXN0LTE6M2NlMjBiZDUtNzg03ZCRMjY5LWExM2UtZmM1MzIyMTk0NTAxIn0.3B1sdyVNpTW644RtpoGmQnRlp9PKGjrk91YUi0Uq2Os"
}

Step 2 - Create the User

HTTP request

Sandbox - POST https://api.sandbox-pay.aero.inc/v2/user Production - POST https://api.aeropay.com/v2/user

Request parameters

Parameter	Required?	Type	Description
firstName	Yes	String	The User's first name as shown on their government ID Min xx characters Max xx characters
lastName	Yes	String	The User's last name as shown on their government ID Min xx characters Max xx characters
phoneNumber	Yes	String	The User's phone number Must be in international format (+11234567890) Landline, VOIP, or prepaid phone numbers are invalid in production.
email	Yes	String	The User's email address Must be a valid email address

Code Example - Request

curl --request POST \
     --url https://api.sandbox-pay.aero.inc/v2/user \
     --header 'Content-Type: application/json' \
     --header 'authorization: Bearer {{merchant-scope token}}' \
     --data '
{
  "firstName": "Jane",
  "lastName": "Doe",
  "phoneNumber": "+11234567890",
  "email": "[email protected]"
}

Code Example - Response

Aeropay will respond with the full user object if the user is new to Aeropay.

{
    "user": {
        "id": "49681f36-bbe0-4038-b024-a5d86584255a",
        "firstName": "Jane",
        "lastName": "Doe",
        "type": "consumer",
        "email": "[email protected]",
        "phoneNumber": "+11234567890",
        "createdDate": "2025-06-24T20:24:21+00:00"
    },
    "mfaType": "sms"
}

When creating a user, a user.id is returned. This user.id is the only variable required for referencing the user within the Aeropay system.

If the user already exists in the Aeropay network, this will kick off our network user flow

🚧
mfaType
Possible values are 'sms', 'email', or null, determined by merchant settings.

Error codes

HTTP status	Error Code	Meaning	Resolution	Message
200	N/A	Missing phoneNumber parameter	Provide parameter 'phoneNumber'	Phone number required to create an AeroPay user
200	N/A	Phone number is being used by a current Aeropay user	Have user provide PIN in email and pass to our /confirmUser endpoint	You've previously used AeroPay to pay another business using this phone number. Please verify your identity by entering the pin sent to your email

After a user is created, the user must connect their bank account. For the guide on bank account connection, please see our bank linking guide.