Log inGet started
Airwallex logo
Core API
Transactional FX
Back to home
Get started
QuickstartManage API keys
Partner connections
OverviewGet startedImplement your authorization flow
Sample integrationsNotifications and workflow automation

Implement your authorization flow

Use this step-by-step guide to implement your authorization flow.

Step 1: Allow Airwallex customers to authorize your application

On your user interface, implement a “Connect to Airwallex” button that your users can click on to connect their Airwallex account to your application. This button should open our OAuth authorization flow URL:

Connect to Airwallex

You must enumerate all the scopes in YOUR_SCOPES that you intend to access through the integration in the authorization flow. The authorization flow is required when users connect to your application for the first time. It is also required when your application needs to access additional scopes.

Customers will be taken to login to their Airwallex account, select which account they want to connect to your application, and review the relevant permissions that you are requesting.

Airwallex login

Choose an account

OAuth page

If they give consent for your application to access their Airwallex account, Airwallex will redirect users back to YOUR_REDIRECT_URI with an authorization code. Otherwise, Airwallex will redirect back to YOUR_REDIRECT_URI with an error.


Redirect URIs must be whitelisted for security purposes; if you intend to add a new redirect URI, contact your Airwallex partnerships manager to do so. Attempting to use a non-whitelisted redirect URI will result in an error.

Step 2: Obtain refresh and access tokens

Once the authorization code is successfully obtained, your application should exchange the authorization code back to Airwallex OAuth server for a refresh and access token.

Note that YOUR_REDIRECT_URI must match the one that was used to obtain the AUTH_CODE in the previous step.

If the AUTH_CODE is valid, you will receive a refresh and access token. The refresh token is long-lived (valid for 60 days), and you should store this securely in a database for refreshing your access token later. The access token is short-lived (valid for 5 minutes) and should be used in each session where you call the Airwallex API on behalf of authorized accounts.

To use the access token, pass the access token value in the Authorization header of requests each time your application calls an API. The value should always be: Authorization: Bearer {AccessToken}. For example, you can now call the GET /api/v1/account/ endpoint to obtain details about the account that was just connected.

Step 3: Refresh access tokens

As the access token is short-lived, you will need to obtain new access tokens to continue accessing the Airwallex API across sessions. To do so, use the latest refresh token value from your previous call to /oauth/token/.

After obtaining the new access token and refresh token, remember to update the stored refresh token value. Keep in mind that the previous refresh token remains valid for 1 minute after the issuance of the new one. In case of any unexpected errors, such as a network outage, you can use the old refresh token to request new access and refresh tokens.

Do not attempt to use old refresh tokens to obtain a new access token. Doing so will cause the connection to be invalidated, as Airwallex interprets that as a potential signal that your refresh tokens were leaked or compromised by a third party.

Access tokens may become invalid if:

  • The access token is expired: You will need to use your refresh token to renew the access token
  • Your user revoked access: If a user disconnects their Airwallex account from your application, it invalidates the access token and refresh token. You will need to ask your users to start the authorization flow again
On this page