Log inGet started
Airwallex logo
Core API
Transactional FX
Back to home
OverviewUnderstanding Banking as a ServiceSupported regions and currencies
Get started
Create cardholders
Create cards
Authorization controls
Remote authorization
Remote authorization scenariosConfigure remote authorizationRespond to authorization requests
Retrieve authorizationsTest remote authorizationHandle exceptions
Test and go live

Respond to authorization requests

This guide describes how to respond to remote authorization requests sent from Airwallex.

Before you begin

Step 1: Receive a remote authorization request

If you are enabled and configured for remote authorization, Airwallex sends a JSON payload on your configured HTTPS endpoint when an authorization transaction is initiated on the card associated with your Airwallex account. The authorization transaction can be part of a single message or a dual message. See Remote authorization scenarios for more information.

account_idAccount identifier of your Airwallex account. This could, be the Connected account Id if you are a Scale user.
card_idUnique identifier for the card that initiated the transaction.
transaction_idUnique identifier for the transaction, you can use this identifier to retrieve the transaction using Get transactions.
transaction_typePossible values: CLEARING, AUTHORIZATION
transaction_dateTimestamp of the transaction in GMT.
transaction_amountThe transaction amount to be authorized.
transaction_currencyTransaction currency.
merchant objectMerchant information includes name, city, country and MCC code.
auth_codeAuth code which can be used to retrieve the transaction.
masked_card_numberMasked card number of the card.
retrieval_refRetrieval reference code, which can be used to retrieve the transaction using Get transactions API.
client_dataClient data for the transaction card.
card_nicknameNick name for the transaction card.
network_transaction_idTransaction Id from VISA network.
acquiring_institution_idThe identifier from the network for the acquirer that sent the request.
billing_orderIndicates the priority order of Airwallex wallets for sourcing funds for the transaction. Airwallex will deduct the funds from the first currency wallet with sufficient funds.

Step 2: Validate digital signatures

In addition to the request body, Airwallex attaches a digital signature to each request to allow you to verify that the remote authorization request was sent by Airwallex.

The signature and the nonce are sent using the following request headers:

  • x-signature : Contains the signature sent as a base-64 string.
  • x-nonce: Contains a HMAC-SHA256 encoding of a randomly generated nonce. Prepended to the nonce is an epoch timestamp in milliseconds, which can be used to validate the timeliness of the received message.

Follow these steps to validate that the remote authorization request received is legitimate and authentic:

  1. Extract the x-nonce from the request header.
  2. Compute an HMAC with the SHA-256 hash function on the x-nonce, using your configured shared_secret as the key.
  3. 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.
  4. If a signature matches, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.
Kotlin example for generating a signature

Step 3: Respond to the remote authorization request

Once Airwallex sends the remote authorization request, you have up to two seconds to send a response, either authorizing or declining the request.

You must send the corresponding transaction ID as well as a reason pertaining to the status of the response in the response body. This will be stored along with the transaction in our logs. In the case of a request timeout, Airwallex ignores any received responses and the configured default action will be performed.

Example JSON for an Authorized response
Example JSON for a Declined response

After receiving your decision, Airwallex performs internal risk and regulatory reviews before finalizing the authorization response. Airwallex can decline an approved decision based on the risk and regulatory checks. See Handling exceptions for more details.

Step 4: Check transaction results

Once your remote authorization endpoint has been configured, remote authorization data will be included as a field in webhook notification payloads and transaction API responses to allow you to better understand how your decision has affected the overall authorization process. This field will only be returned for transactions that require remote authorization. Shown below is an example of this field in the transaction response:


You can retrieve the status of all authorizations (single message and dual message) processed against your cards. For information, see Retrieve authorizations.

On this page