Network User

Aeropay network users are users that exist within the Aeropay network that are new to your platform. If a user exists in the Aeropay network, the API response from POST /user will contain "existingUser" and send an OTP to the user's email.

👍

Note: A Network User only needs to complete the OTP code flow once, after this point, the user becomes a Returning user

Step 1 - Generate the Merchant 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.

HTTP request

Sandbox - POST https://staging-api.aeropay.com/token
Production - POST https://api.aeropay.com/token

Request parameters

HTTP status and error codes

Code Example - Request

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"
}
'

Code Example - Response

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

Step 2 - Create the User

HTTP request

Sandbox - POST https://staging-api.aeropay.com/user
Production - POST https://api.aeropay.com/user

Request parameters

Code Example - Request

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

Code Example - Response

{
  "success": true,
  "error": null,
  "existingUser": {
    "userId": "123456",
    "phone": "+11234567890",
    "email": "[email protected]"
  },
  "displayMessage": "You've previously used AeroPay to pay another business. Please verify your identity by entering the pin sent to your email ja****[email protected]"
}

👀

Look for "existingUser" parameter

If the user already exists in Aeropay, but has never transacted at your merchant, POST /user will respond with the following message including "existingUser".

Step 3 - Confirm User Identity

In the case the user you've created already exists in the Aeropay ecosystem, you will relieve an error from POST /user that the user you created has previously used Aeropay. Aeropay will send an MFA code to the user's email registered with their pre-existing Aeropay account. This MFA code has a TTL of 15 minutes.

You will have to verify the user's identity with POST /confirmUser. The POST /confirmUser API can be used to verify the user's identity by requiring the user to enter an MFA code sent to the email on file with Aeropay. Note: Aeropay handles sending of these MFA codes.

📘

Use our test endpoint to "unverify" any test users you've created to test this existing user flow in sandbox.

HTTP request

Sandbox - POST https://staging-api.aeropay.com/confirmUser
Production - POST https://api.aeropay.com/confirmUser

Request parameters

Code Example - Request

curl --request POST \
     --url https://staging-api.aeropay.com/confirmUser \
     --header 'Content-Type: application/json' \
     --header 'accept: application/json' \
     --header 'authorizationToken: Bearer {{token}}' \
     --data '
{
  "userId": "123123", // userId of user
  "code": "234153", // MFA code provided by user via email
}

Code Example - Response

{
    "success": true,
  	"error": null
}

🌟

Store the Aeropay userId in your database

Only once the user has been verified successfully should you save the Aeropay userId in your database. The next time this user comes to make a transaction, follow the Returning User guide.

Step 4 - Retrieve the User Details

Aeropay recommends saving the userId and demographic information in your own database, but the user's actively-linked bank accounts must be fetched before making a transaction. The GET /user API can be used to fetch all relevant user information by searching on the user's Aeropay userid.

HTTP request

Sandbox - GET https://staging-api.aeropay.com/user
Production - GET https://api.aeropay.com/user

Request parameters

Code Example - Request

curl --request GET \
     --url https://staging-api.aeropay.com/user \
     --header 'Content-Type: application/json' \
     --header 'accept: application/json' \
     --header 'authorizationToken: Bearer {{user or userForMerchant token}}'

Code Example - Response

{
    "success": 1,
    "user": {
        "userId": "1234",
        "firstName": "John",
        "lastName": "Doe",
        "type": "consumer",
        "email": "[email protected]",
        "phone": "+13144949063",
        "createdDate": "1605113011",
        "bankAccounts": [
            {
                "bankAccountId": "123456",
                "userId": "1234",
                "bankName": "Chase Bank",
                "accountLast4": "1222",
                "name": "Checking - 1222",
                "externalBankAccountId": "",
                "isSelected": "1",
                "accountType": "checking",
                "status": "verified",
                "createdDate": "1692715066"
            }
        ],
      	"createdDate": "1716312178",
        "aeroPassUserUuid": "0f2542a4-8e60-4a72-b3a1-064f2d6943e8",
        "userStatus": "Active"
    }
}