Existing customers
Step 1: Allow Airwallex customers to authorise your application
On your user interface, implement a "Connect to Airwallex" button on your user interface. Users can click this button to connect their Airwallex account to your application. Upon clicking, the button should initiate our OAuth authorisation flow URL:
https://airwallex.com/oauth/authorize?response_type=code&client_id=YOUR_APPID&redirect_uri=YOUR_REDIRECT_URI&scope=YOUR_SCOPES
Specify all the scopes within YOUR_SCOPES that you plan to leverage in the authorisation flow during integration. This authorisation flow is mandatory when users initially connect to your application and is also necessary when your application requires access to additional scopes.
Customers will be directed to log in to their Airwallex account, choose the specific account they wish to link to your application, and review the permissions that your application is seeking.
Upon granting consent for your application to access their Airwallex account, users will be redirected back to YOUR_REDIRECT_URI with an authorisation code. In the event of non-consent, Airwallex will redirect users back to YOUR_REDIRECT_URI, accompanied by an error notification Otherwise, Airwallex will redirect back to YOUR_REDIRECT_URI with an error.
https://YOUR_REDIRECT_URI/?code=AUTH_CODE
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
After successfully acquiring the authorisation code, your application should exchange the authorisation 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). 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 authorised 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 APIs across sessions. To do so, use the latest refresh token value from your previous call to /oauth/token/.
This will give you a new access token and refresh token. You should replace the previously-stored refresh token value with the new one. Note 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 under the following circumstances:
- Expiration: If the access token expires, utilise your refresh token to renew it.
- User Revocation: In the event that a user disconnects their Airwallex account from your application, both the access token and refresh token are invalidated. In such cases, it is necessary to prompt your users to initiate the authorisation flow once again.