Respond to authorization requests

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

Before you begin

• Contact your Airwallex Account Manager to enable Issuing APIs, Cards, Remote Authorization for your Airwallex account.
• If you have a Scale platform account, enabling remote authorization on the platform account also enables remote authorization for connected accounts.
• Obtain your access token API by authenticating to Airwallex using your unique Client ID and API key. You will need the access token to make API calls.
• Configure remote authorization, including HTTPS endpoint, default action, etc., using Update issuing config API. For more information, see Configure remote authorization.

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.

JSON
1{
2   "account_id":"acct_10SP6nLeM9utP9i6gDt93w",
3   "card_id":"aaf19d28-b638-4ce8-b0a3-793d47b7def1",
4   "transaction_id":"47f9739c-3501-49ae-b929-febd028c905d",
5   "transaction_type":"CLEARING",
6   "transaction_date":"2022-07-15T01:48:27.787+0000",
7   "transaction_amount":11.11,
8   "transaction_currency":"AUD",
9   "merchant":{
10      "id":"057186312156189",
11      "name":"CARD_TX_GENERATOR  REMOTE",
12      "city":"AUTH  TEST",
13      "country":"AWX",
14      "state":"TX",
15      "postcode":"70000",
16      "category_code":"7531"
17   },
18   "auth_code":"266232",
19   "masked_card_number":"************5353",
20   "retrieval_ref":"317843885701",
21   "client_data":"",
22   "card_nickname":"",
23   "network_transaction_id":"6450014364553208",
24   "acquiring_institution_id":"471471",
25   "merchant_id":"422899490014419",
26   "billing_order":[
27      {
28         "currency":"AUD",
29         "amount":11.11
30      },
31      {
32         "currency":"USD",
33         "amount":7.99
34      }
35   ]
36}

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.

Shell
1# Request Headers
2
3"x-nonce": "1650458086181.oIS519+CsXhPOM8X",
4"x-signature": "3qBE5ZmGis7ZlTEwiGRJxgH8jgAsHoSoqM6VSp6paCM="
5

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

Kotlin
1import com.google.api.client.util.Base64
2import org.apache.commons.codec.digest.HmacAlgorithms
3import org.apache.commons.codec.digest.HmacUtils
4
5val hmacStr = HmacUtils(HmacAlgorithms.HMAC_SHA_256, sharedSecret).hmac(x-nonce)
6val signature = Base64.encodeBase64String(hmacStr)
7

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

JSON
1{ 
2    "transaction_id": "47f9739c-3501-49ae-b929-febd028c905d",
3    "response_status": "AUTHORIZED",
4    "status_reason": "valid transaction"
5}

Example JSON for a Declined response

JSON
1{ 
2    "transaction_id": "47f9739c-3501-49ae-b929-febd028c905d",
3    "response_status": "DECLINED",
4    "status_reason": "failed internal risk assessment"
5}

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:

JSON
1...
2"remote_auth": {
3                   "default_action_used": false,
4                   "duration": 247,
5                   "response_status": "AUTHORIZED",
6                   "status_reason": "Transaction Approved",
7                   "timed_out": false
8                },
9...

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