Understanding Token Scopes

The Two Token Scopes

Aeropay uses two different token scopes:

1. merchant scope

Use this scope when your merchant organization needs to perform administrative actions.

Required credentials:

• api_key (your merchant API key)
• api_secret (your merchant API secret)
• scope: "merchant"
• id(your merchant ID)

Common use cases:

• Creating new users via POST /user
• Creating a payment link via POST /paymentLink
• Managing and viewing transaction details via POST /transactionSearch
• Capturing preauthorized transactions via POST /capturePreauthTransaction
• Voiding or refunding transactions via GET /reverseTransaction

2. userForMerchant scope

Use this scope when your merchant needs to act on behalf of users.

Required credentials:

• api_key (your merchant API key)
• api_secret (your merchant API secret)
• scope: "userForMerchant"
• id (your merchant ID)
• userId (the specific user's ID you're acting on behalf of)

Common use cases:

• Getting bank linking credentials via GET /aggregatorCredentials
• Creating transactions on behalf of users via POST /transaction, POST /preauthTransaction
• Fetching user bank accounts via GET /user

Requesting a Token

Both scopes use the same POST /token endpoint. Simply specify the scope and provide the appropriate credentials:

Example - Merchant scope token:

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

Example - userForMerchant scope token:

curl --request POST \
  --url https://api.sandbox-pay.aero.inc/token \
  --header 'Content-Type: application/json' \
  --header 'accept: application/json' \
  --data '{
    "scope": "userForMerchant",
    "api_key": "your-api-key",
    "api_secret": "your-api-secret",
    "id": "your-merchant-id",
    "userId": "the-users-id"
  }'

Important Notes

• All tokens expire after 30 minutes. You'll need to request a new token when yours expires.
• Refer to the API reference for each endpoint to see which scope is required.