Log inGet started
Airwallex logo
Online Payments
Transactional FX
Open Banking
Developer Tools
API Reference
Introduction to Issuing
Issuing Use Cases
Authorisation Controls
Currency Based ControlsMerchant Based ControlsTransaction Based ControlsTime Based ControlsRemote Authorisation Controls
Remote Authorisation ScenariosRemote Authorisation TimeoutRemote Authorisation Config Tutorial Setup your Remote Authorisation Endpoint
Handling Exceptions
Merchant Category Codes

Setup your Remote Authorisation Endpoint

A technical guide of how to setup your remote authorisation endpoint

In order to perform remote authorisation, you must first set up a HTTPS endpoint and provide the URL to this endpoint for requests to be directed to (please refer to example endpoint for more details). Along with this, a fallback action must be chosen (AUTHORIZED | DECLINED) to be used in the unlikely case of network failures or request timeouts. You can do the configuration via our API. You will get a shared secret that will be used to generate digital signatures on all transaction requests. (More details in signature validation section)

Enable your remote authorisation config

Please refer to Remote Authorisation Config Tutorial for how to config remote authorisation setting via our API API

An example config:


Receive Remote Authorisation Request

Below is the standard body of a Remote Authorisation request (in the form of a POST request).

data fieldContent
account_idOpenId for the account, this could be the connected accountId if you are a scale user
card_idUUID for the card which made the transaction
transaction_idUUID for the transaction, you can use this Id to retrival transaction in our API
transaction_typeCould be CLEARING or AUTHORIZATION
transaction_dateTransaction date time in GMT
transaction_amountTransaction amount
transaction_currencyTransaction currency
merchantMerchant info include name, city, county and MCC code
auth_codeAuth code which can be used to retrival transaction in API
masked_card_numberMasked card number for the transaction card
retrieval_refRetrieval reference code which can be used to retrival transaction in API
client_dataClient data for the transaction card
card_nicknameNick name for the transaction card
network_transaction_idTransaction Id from VISA network
billing_orderWallet deduct attempt order, Airwallex will use this order as priority to deduct the money from first currency wallet with sufficient fund

Please note there are two different transaction type support remote authorisation you can find all example request body in Remote Authorisation Scenarios

Signature validation

In addition to the request body, we attach a digital signature to each request to allow for verification of the remote authorisation request sent by Airwallex. This signature is sent as a base64 string in the ‘x-signature’ header and comprises a HMAC-SHA256 encoding of a randomly generated nonce, sent in the ‘x-nonce’ header. Prepended to the nonce is an epoch timestamp in milliseconds, which can be used to validate the timeliness of the received message

To validate that a request received is legitimate and authentic: Extract the x-nonce from the request header Compute an HMAC with the SHA-256 hash function on the x-nonce, using your configured shared secret as the key Compare the x-signature in the header to the expected signature. Additionally, the timestamp prepended on the x-nonce before the ‘.’ delimiter can be used to validate the timeliness of the received message

Kotlin Example for generating signature


Respond to Remote Authorisation Request

Once the request has been sent by our service, we allow up to 2 seconds to receive a response, either authorizing or declining the request. The corresponding transaction ID as well as a ‘reason’ pertaining to the status of the response should also be included in the response body and will be stored along with the transaction in our logs. In the case of a request timeout, any received responses will be ignored and the fallback action will be performed.

Response JSON Authorized


It is worth noting that approval of the transaction does not solely depend on this response, our authorisation service runs an internal risk assessment simultaneously and a transaction must pass through all checks in order to be authorized. For more details please refer to Remote Authorisation Scenarios

Check Transaction Results

Once your remote authorisation endpoint has been configured, remote authorisation data will be included as a field in the body of webhook notifications and transaction API responses so that you can better understand how your response has affected the overall authorisation process. An example of this field can be seen below:

This field will only be present for transactions that require remote authorisation.

The authorisation status of individual transactions can be retrieved via our API or web app. Refer to the following docs for more information: Product doc Authorizations API Product doc Transactions API

Additional information regarding individual transactions can also be retrieved using Airwallex’s webhook services. Please refer to the webhook documentation for instructions regarding this process: Issuing webhooks

Testing the service

We have created a sandbox API to allow generation of mock transactions in our demo environment, allowing you to test the availability and correctness of your remote authorisation endpoint. The following tutorial will step through how to generate a mock transaction within our demo environment. Please refer to Generate card issuing transactions for more information.

Example Endpoint

This is a template for a Remote Authorisation endpoint written in Kotlin with Spring Boot.