Testing

Testing Network User MFA Scenario

To test the /confirmUser endpoint (MFA OTP challenge):

1. Create a test user via POST /user
2. Link a bank account using Aerosync
3. Delete the user from your backend database
4. Call POST /user again with the same user details
   1. Aeropay will recognize this user exists in the network
   2. You'll receive an mfaType in the response
   3. An OTP will be sent to the user
5. Call POST /confirmUser with the OTP code to verify the user at your merchant
6. Call GET /bankAccounts to fetch the user's existing bank accounts

The user will now have access to their previously linked bank account without needing to reconnect it.

📘

Important Notes:

• Each time you call POST /user for testing, you must call /confirmUser to complete verification
• Once verified via /confirmUser, the user becomes a returning user at your merchant
• For subsequent sessions, skip POST /user and POST /confirmUser - simply generate a userForMerchant token and call GET /bankAccounts

Code Example - Request

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

Code Example - Response

{
    "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" // if sms or email, MFA code was sent to user to be verified. If null, skip to Step 4
}

Phone Number Error Scenarios

Use the following phone numbers in the phoneNumber field of POST /user to trigger specific phone validation errors in sandbox and staging.

User/Email Error Scenarios

Use the following emails in the email field of POST /user to trigger specific user errors.

Transaction Decline Scenarios

You may use the following key words when creating transactions in our sandbox environment to simulate a declined transaction. To run an Exception Scenario transaction, run a regular POST /v2/transaction with an extra ‘exceptionScenario’ value in the body. The transaction will produce the desired output exactly as it would happen if the transaction hit that error through its regular execution.

When you trigger a decline scenario, users will automatically become suspended until the payment is resolved. You can resolve test payments in the sandbox environment from your Aeropay merchant portal.

Example request

{
    "amount": {
        "currency": "USD",
        "value": 5
    },
    "merchantId" : "931",
    "exceptionScenario": "returnInsufficient"
}

Example response

Note: In these scenarios, the POST /v2/transaction call will succeed, but the transaction will shortly after be declined with a returnCode corresponding to the exceptionScenario.

{
    "transaction": {
        "id": "6aaf8e38-2ace-4f33-a90b-4fa94ec2df11",
        "message": "The scenario transaction is being created and declined. Please wait a few seconds to see it reflected in the merchant portal.",
        "scenarioReturnCode": "R02",
        "amount": {
            "amount": 5,
            "currency": "USD"
        },
        "status": "pending",
        "paymentType": "payment",
        "userId": "558ca193-fce8-494b-8aad-b34c5641ab0a",
        "referenceId": "Testing V2",
        "isRtp": false,
        "merchantId": 1522,
        "title": "Online Transaction",
        "locationId": 2887,
        "userAccountId": 952432
    }
}

Transaction Rejection Scenarios

You may use the following key words when creating transactions in our sandbox environment to simulate a rejected transaction. To run an Exception Scenario transaction, run a regular POST /v2/transaction with an extra ‘exceptionScenario’ value in the body. The transaction will produce the desired output exactly as it would happen if the transaction hit that error through its regular execution.

Example request

{
    "amount": {
        "currency": "USD",
        "value": "5.0"
    },
    "merchantId" : "931",
    "exceptionScenario": "delinquent"
}

Example response

{
    "success": false,
    "code": "AP109",
    "error": "We've detected delinquent activity on your account. Reach out to [email protected] to reactivate your account."
}