Aerosync Integration Guides

This guide walks through connecting a user's bank account with Aerosync, then linking that connection to Aeropay. The flow has three steps: get a token, load the Aerosync widget, and connect the resulting bank account to Aeropay.

1. Get an Aerosync token

Make a request to Aeropay's GET /v2/aggregatorCredentials endpoint. You'll need to input aerosync as the value for the aggregator query parameter.

Sample request to GET /v2/aggregatorCredentials:

curl --request GET \
     --url 'https://api.sandbox-pay.aero.inc/v2/aggregatorCredentials?aggregator=aerosync' \
     --header 'Content-Type: application/json' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {{token}}'

Response:

{
    "fastlinkURL": "https://sandbox.aerosync.com/",
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJkNDYzZjhhYwefNmEyLTQzOTctOWIyNC00NWYzZGY2MDcxYjciLCJleHAiOjE2ODY0Mzk4NTYsInVzZXJJZCI6ImU3OTQzMmNiOWFmNTQ2ZTRiMDBiN2NmMDU3ZjdlZWEyIiwidXNlclBhc3N3b3JkIjoiODYxNDg3OGExMzEyNDA2Njg5MDBlN2VkMGNhNDhkNTkiLCJDbGllbnRJZCI6InRlc3QxIiwiQ2xpZW50TmFtZSI6ImNsaWVudDEifQ.XufkfsgGc7CGDy8DZRTOc0e_-kJYt9puyCAqneX4Ze0",
    "username": "e79432cb9af546e4b00b7cf057fasea2"
}

Keep note of the token from the response. You'll need it for the next step.

🚧
Use the token to initialize the widget in the next step. Don't use fastlinkURL to build your own iframe.
The response from GET /v2/aggregatorCredentials includes a fastlinkURL field. This should not be used to manually construct your own iframe or redirect URL for bank linking.
Building your own iframe around fastlinkURL skips the SDK's built-in handling of widget events (success, close, error) and connectionId retrieval, and it isn't guaranteed to behave the same way in sandbox vs. production.
Always use one of the official SDKs listed in Step 2 below to load the Aerosync widget.

2. Load the Aerosync widget

Follow one of the guides to initialize and launch the Aerosync widget. These guides also explain how to interact with the widget and its postMessage events:

3. Connect bank account to Aeropay

Now that a user has connected their bank account with Aerosync, the next step is to link that bank account to Aeropay. You'll need to make a request to Aeropay's POST /v2/linkAccountFromAggregator endpoint.

Sample request to POST /v2/linkAccountFromAggregator:

curl --request POST \
     --url https://api.sandbox-pay.aero.inc/v2/linkAccountFromAggregator \
     --header 'Content-Type: application/json' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {{token}}' \
     --data '
{
  "connectionId": "a2c7f83f-4df9-4090-b3bd-ad6fc3003c90", // this is the connectionId returned from the Aerosync widget success
  "aggregator": "aerosync"
}
'

Response:

{
    "userBankInfo": {
    "bankAccountId": 4351,
    "bankName": "Aerosync Bank (oAuth)",
    "accountLast4": "0191",
    "name": "Aerosync Savings",
    "externalBankAccountId": "None",
    "isSelected": true,
    "accountType": "savings",
    "status": "verified",
    "createdDate": "2025-08-04T21:26:53+00:00",
    "accountHolderInfo": [
      {
        "name": {
          "fullName": "Dwight Schrute"
        }
      }
    ],
    "canFetchBalance": true,
    "balance": 312425
  }
}

1. Get an Aerosync token

Use the token to initialize the widget in the next step. Don't use fastlinkURL to build your own iframe.

2. Load the Aerosync widget

3. Connect bank account to Aeropay

Use the `token` to initialize the widget in the next step. Don't use `fastlinkURL` to build your own iframe.