Authorizations

You can view authorizations such as pre auth and capture processed against individual cards or for all cards created within your organisation.

Endpoints

GET /api/v1/issuing/authorizations
GET /api/v1/issuing/authorizations/{id}

Get authorization status

GET /api/v1/issuing/authorizations

Copy for LLMView as Markdown

Retrieve the status of an authorization. Will default to a 30 day period unless both to and from created_at request fields are populated.

Parameters

billing_currencystring

Currency in which transition was billed. (3-letter ISO-4217 code)

card_idstring

Unique Identifier for card

digital_wallet_token_idstring

Unique Identifier for digital token

from_created_atstring

start of Transaction Date in ISO8601 format (inclusive)

lifecycle_idstring

Unique Identifier for lifecycle

page_numinteger

Page number, starts from 0

page_sizeinteger

Number of results per page

retrieval_refstring

Retrieval reference number

statusstring

Authorization status, Can be one of CLEARED, EXPIRED, FAILED, PENDING, REVERSED

to_created_atstring

end of Transaction Date in ISO8601 format (exclusive)

Response body - 200 OK

has_moreboolean

itemsarray

items.acquiring_institution_identifierstring

Unique Identifier for acquiring institution

items.auth_codestring

Authorization Code

items.billing_amountnumber

Billing Amount

items.billing_currencystring

Billing Currency

items.card_idstring

Unique Identifier for card

items.card_nicknamestring

The nickname of the card used

items.card_transaction_dataobject

Card transaction identifiers associated with this authorization. Omitted for transactions created before January 2025.

items.card_transaction_data.card_transaction_event_idstring

Identifier of the individual card transaction event within the lifecycle. The closest equivalent of the transaction_id field.

items.card_transaction_data.card_transaction_idstring

Identifier of the card transaction. Retrieve its details via GET /api/v1/issuing/card_transactions/{id}.

items.card_transaction_data.card_transaction_lifecycle_idstring

Identifier that links related transactions belonging to the same card payment — such as authorizations, reversals, captures, and refunds — under a single lifecycle.

items.client_datastring

Client data stored against the card record

items.create_timestring

The time this outstanding authorization was created

items.digital_wallet_token_idstring

Unique Identifier for digital token

items.expiry_datestring

The authorization will expire after this date if not posted

items.failure_reasonstring

The reason why this authorization failed (if status is FAILED). Can be one of: ACCOUNT_INVALID, CARD_CLOSED, CARD_INACTIVE, CARD_INVALID, CARD_LOST_STOLEN, CARD_NOT_ACTIVATED, CARD_REISSUED_TO_NEW_NUMBER, CARDHOLDER_VERIFICATION_FAILED, CURRENCY_NOT_ALLOWED, CVV_INVALID, EXPIRY_MISSING, INSUFFICIENT_AVAILABLE_CREDIT, INSUFFICIENT_FUNDS, INTERNAL_ERROR, INVALID_EXPIRY_DATE, LIMIT_EXCEEDED, MERCHANT_CATEGORY_NOT_ALLOWED, NOT_SUPPORTED, OUT_OF_ALLOWED_TIME_RANGE, PIN_INVALID, PIN_RETRIES_EXCEEDED, REMOTE_AUTH_DECLINED, RESTRICTED_COUNTRY, SUSPECTED_FRAUD, TRANSACTION_BLOCKED, TRANSACTION_BLOCKED_AT_TERMINAL, TRANSACTION_USAGE_DISABLED, MERCHANT_COUNTRY_NOT_ALLOWED, MERCHANT_BRAND_NOT_ALLOWED, MERCHANT_BRAND_CATEGORY_NOT_ALLOWED, MERCHANT_BRAND_SUBCATEGORY_NOT_ALLOWED. Learn more about transaction failure reasons .

items.fee_detailsarray

List of fee details associated with the authorization

items.fee_details.amountnumber

Fee amount.

items.fee_details.currencystring

Currency in which the fee is charged (3-letter ISO-4217 code).

items.fee_details.typestring

Fee type. One of: ATM_ACCESS_FEE.

items.lifecycle_idstring

A identifier that links multiple related transactions belonging to the same card payment—such as authorizations, reversals, captures, and refunds—under a single transaction lifecycle. Note: this field will be null for transactions created before January 2025

items.masked_card_numberstring

Masked card number

items.merchantobject

merchant of the card transaction

items.merchant.additional_merchant_infoobject

Merchant additional info

items.merchant.additional_merchant_info.merchant_categorystring

Merchant category

items.merchant.additional_merchant_info.merchant_full_namestring

Merchant full name

items.merchant.additional_merchant_info.merchant_logo_urlstring

Merchant logo url

items.merchant.additional_merchant_info.merchant_sub_categorystring

Merchant sub category

items.merchant.category_codestring

Merchant category code

items.merchant.citystring

Merchant city

items.merchant.countrystring

Merchant country. Note: this field might prefixed with state name for some countries, e.g. TXUSA, you should parse the last 3 characters for country code.

items.merchant.identifierstring

Unique identifier for merchant

items.merchant.namestring

Merchant name

items.merchant.postcodestring

Merchant postcode (only for merchants within the US, Canada or Brazil)

items.merchant.statestring

Merchant state (only for merchants within the US, Canada or Brazil)

items.network_transaction_idstring

The transaction unique identifier from VISA network

items.retrieval_refstring

Transaction retrieval reference number. Data element 37 of a financial transaction message (https://en.wikipedia.org/wiki/ISO_8583)

items.risk_detailsobject

Risk details provides a comprehensive overview of the risk evaluation for a card transaction, including identified risk factors, actions taken by the risk engine, and the outcome of the 3D Secure authentication process. It encapsulates key elements that assess the potential threat level, safeguard the transaction, and ensure the cardholder’s identity is verified. N.b. this information will only be available for transactions on or after 1st Sept 2024.

items.risk_details.risk_actions_performedarray

Risk actions performed for a card transaction, triggered by rules in our risk engine

items.risk_details.risk_factorsarray

Risk factors are conditions or variables that increase the likelihood of fraud or financial irregularities, assessed by our risk management system to determine the threat level of a transaction

items.risk_details.three_dsecure_outcomestring

The outcome of a 3D Secure authentication process, which verifies the identity of a cardholder during an online purchase. Can be one of: ATTEMPTED, AUTHENTICATED, FAILED, NOT_APPLICABLE, NOT_REQUESTED. Learn more about 3D Secure

items.statusstring

The status of this authorization. Can be one of CLEARED, EXPIRED, FAILED, PENDING, REVERSED

items.transaction_amountnumber

Transaction amount

items.transaction_currencystring

Transaction currency

items.transaction_idstring

Unique id for transaction

items.updated_by_transactionstring

Id of the transaction which updated status of this transaction. eg: capture

Errors

Error status	Description
400	Possible errors: `field_required`, `bad_request`, `invalid_argument`
401	Possible errors: `credentials_invalid`, `credentials_expired`
429	Too many requests
500	Service unavailable

GET /api/v1/issuing/authorizations

$curl --request GET \
>  --url 'https://api-demo.airwallex.com/api/v1/issuing/authorizations' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json'

Response (200 OK)

1{
2  "has_more": false,
3  "items": [
4    {
5      "acquiring_institution_identifier": "123456",
6      "auth_code": "000001",
7      "billing_amount": 1000,
8      "billing_currency": "USD",
9      "card_id": "6c2dc266-09ad-4235-b61a-767c7cd6d6ea",
10      "client_data": "Some client data",
11      "create_time": "2018-03-22T16:08:02+00:00",
12      "digital_wallet_token_id": "91eb855a-8169-40ea-b428-8405372da9a5",
13      "expiry_date": "2018-03-22T16:08:02+00:00",
14      "failure_reason": "INSUFFICIENT_FUNDS",
15      "fee_details": [
16        {
17          "amount": 500,
18          "currency": "USD",
19          "type": "ATM_ACCESS_FEE"
20        }
21      ],
22      "lifecycle_id": "95ede192-3a86-461e-96d9-f51b55aae79e",
23      "masked_card_number": "************4242",
24      "merchant": {
25        "additional_merchant_info": {
26          "merchant_category": "Professional Services",
27          "merchant_full_name": "Meta",
28          "merchant_logo_url": "https://example.com/merchant-logo.png",
29          "merchant_sub_category": "Advertising and Marketing"
30        },
31        "category_code": "4829",
32        "city": "San Francisco",
33        "country": "USA",
34        "identifier": "012345678910123",
35        "name": "Merchant A",
36        "postcode": "94111",
37        "state": "CA"
38      },
39      "network_transaction_id": "3951729271768745",
40      "retrieval_ref": "909916088001",
41      "risk_details": {
42        "risk_actions_performed": [
43          "TRANSACTION_BLOCKED"
44        ],
45        "risk_factors": [
46          "Suspicious transaction velocity"
47        ],
48        "three_dsecure_outcome": "AUTHENTICATED"
49      },
50      "status": "PENDING",
51      "transaction_amount": 100,
52      "transaction_currency": "USD",
53      "transaction_id": "6c2dc266-09ad-4235-b61a-767c7cd6d6ea",
54      "updated_by_transaction": "6c2dc266-09ad-4235-b61a-767c7cd6d6ea"
55    }
56  ]
57}

Was this section helpful?

Get single authorization status

GET /api/v1/issuing/authorizations/{id}

Copy for LLMView as Markdown

Retrieve single authorization status

Parameters

idrequiredstring

Unique Identifier for transaction

Response body - 200 OK

acquiring_institution_identifierstring

Unique Identifier for acquiring institution

auth_codestring

Authorization Code

billing_amountnumber

Billing Amount

billing_currencystring

Billing Currency

card_idstring

Unique Identifier for card

card_nicknamestring

The nickname of the card used

card_transaction_dataobject

Card transaction identifiers associated with this authorization. Omitted for transactions created before January 2025.

card_transaction_data.card_transaction_event_idstring

Identifier of the individual card transaction event within the lifecycle. The closest equivalent of the transaction_id field.

card_transaction_data.card_transaction_idstring

Identifier of the card transaction. Retrieve its details via GET /api/v1/issuing/card_transactions/{id}.

card_transaction_data.card_transaction_lifecycle_idstring

Identifier that links related transactions belonging to the same card payment — such as authorizations, reversals, captures, and refunds — under a single lifecycle.

client_datastring

Client data stored against the card record

create_timestring

The time this outstanding authorization was created

digital_wallet_token_idstring

Unique Identifier for digital token

expiry_datestring

The authorization will expire after this date if not posted

failure_reasonstring

fee_detailsarray

List of fee details associated with the authorization

fee_details.amountnumber

Fee amount.

fee_details.currencystring

Currency in which the fee is charged (3-letter ISO-4217 code).

fee_details.typestring

Fee type. One of: ATM_ACCESS_FEE.

lifecycle_idstring

masked_card_numberstring

Masked card number

merchantobject

merchant of the card transaction

merchant.additional_merchant_infoobject

Merchant additional info

merchant.additional_merchant_info.merchant_categorystring

Merchant category

merchant.additional_merchant_info.merchant_full_namestring

Merchant full name

merchant.additional_merchant_info.merchant_logo_urlstring

Merchant logo url

merchant.additional_merchant_info.merchant_sub_categorystring

Merchant sub category

merchant.category_codestring

Merchant category code

merchant.citystring

Merchant city

merchant.countrystring

Merchant country. Note: this field might prefixed with state name for some countries, e.g. TXUSA, you should parse the last 3 characters for country code.

merchant.identifierstring

Unique identifier for merchant

merchant.namestring

Merchant name

merchant.postcodestring

Merchant postcode (only for merchants within the US, Canada or Brazil)

merchant.statestring

Merchant state (only for merchants within the US, Canada or Brazil)

network_transaction_idstring

The transaction unique identifier from VISA network

retrieval_refstring

Transaction retrieval reference number. Data element 37 of a financial transaction message (https://en.wikipedia.org/wiki/ISO_8583)

risk_detailsobject

risk_details.risk_actions_performedarray

Risk actions performed for a card transaction, triggered by rules in our risk engine

risk_details.risk_factorsarray

Risk factors are conditions or variables that increase the likelihood of fraud or financial irregularities, assessed by our risk management system to determine the threat level of a transaction

risk_details.three_dsecure_outcomestring

statusstring

The status of this authorization. Can be one of CLEARED, EXPIRED, FAILED, PENDING, REVERSED

transaction_amountnumber

Transaction amount

transaction_currencystring

Transaction currency

transaction_idstring

Unique id for transaction

updated_by_transactionstring

Id of the transaction which updated status of this transaction. eg: capture

Errors

Error status	Description
400	Possible errors: `field_required`, `bad_request`, `invalid_argument`
401	Possible errors: `credentials_invalid`, `credentials_expired`
429	Too many requests
500	Service unavailable

GET /api/v1/issuing/authorizations/{id}

$curl --request GET \
>  --url 'https://api-demo.airwallex.com/api/v1/issuing/authorizations/authorization_id' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json'

Response (200 OK)

1{
2  "acquiring_institution_identifier": "123456",
3  "auth_code": "000001",
4  "billing_amount": 1000,
5  "billing_currency": "USD",
6  "card_id": "6c2dc266-09ad-4235-b61a-767c7cd6d6ea",
7  "card_nickname": "<string>",
8  "client_data": "Some client data",
9  "create_time": "2018-03-22T16:08:02+00:00",
10  "digital_wallet_token_id": "91eb855a-8169-40ea-b428-8405372da9a5",
11  "expiry_date": "2018-03-22T16:08:02+00:00",
12  "failure_reason": "INSUFFICIENT_FUNDS",
13  "fee_details": [
14    {
15      "amount": 500,
16      "currency": "USD",
17      "type": "ATM_ACCESS_FEE"
18    }
19  ],
20  "lifecycle_id": "95ede192-3a86-461e-96d9-f51b55aae79e",
21  "masked_card_number": "************4242",
22  "merchant": {
23    "additional_merchant_info": {
24      "merchant_category": "Professional Services",
25      "merchant_full_name": "Meta",
26      "merchant_logo_url": "https://example.com/merchant-logo.png",
27      "merchant_sub_category": "Advertising and Marketing"
28    },
29    "category_code": "4829",
30    "city": "San Francisco",
31    "country": "USA",
32    "identifier": "012345678910123",
33    "name": "Merchant A",
34    "postcode": "94111",
35    "state": "CA"
36  },
37  "network_transaction_id": "3951729271768745",
38  "retrieval_ref": "909916088001",
39  "risk_details": {
40    "risk_actions_performed": [
41      "TRANSACTION_BLOCKED"
42    ],
43    "risk_factors": [
44      "Suspicious transaction velocity"
45    ],
46    "three_dsecure_outcome": "AUTHENTICATED"
47  },
48  "status": "PENDING",
49  "transaction_amount": 100,
50  "transaction_currency": "USD",
51  "transaction_id": "6c2dc266-09ad-4235-b61a-767c7cd6d6ea",
52  "updated_by_transaction": "6c2dc266-09ad-4235-b61a-767c7cd6d6ea"
53}

Was this section helpful?