Airwallex logo
Airwallex logoAirwallex logo

Cards

Copy for LLMView as Markdown

You can create virtual cards associated with your organisation, these cards can be single or multi-usage and be restricted by merchant code, currency and transaction amount.

Endpoints
POST /api/v1/issuing/cards/create
GET /api/v1/issuing/cards/{id}
GET /api/v1/issuing/cards
POST /api/v1/issuing/cards/{id}/update
POST /api/v1/issuing/cards/{id}/activate
POST /api/v1/issuing/cards/{id}/provision_digital_token
GET /api/v1/issuing/cards/{id}/details
GET /api/v1/issuing/cards/{id}/limits

Create a Card

POST /api/v1/issuing/cards/create

Copy for LLMView as Markdown

The card object is the actual resource associated with the card issued out by Airwallex. It holds details such as linked account, embossed name (for physical cards), shipping method and information (for physical cards), card based spend controls (eg. transaction limits, blocked merchant category codes etc.). The card object also determines who the card is for (ie for clients or their customers/employees), form factor (physical or virtual), and the number of uses (single or multiple).

Request body
authorization_controlsrequiredobject

Spend controls that determine the rules and restrictions to check for transaction authorizations.

authorization_controls.allowed_transaction_countrequiredstring

Specifies whether this card is a Single or Multiple Use card. Single Use means that the card can only be used for 1 successful debit transaction.

SINGLE
MULTIPLE
authorization_controls.transaction_limitsrequiredobject

Transaction limits for the card. Multiple transaction limits can be configured based on single currency. Each transaction will be checked against the limits with interval after currency conversion rate applied.

authorization_controls.transaction_limits.limitsrequiredarray

Transaction limits are based on interval and amount.

If the per transaction limit is not set, the default per transaction limit amount for the selected limit currency will be used. The default per transaction amount is part of account settings. To change the default per transaction limit, please reach out to your account manager.

The account holder may be liable for any unauthorised spending on the card, so please apply limits responsibly.

authorization_controls.transaction_limits.limits.amountrequirednumber

Transaction limit amount. This field is mandatory and must be greater than 0. Customer can set perTransaction limit up to a maximum amount (The maximum amount is part of account setting).

authorization_controls.transaction_limits.limits.intervalrequiredstring

Transaction limit interval. This field is mandatory and must be one of: PER_TRANSACTION, DAILY, WEEKLY, MONTHLY, ALL_TIME.

authorization_controls.transaction_limits.cash_withdrawal_limitsarray

Cash withdrawal transaction limits are based on interval and amount.

If the daily limit is not set, the default daily limit amount for the selected limit currency will be used. The default daily limit amount is part of the account setting. To change the default daily limit amount, please reach out to your account manager.

Please note that the cash withdrawal transaction limits apply exclusively to cash withdrawals and are imposed to help manage potential liability for the account holder and for Airwallex. The account holder may be liable for any unauthorised spending on the card, so please apply the limits responsibly.

Important: This limit will only appear if you have cash withdrawals enabled. Please speak to your account manager if you would like to enable cash withdrawals.

authorization_controls.transaction_limits.cash_withdrawal_limits.amountrequirednumber

Transaction limit amount. This field is mandatory and must be greater than 0. Customer can set perTransaction limit up to a maximum amount (The maximum amount is part of account setting).

authorization_controls.transaction_limits.cash_withdrawal_limits.intervalrequiredstring

Transaction limit interval. This field is mandatory and must be one of: PER_TRANSACTION, DAILY, WEEKLY, MONTHLY, ALL_TIME.

authorization_controls.transaction_limits.currencystring

Currency for transaction limits (3-letter ISO-4217 code). Will use USD if not set. Examples of valid base currencies are USD, AUD, GBP, EUR, CNY, HKD, SGD, NZD, JPY, CAD, CHF. More currencies may be available for your account: you may query the full list by calling the Get issuing config endpoint.

authorization_controls.active_fromstring

If provided, authorizations prior to this time will be rejected.

authorization_controls.active_tostring

If provided, authorizations after this time will be rejected.

authorization_controls.allowed_currenciesarray

Allowed Currencies for transactions. Please note if this field is absent from request payload, or has a value of null or empty array [], then all transaction currencies will be allowed.

authorization_controls.allowed_merchant_brandsobject

Allowed Merchant Brands rules for transactions. Please note if this field is absent from request payload, then transactions from all merchant brands will be allowed.

authorization_controls.allowed_merchant_brands.categoriesarray

Allowed Merchant Brands Categories for transactions. These must be provided using the codes defined in the Merchant Brands Controls product pageDocs. Please note if this field is absent from request payload, or has a value of null or empty array [], then transactions from all merchant brand categories will be allowed.

authorization_controls.allowed_merchant_brands.idsarray

Allowed Merchant Brand identifiers for transactions. Please note if this field is absent from request payload, or has a value of null or empty array [], then transactions from all merchant brand ids will be allowed. You can search for Merchant Brands ids using the Merchant Brands API.

authorization_controls.allowed_merchant_brands.subcategoriesarray

Allowed Merchant Brands Subcategories for transactions. These must be provided using the codes defined in the Merchant Brands Controls product pageDocs. Please note if this field is absent from request payload, or has a value of null or empty array [], then transactions from all merchant brand subcategories will be allowed.

authorization_controls.allowed_merchant_categoriesarray

Allowed Merchant Category Codes. Please note if this field is absent from request payload, or has a value of null or empty array [], then all merchant categories will be allowed.

authorization_controls.allowed_merchant_countriesarray

Allowed Merchant Countries for transactions. Please note if this field is absent from request payload, or has a value of null or empty array [], then transactions from all merchant countries will be allowed (although some may still be blocked by our risk team).

authorization_controls.blocked_transaction_usagesarray

List of disabled transaction usages, based on transaction_scope and usage_scope values. Please note if this field is absent from request payload or has a value of null, then all transaction usages will be allowed unless a default configration is added.

You can add multiple transaction_scope and usage_scope values. The most restrictive scope(s) would apply.

authorization_controls.blocked_transaction_usages.transaction_scopestring

Types of transaction scope. It can be one of: ALL_TRANSACTIONS, ONLINE_TRANSACTION, CONTACTLESS_TRANSACTION, CONTACT_CHIP_TRANSACTION, MAGSTRIPE, CASH_WITHDRAWAL, BILL_PAYMENT, ACCOUNT_FUNDING.

authorization_controls.blocked_transaction_usages.usage_scopestring

Determines if a transaction can be made domestically and/or internationally. It can be one of: ALL, INTERNATIONAL, DOMESTIC.

created_byrequiredstring

Full legal name of user requesting new card.

form_factorrequiredstring

Form of the card - PHYSICAL or VIRTUAL.

issue_torequiredstring

Who the card is issued to - client or individual. A value of ORGANISATION indicates that the card will be issued to the client themselves i.e. Purchasing Card.

request_idrequiredstring

A unique request identifier specified by the client. Requests with the same request_id will be ignored. This allows requests to be replayed if client is unsure of the outcome, e.g. due to network issues, system failures, etc. Note: Can be non-UUID as long as it is unique between requests.

activate_on_issueboolean

Set this to true to activate the physical card when it is created. This will enable use of the card while it’s being delivered to the cardholder. Virtual cards will always be activated upon creation.

cardholder_idstring

The unique identifier of the cardholder to associate this card with.

client_datastring

Client data which will be stored against the card record in Airwallex.

metadataobject

A set of key-value pairs that can be attached to the Card. You can specify up to 20 keys, with key names up to 20 characters long and values up to 150 characters long.

nick_namestring

A nick name for the card.

notestring

Notes that are to be stored against the card request (for client reference).

postal_addressobject

Optional postal address of physical card delivery. The card will be issued to the cardholder's postal address if this value is not set. The cardholder's address will be used instead if cardholder's postal address does not exist.

postal_address.cityrequiredstring

City of address.

postal_address.countryrequiredstring

ISO country code of address.

postal_address.line1requiredstring

Address line 1.

postal_address.postcoderequiredstring

Address postcode or ZIP code.

postal_address.line2string

Address line 2.

postal_address.statestring

Address state or region.

primary_contact_detailsobject

Details of the primary contact of the new card. Only valid when issue_to is ORGANISATION.

primary_contact_details.emailstring

The email address of the primary contact of the new card.

primary_contact_details.full_namestring

Full name of the primary contact of the new card.

primary_contact_details.mobile_numberstring

The mobile number of the primary contact of the new card.

purposestring

Optional purpose for card's usage when card issueTo is ORGANISATION. Can be one of - BUSINESS_EXPENSES, CLIENT_EXPENSES, MARKETING_EXPENSES, OFFICE_SUPPLIES, ONLINE_PURCHASING, OTHER, SUBSCRIPTIONS, TEAM_EXPENSES, TRAVEL_EXPENSES. Default value is BUSINESS_EXPENSES.

typestring

Card type - PREPAID, DEBIT, GOOD_FUNDS_CREDIT or DD_OTA. DD_OTA is Deferred Debit card available for OTA (Online Travel Agent) customers only in UK/Europe countries. If card type is not set, the default card type which is a part of your account setting will be used.

Response body - 202 Accepted
activate_on_issueboolean

Set this to true to activate the physical card when it is created. This will enable use of the card while it’s being delivered to the cardholder. Virtual cards will always be activated upon creation.

all_card_versionsarray

Contains information about all versions of a card. A version changes with change in PAN

all_card_versions.card_numberstring

Masked card number of this version

all_card_versions.card_statusstring

Card status of this version. See Card StatusDocs for definitions.

PENDING
FAILED
INACTIVE
ACTIVE
LOST
STOLEN
CLOSED
BLOCKED
EXPIRED
UNKNOWN
all_card_versions.card_versioninteger

Version Id which uniquely identifies this card version object

all_card_versions.created_atstring

Creation time of the card version.

authorization_controlsobject

Spend controls that determine the rules and restrictions to check for transaction authorizations.

authorization_controls.allowed_transaction_countstring

Specifies whether this card is a Single or Multiple Use card. Single Use means that the card can only be used for 1 successful debit transaction.

SINGLE
MULTIPLE
authorization_controls.transaction_limitsobject

Transaction limits for the card. Multiple transaction limits can be configured based on single currency. Each transaction will be checked against the limits with interval after currency conversion rate applied

authorization_controls.transaction_limits.limitsarray

Transaction limits are based on interval and amount.

If the per transaction limit is not set, the default per transaction limit amount for the selected limit currency will be used. The default per transaction amount is part of account settings. To change the default per transaction limit, please reach out to your account manager.

The account holder may be liable for any unauthorised spending on the card, so please apply limits responsibly.

authorization_controls.transaction_limits.limits.amountnumber

Transaction limit amount. This field is mandatory and must be greater than 0. Customer can set perTransaction limit up to a maximum amount (The maximum amount is part of account setting)

authorization_controls.transaction_limits.limits.intervalstring

Transaction limit interval. This field is mandatory and must be one of: PER_TRANSACTION, DAILY, WEEKLY, MONTHLY, ALL_TIME

authorization_controls.transaction_limits.cash_withdrawal_limitsarray

Cash withdrawal transaction limits are based on interval and amount.

If the daily limit is not set, the default daily limit amount for the selected limit currency will be used. The default daily limit amount is part of the account setting. To change the default daily limit amount, please reach out to your account manager.

Please note that the cash withdrawal transaction limits apply exclusively to cash withdrawals and are imposed to help manage potential liability for the account holder and for Airwallex. The account holder may be liable for any unauthorised spending on the card, so please apply the limits responsibly.

Important: This limit will only appear if you have cash withdrawals enabled. Please speak to your account manager if you would like to enable cash withdrawals.

authorization_controls.transaction_limits.cash_withdrawal_limits.amountnumber

Transaction limit amount. This field is mandatory and must be greater than 0. Customer can set perTransaction limit up to a maximum amount (The maximum amount is part of account setting)

authorization_controls.transaction_limits.cash_withdrawal_limits.intervalstring

Transaction limit interval. This field is mandatory and must be one of: PER_TRANSACTION, DAILY, WEEKLY, MONTHLY, ALL_TIME

authorization_controls.transaction_limits.currencystring

Currency for transaction limits (3-letter ISO-4217 code). Will use USD if not set. Examples of valid base currencies are USD, AUD, GBP, EUR, CNY, HKD, SGD, NZD, JPY, CAD, CHF. More currencies may be available for your account: you may query the full list by calling the Get issuing config endpoint.

authorization_controls.active_fromstring

If provided, authorizations prior to this time will be rejected.

authorization_controls.active_tostring

If provided, authorizations after this time will be rejected.

authorization_controls.allowed_currenciesarray

Allowed Currencies for transactions. Please note if this field is absent from request payload, or has a value of null or empty array [], then all transaction currencies will be allowed.

authorization_controls.allowed_merchant_brandsobject

Allowed Merchant Brands rules for transactions. Please note if this field is absent from request payload, then transactions from all merchant brands will be allowed.

authorization_controls.allowed_merchant_brands.categoriesarray

Allowed Merchant Brands Categories for transactions. These must be provided using the codes defined in the Merchant Brands Controls product pageDocs. Please note if this field is absent from request payload, or has a value of null or empty array [], then transactions from all merchant brand categories will be allowed.

authorization_controls.allowed_merchant_brands.idsarray

Allowed Merchant Brand identifiers for transactions. Please note if this field is absent from request payload, or has a value of null or empty array [], then transactions from all merchant brand ids will be allowed. You can search for Merchant Brands ids using the Merchant Brands API.

authorization_controls.allowed_merchant_brands.subcategoriesarray

Allowed Merchant Brands Subcategories for transactions. These must be provided using the codes defined in the Merchant Brands Controls product pageDocs. Please note if this field is absent from request payload, or has a value of null or empty array [], then transactions from all merchant brand subcategories will be allowed.

authorization_controls.allowed_merchant_categoriesarray

Allowed Merchant Category Codes. Please note if this field is absent from request payload, or has a value of null or empty array [], then all merchant categories will be allowed.

authorization_controls.allowed_merchant_countriesarray

Allowed Merchant Countries for transactions. Please note if this field is absent from request payload, or has a value of null or empty array [], then transactions from all merchant countries will be allowed (although some may still be blocked by our risk team).

authorization_controls.blocked_transaction_usagesarray

List of disabled transaction usages, based on transaction_scope and usage_scope values. Please note if this field is absent from request payload or has a value of null, then all transaction usages will be allowed unless a default configration is added.

You can add multiple transaction_scope and usage_scope values. The most restrictive scope(s) would apply.

authorization_controls.blocked_transaction_usages.transaction_scopestring

Types of transaction scope. It can be one of: ALL_TRANSACTIONS, ONLINE_TRANSACTION, CONTACTLESS_TRANSACTION, CONTACT_CHIP_TRANSACTION, MAGSTRIPE, CASH_WITHDRAWAL, BILL_PAYMENT, ACCOUNT_FUNDING

authorization_controls.blocked_transaction_usages.usage_scopestring

Determines if a transaction can be made domestically and/or internationally. It can be one of: ALL, INTERNATIONAL, DOMESTIC

brandstring

Card Brand

card_idstring

Unique Identifier for the card

card_numberstring

Masked card number

card_statusstring

Current card status. See Card StatusDocs for definitions.

PENDING
FAILED
INACTIVE
ACTIVE
LOST
STOLEN
CLOSED
BLOCKED
EXPIRED
UNKNOWN
card_versioninteger

Current version of the card

cardholder_idstring

The unique identifier of the cardholder this card is associated with if it is an individual card.

client_datastring

Client data which will be stored against the card record in Airwallex.

created_bystring

The creator of the card

delivery_detailsobject

Delivery detail of the card. Only available for physical cards.

delivery_details.delivery_modestring

MAIL: Delivery of the card is delivered via mail shipment. Tracking may or may not be provided. EXPRESS: Delivery of the card is tracked and delivered via express shipment. A tracking_link will always be provided.

MAIL
EXPRESS
UNKNOWN
delivery_details.delivery_vendorstring

Delivery vendor of this card.

UNKNOWN
AU_POST
EMS
HK_POST
CITY_LINK
DHL
CN_POST
PL_POST
USPS
FEDEX
delivery_details.mobile_numberstring

The mobile number for the card delivery.

delivery_details.preferred_delivery_modestring

The delivery mode customer selected when the Create Card API is called.

MAIL
EXPRESS
UNKNOWN
delivery_details.statusstring

See Delivery StatusDocs for definitions.

PENDING
PRINTED
FAILED_TO_PRINT
DISPATCHED
IN_TRANSIT
OUT_FOR_DELIVERY
DELIVERED
DELIVERY_FAILED
DELIVERY_DELAYED
UNKNOWN
delivery_details.status_descriptionstring

A brief description of the status

delivery_details.trackedboolean

Specifies if the delivery of the card is tracked. If true, a tracking link will be provided when status becomes DISPATCHED

delivery_details.tracking_numberstring

Delivery tracking number of this card.

delivery_details.updated_atstring

Last update time of the delivery details

form_factorstring

Form of the card

PHYSICAL
VIRTUAL
issue_tostring

Who the card is issued to - client or individual. A value of ORGANISATION indicates that the card will be issued to the client themselves i.e. Purchasing Card

ORGANISATION
INDIVIDUAL
metadataobject

A set of key-value pairs that can be attached to the Card. You can specify up to 20 keys, with key names up to 20 characters long and values up to 150 characters long.

name_on_cardstring

Name to be printed on card.

nick_namestring

A nick name for the card

notestring

Notes that are to be stored against the card request (for client reference)

postal_addressobject

Optional postal address of physical card delivery.

postal_address.citystring

City of address

postal_address.countrystring

ISO country code of address

postal_address.line1string

Address line 1

postal_address.postcodestring

Address postcode or ZIP code

postal_address.line2string

Address line 2

postal_address.statestring

Address state or region

primary_contact_detailsobject

Details of the primary contact of the card

primary_contact_details.emailstring

The email address of the primary contact of the new card.

primary_contact_details.full_namestring

Full name of the primary contact of the new card.

primary_contact_details.mobile_numberstring

The mobile number of the primary contact of the new card.

purposestring

The purpose of the card's usage. Only available for expense cards.

SUBSCRIPTIONS
OFFICE_SUPPLIES
MARKETING_EXPENSES
TRAVEL_EXPENSES
CLIENT_EXPENSES
TEAM_EXPENSES
ONLINE_PURCHASING
BUSINESS_EXPENSES
OTHER
request_idstring

A unique request identifier specified by the client. Requests with the same request_id will be ignored. This allows requests to be replayed if client is unsure of the outcome, e.g. due to network issues, system failures, etc. Note: Can be non-UUID as long as it is unique between requests

typestring

Card type - PREPAID, DEBIT, GOOD_FUNDS_CREDIT or DD_OTA. DD_OTA is Deferred Debit card available for OTA (Online Travel Agent) customers only in UK/Europe countries. If card type is not set, the default card type which is a part of your account setting will be used.

UNKNOWN
PREPAID
DEBIT
DD_OTA
GOOD_FUNDS_CREDIT
CREDIT
Errors
Error statusDescription
400

Possible errors: field_required, bad_request, invalid_argument

401

Possible errors: credentials_invalid, credentials_expired

429

Too many requests

500

Service unavailable

POST /api/v1/issuing/cards/create
$curl --request POST \
>  --url 'https://api.sandbox.airwallex.com/api/v1/issuing/cards/create' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "activate_on_issue": false,
>  "authorization_controls": {
>    "active_from": "2018-10-31T00:00:00+0000",
>    "active_to": "2018-10-31T00:00:00+0000",
>    "allowed_currencies": [
>      "USD",
>      "AUD"
>    ],
>    "allowed_merchant_brands": {
>      "categories": [
>        "10000",
>        "16000"
>      ],
>      "ids": [
>        "245e5003-58ec-540c-89a0-e148e54c2518"
>      ],
>      "subcategories": [
>        "10001",
>        "16003"
>      ]
>    },
>    "allowed_merchant_categories": [
>      "7531",
>      "7534"
>    ],
>    "allowed_merchant_countries": [
>      "US",
>      "AU"
>    ],
>    "allowed_transaction_count": "SINGLE",
>    "blocked_transaction_usages": [
>      {
>        "transaction_scope": "MAGSTRIPE",
>        "usage_scope": "INTERNATIONAL"
>      },
>      {
>        "transaction_scope": "ONLINE_TRANSACTION",
>        "usage_scope": "ALL"
>      }
>    ],
>    "transaction_limits": {
>      "cash_withdrawal_limits": [
>        {
>          "amount": 1000,
>          "interval": "PER_TRANSACTION"
>        }
>      ],
>      "currency": "USD",
>      "limits": [
>        {
>          "amount": 1000,
>          "interval": "PER_TRANSACTION"
>        }
>      ]
>    }
>  },
>  "cardholder_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",
>  "client_data": "20190817_dfelsflkj73494lksdfg9480ww",
>  "created_by": "John Smith",
>  "form_factor": "VIRTUAL",
>  "issue_to": "ORGANISATION",
>  "nick_name": "travelling",
>  "note": "This is my first card.",
>  "postal_address": {
>    "city": "Melbourne",
>    "country": "AU",
>    "line1": "44 Gillespie St",
>    "line2": "Unit 2",
>    "postcode": "3121",
>    "state": "VIC"
>  },
>  "primary_contact_details": {
>    "email": "[email protected]",
>    "full_name": "John Smith",
>    "mobile_number": "619922334321"
>  },
>  "purpose": "<string>",
>  "request_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",
>  "type": "PREPAID",
>  "metadata": {
>    "key1": "value1",
>    "key2": "value2"
>  }
>}'
Response (202 Accepted)
1{
2  "activate_on_issue": false,
3  "authorization_controls": {
4    "active_from": "2018-10-31T00:00:00+0000",
5    "active_to": "2018-10-31T00:00:00+0000",
6    "allowed_currencies": [
7      "USD",
8      "AUD"
9    ],
10    "allowed_merchant_brands": {
11      "categories": [
12        "10000",
13        "16000"
14      ],
15      "ids": [
16        "245e5003-58ec-540c-89a0-e148e54c2518"
17      ],
18      "subcategories": [
19        "10001",
20        "16003"
21      ]
22    },
23    "allowed_merchant_categories": [
24      "7531",
25      "7534"
26    ],
27    "allowed_merchant_countries": [
28      "US",
29      "AU"
30    ],
31    "allowed_transaction_count": "SINGLE",
32    "blocked_transaction_usages": [
33      {
34        "transaction_scope": "MAGSTRIPE",
35        "usage_scope": "INTERNATIONAL"
36      },
37      {
38        "transaction_scope": "ONLINE_TRANSACTION",
39        "usage_scope": "ALL"
40      }
41    ],
42    "transaction_limits": {
43      "cash_withdrawal_limits": [
44        {
45          "amount": 1000,
46          "interval": "PER_TRANSACTION"
47        }
48      ],
49      "currency": "USD",
50      "limits": [
51        {
52          "amount": 1000,
53          "interval": "PER_TRANSACTION"
54        }
55      ]
56    }
57  },
58  "brand": "visa",
59  "card_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",
60  "card_number": "************4111",
61  "card_status": "ACTIVE",
62  "cardholder_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",
63  "client_data": "20190817_dfelsflkj73494lksdfg9480ww",
64  "created_by": "<string>",
65  "form_factor": "VIRTUAL",
66  "issue_to": "ORGANISATION",
67  "name_on_card": "John Smith",
68  "nick_name": "travelling",
69  "note": "This is my first card.",
70  "postal_address": {
71    "city": "Melbourne",
72    "country": "AU",
73    "line1": "44 Gillespie St",
74    "line2": "Unit 2",
75    "postcode": "3121",
76    "state": "VIC"
77  },
78  "primary_contact_details": {
79    "email": "[email protected]",
80    "full_name": "John Smith",
81    "mobile_number": "619922334321"
82  },
83  "purpose": "BUSINESS_EXPENSES",
84  "request_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",
85  "type": "UNKNOWN",
86  "card_version": 1,
87  "all_card_versions": [
88    {
89      "card_number": "************4111",
90      "card_status": "ACTIVE",
91      "card_version": 1,
92      "created_at": "2024-01-09T00:00:00+0000"
93    }
94  ],
95  "metadata": {
96    "key1": "value1",
97    "key2": "value2"
98  },
99  "delivery_details": {
100    "delivery_mode": "MAIL",
101    "delivery_vendor": "DHL",
102    "mobile_number": "+6512345678",
103    "preferred_delivery_mode": "MAIL",
104    "status": "DISPATCHED",
105    "status_description": "The card has been printed.",
106    "tracked": true,
107    "tracking_link": "https://www.dhl.com/global-en/home/tracking/tracking-parcel.html?submit=1&tracking-id=ABCD1234",
108    "tracking_number": "ABCD1234",
109    "updated_at": "2024-01-09T00:00:00+0000"
110  }
111}
Was this section helpful?

Retrieve a Card

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

Copy for LLMView as Markdown

Retrieve Card details.

Path parameters
idrequiredstring

Unique Identifier for the card.

Response body - 200 OK
activate_on_issueboolean

Set this to true to activate the physical card when it is created. This will enable use of the card while it’s being delivered to the cardholder. Virtual cards will always be activated upon creation.

all_card_versionsarray

Contains information about all versions of a card. A version changes with change in PAN

all_card_versions.card_numberstring

Masked card number of this version

all_card_versions.card_statusstring

Card status of this version. See Card StatusDocs for definitions.

PENDING
FAILED
INACTIVE
ACTIVE
LOST
STOLEN
CLOSED
BLOCKED
EXPIRED
UNKNOWN
all_card_versions.card_versioninteger

Version Id which uniquely identifies this card version object

all_card_versions.created_atstring

Creation time of the card version.

authorization_controlsobject

Spend controls that determine the rules and restrictions to check for transaction authorizations.

authorization_controls.allowed_transaction_countstring

Specifies whether this card is a Single or Multiple Use card. Single Use means that the card can only be used for 1 successful debit transaction.

SINGLE
MULTIPLE
authorization_controls.transaction_limitsobject

Transaction limits for the card. Multiple transaction limits can be configured based on single currency. Each transaction will be checked against the limits with interval after currency conversion rate applied

authorization_controls.transaction_limits.limitsarray

Transaction limits are based on interval and amount.

If the per transaction limit is not set, the default per transaction limit amount for the selected limit currency will be used. The default per transaction amount is part of account settings. To change the default per transaction limit, please reach out to your account manager.

The account holder may be liable for any unauthorised spending on the card, so please apply limits responsibly.

authorization_controls.transaction_limits.limits.amountnumber

Transaction limit amount. This field is mandatory and must be greater than 0. Customer can set perTransaction limit up to a maximum amount (The maximum amount is part of account setting)

authorization_controls.transaction_limits.limits.intervalstring

Transaction limit interval. This field is mandatory and must be one of: PER_TRANSACTION, DAILY, WEEKLY, MONTHLY, ALL_TIME

authorization_controls.transaction_limits.cash_withdrawal_limitsarray

Cash withdrawal transaction limits are based on interval and amount.

If the daily limit is not set, the default daily limit amount for the selected limit currency will be used. The default daily limit amount is part of the account setting. To change the default daily limit amount, please reach out to your account manager.

Please note that the cash withdrawal transaction limits apply exclusively to cash withdrawals and are imposed to help manage potential liability for the account holder and for Airwallex. The account holder may be liable for any unauthorised spending on the card, so please apply the limits responsibly.

Important: This limit will only appear if you have cash withdrawals enabled. Please speak to your account manager if you would like to enable cash withdrawals.

authorization_controls.transaction_limits.cash_withdrawal_limits.amountnumber

Transaction limit amount. This field is mandatory and must be greater than 0. Customer can set perTransaction limit up to a maximum amount (The maximum amount is part of account setting)

authorization_controls.transaction_limits.cash_withdrawal_limits.intervalstring

Transaction limit interval. This field is mandatory and must be one of: PER_TRANSACTION, DAILY, WEEKLY, MONTHLY, ALL_TIME

authorization_controls.transaction_limits.currencystring

Currency for transaction limits (3-letter ISO-4217 code). Will use USD if not set. Examples of valid base currencies are USD, AUD, GBP, EUR, CNY, HKD, SGD, NZD, JPY, CAD, CHF. More currencies may be available for your account: you may query the full list by calling the Get issuing config endpoint.

authorization_controls.active_fromstring

If provided, authorizations prior to this time will be rejected.

authorization_controls.active_tostring

If provided, authorizations after this time will be rejected.

authorization_controls.allowed_currenciesarray

Allowed Currencies for transactions. Please note if this field is absent from request payload, or has a value of null or empty array [], then all transaction currencies will be allowed.

authorization_controls.allowed_merchant_brandsobject

Allowed Merchant Brands rules for transactions. Please note if this field is absent from request payload, then transactions from all merchant brands will be allowed.

authorization_controls.allowed_merchant_brands.categoriesarray

Allowed Merchant Brands Categories for transactions. These must be provided using the codes defined in the Merchant Brands Controls product pageDocs. Please note if this field is absent from request payload, or has a value of null or empty array [], then transactions from all merchant brand categories will be allowed.

authorization_controls.allowed_merchant_brands.idsarray

Allowed Merchant Brand identifiers for transactions. Please note if this field is absent from request payload, or has a value of null or empty array [], then transactions from all merchant brand ids will be allowed. You can search for Merchant Brands ids using the Merchant Brands API.

authorization_controls.allowed_merchant_brands.subcategoriesarray

Allowed Merchant Brands Subcategories for transactions. These must be provided using the codes defined in the Merchant Brands Controls product pageDocs. Please note if this field is absent from request payload, or has a value of null or empty array [], then transactions from all merchant brand subcategories will be allowed.

authorization_controls.allowed_merchant_categoriesarray

Allowed Merchant Category Codes. Please note if this field is absent from request payload, or has a value of null or empty array [], then all merchant categories will be allowed.

authorization_controls.allowed_merchant_countriesarray

Allowed Merchant Countries for transactions. Please note if this field is absent from request payload, or has a value of null or empty array [], then transactions from all merchant countries will be allowed (although some may still be blocked by our risk team).

authorization_controls.blocked_transaction_usagesarray

List of disabled transaction usages, based on transaction_scope and usage_scope values. Please note if this field is absent from request payload or has a value of null, then all transaction usages will be allowed unless a default configration is added.

You can add multiple transaction_scope and usage_scope values. The most restrictive scope(s) would apply.

authorization_controls.blocked_transaction_usages.transaction_scopestring

Types of transaction scope. It can be one of: ALL_TRANSACTIONS, ONLINE_TRANSACTION, CONTACTLESS_TRANSACTION, CONTACT_CHIP_TRANSACTION, MAGSTRIPE, CASH_WITHDRAWAL, BILL_PAYMENT, ACCOUNT_FUNDING

authorization_controls.blocked_transaction_usages.usage_scopestring

Determines if a transaction can be made domestically and/or internationally. It can be one of: ALL, INTERNATIONAL, DOMESTIC

brandstring

Card Brand

card_idstring

Unique Identifier for the card

card_numberstring

Masked card number

card_statusstring

Current card status. See Card StatusDocs for definitions.

PENDING
FAILED
INACTIVE
ACTIVE
LOST
STOLEN
CLOSED
BLOCKED
EXPIRED
UNKNOWN
card_versioninteger

Current version of the card

cardholder_idstring

The unique identifier of the cardholder this card is associated with if it is an individual card.

client_datastring

Client data which will be stored against the card record in Airwallex.

created_bystring

The creator of the card

delivery_detailsobject

Delivery detail of the card. Only available for physical cards.

delivery_details.delivery_modestring

MAIL: Delivery of the card is delivered via mail shipment. Tracking may or may not be provided. EXPRESS: Delivery of the card is tracked and delivered via express shipment. A tracking_link will always be provided.

MAIL
EXPRESS
UNKNOWN
delivery_details.delivery_vendorstring

Delivery vendor of this card.

UNKNOWN
AU_POST
EMS
HK_POST
CITY_LINK
DHL
CN_POST
PL_POST
USPS
FEDEX
delivery_details.mobile_numberstring

The mobile number for the card delivery.

delivery_details.preferred_delivery_modestring

The delivery mode customer selected when the Create Card API is called.

MAIL
EXPRESS
UNKNOWN
delivery_details.statusstring

See Delivery StatusDocs for definitions.

PENDING
PRINTED
FAILED_TO_PRINT
DISPATCHED
IN_TRANSIT
OUT_FOR_DELIVERY
DELIVERED
DELIVERY_FAILED
DELIVERY_DELAYED
UNKNOWN
delivery_details.status_descriptionstring

A brief description of the status

delivery_details.trackedboolean

Specifies if the delivery of the card is tracked. If true, a tracking link will be provided when status becomes DISPATCHED

delivery_details.tracking_numberstring

Delivery tracking number of this card.

delivery_details.updated_atstring

Last update time of the delivery details

form_factorstring

Form of the card

PHYSICAL
VIRTUAL
issue_tostring

Who the card is issued to - client or individual. A value of ORGANISATION indicates that the card will be issued to the client themselves i.e. Purchasing Card

ORGANISATION
INDIVIDUAL
metadataobject

A set of key-value pairs that can be attached to the Card. You can specify up to 20 keys, with key names up to 20 characters long and values up to 150 characters long.

name_on_cardstring

Name to be printed on card.

nick_namestring

A nick name for the card

notestring

Notes that are to be stored against the card request (for client reference)

postal_addressobject

Optional postal address of physical card delivery.

postal_address.citystring

City of address

postal_address.countrystring

ISO country code of address

postal_address.line1string

Address line 1

postal_address.postcodestring

Address postcode or ZIP code

postal_address.line2string

Address line 2

postal_address.statestring

Address state or region

primary_contact_detailsobject

Details of the primary contact of the card

primary_contact_details.emailstring

The email address of the primary contact of the new card.

primary_contact_details.full_namestring

Full name of the primary contact of the new card.

primary_contact_details.mobile_numberstring

The mobile number of the primary contact of the new card.

purposestring

The purpose of the card's usage. Only available for expense cards.

SUBSCRIPTIONS
OFFICE_SUPPLIES
MARKETING_EXPENSES
TRAVEL_EXPENSES
CLIENT_EXPENSES
TEAM_EXPENSES
ONLINE_PURCHASING
BUSINESS_EXPENSES
OTHER
request_idstring

A unique request identifier specified by the client. Requests with the same request_id will be ignored. This allows requests to be replayed if client is unsure of the outcome, e.g. due to network issues, system failures, etc. Note: Can be non-UUID as long as it is unique between requests

typestring

Card type - PREPAID, DEBIT, GOOD_FUNDS_CREDIT or DD_OTA. DD_OTA is Deferred Debit card available for OTA (Online Travel Agent) customers only in UK/Europe countries. If card type is not set, the default card type which is a part of your account setting will be used.

UNKNOWN
PREPAID
DEBIT
DD_OTA
GOOD_FUNDS_CREDIT
CREDIT
Errors
Error statusDescription
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/cards/{id}
$curl --request GET \
>  --url 'https://api.sandbox.airwallex.com/api/v1/issuing/cards/card_id' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json'
Response (200 OK)
1{
2  "activate_on_issue": false,
3  "authorization_controls": {
4    "active_from": "2018-10-31T00:00:00+0000",
5    "active_to": "2018-10-31T00:00:00+0000",
6    "allowed_currencies": [
7      "USD",
8      "AUD"
9    ],
10    "allowed_merchant_brands": {
11      "categories": [
12        "10000",
13        "16000"
14      ],
15      "ids": [
16        "245e5003-58ec-540c-89a0-e148e54c2518"
17      ],
18      "subcategories": [
19        "10001",
20        "16003"
21      ]
22    },
23    "allowed_merchant_categories": [
24      "7531",
25      "7534"
26    ],
27    "allowed_merchant_countries": [
28      "US",
29      "AU"
30    ],
31    "allowed_transaction_count": "SINGLE",
32    "blocked_transaction_usages": [
33      {
34        "transaction_scope": "MAGSTRIPE",
35        "usage_scope": "INTERNATIONAL"
36      },
37      {
38        "transaction_scope": "ONLINE_TRANSACTION",
39        "usage_scope": "ALL"
40      }
41    ],
42    "transaction_limits": {
43      "cash_withdrawal_limits": [
44        {
45          "amount": 1000,
46          "interval": "PER_TRANSACTION"
47        }
48      ],
49      "currency": "USD",
50      "limits": [
51        {
52          "amount": 1000,
53          "interval": "PER_TRANSACTION"
54        }
55      ]
56    }
57  },
58  "brand": "visa",
59  "card_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",
60  "card_number": "************4111",
61  "card_status": "ACTIVE",
62  "cardholder_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",
63  "client_data": "20190817_dfelsflkj73494lksdfg9480ww",
64  "created_by": "<string>",
65  "form_factor": "VIRTUAL",
66  "issue_to": "ORGANISATION",
67  "name_on_card": "John Smith",
68  "nick_name": "travelling",
69  "note": "This is my first card.",
70  "postal_address": {
71    "city": "Melbourne",
72    "country": "AU",
73    "line1": "44 Gillespie St",
74    "line2": "Unit 2",
75    "postcode": "3121",
76    "state": "VIC"
77  },
78  "primary_contact_details": {
79    "email": "[email protected]",
80    "full_name": "John Smith",
81    "mobile_number": "619922334321"
82  },
83  "purpose": "BUSINESS_EXPENSES",
84  "request_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",
85  "type": "UNKNOWN",
86  "card_version": 1,
87  "all_card_versions": [
88    {
89      "card_number": "************4111",
90      "card_status": "ACTIVE",
91      "card_version": 1,
92      "created_at": "2024-01-09T00:00:00+0000"
93    }
94  ],
95  "metadata": {
96    "key1": "value1",
97    "key2": "value2"
98  },
99  "delivery_details": {
100    "delivery_mode": "MAIL",
101    "delivery_vendor": "DHL",
102    "mobile_number": "+6512345678",
103    "preferred_delivery_mode": "MAIL",
104    "status": "DISPATCHED",
105    "status_description": "The card has been printed.",
106    "tracked": true,
107    "tracking_link": "https://www.dhl.com/global-en/home/tracking/tracking-parcel.html?submit=1&tracking-id=ABCD1234",
108    "tracking_number": "ABCD1234",
109    "updated_at": "2024-01-09T00:00:00+0000"
110  }
111}
Was this section helpful?

List all Cards

GET /api/v1/issuing/cards

Copy for LLMView as Markdown

Get cards issued under an account. Will default to a 30 day period unless both to and from created_at request fields are populated.

Query parameters
card_statusstring

Current card status.

PENDING
FAILED
INACTIVE
ACTIVE
LOST
STOLEN
CLOSED
BLOCKED
EXPIRED
UNKNOWN
cardholder_idstring

The id of the cardholder for the card, if it is an employee card.

from_created_atstring

Created_from_date in ISO8601 format (inclusive).

from_updated_atstring

Updated_from_date in ISO8601 format (inclusive).

nick_namestring

Will be used to return cards whose nickname exactly matches the value of this field.

page_numinteger

Page number, starts from 0.

page_sizeinteger

Number of results per page, between 10 and 200. The default is 100.

to_created_atstring

Created_to_date in ISO8601 format (inclusive).

to_updated_atstring

Updated_to_date in ISO8601 format (inclusive).

Response body - 200 OK
has_moreboolean
itemsarray
items.brandstring

Card Brand

items.card_idstring

Unique Identifier for the card

items.card_numberstring

Masked card number

items.card_statusstring

Current card status

PENDING
FAILED
INACTIVE
ACTIVE
LOST
STOLEN
CLOSED
BLOCKED
EXPIRED
UNKNOWN
items.created_atstring

Date card was created

items.cardholder_idstring

Unique Identifier for the cardholder, if this is an employee card.

items.nick_namestring

Nickname on the card.

Errors
Error statusDescription
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/cards
$curl --request GET \
>  --url 'https://api.sandbox.airwallex.com/api/v1/issuing/cards' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json'
Response (200 OK)
1{
2  "has_more": false,
3  "items": [
4    {
5      "brand": "visa",
6      "card_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",
7      "card_number": "************4111",
8      "card_status": "ACTIVE",
9      "cardholder_id": "7f0216e7-0348-4a36-9871-d1ba82c13410",
10      "created_at": "2018-10-31T00:00:00+0000",
11      "nick_name": "Travel"
12    }
13  ]
14}
Was this section helpful?

Update a Card

POST /api/v1/issuing/cards/{id}/update

Copy for LLMView as Markdown

Updates card details by setting the values of the included parameters. Parameters that are not included will be left unchanged.

Path parameters
idrequiredstring

Unique Identifier for the card.

Request body
authorization_controlsobject

Spend controls that determine the rules and restrictions to check for transaction authorizations.

authorization_controls.active_fromstring

If not provided, current value will be maintained. If provided, authorizations prior to this time will be rejected.

authorization_controls.active_tostring

If not provided, current value will be maintained. If provided, authorizations after this time will be rejected.

authorization_controls.allowed_currenciesarray

Allowed Currencies for transactions.

authorization_controls.allowed_merchant_brandsobject

Allowed Merchant Brands rules for transactions. Please note if this field is absent from request payload, then transactions from all merchant brands will be allowed.

authorization_controls.allowed_merchant_brands.categoriesarray

Allowed Merchant Brands Categories for transactions. These must be provided using the codes defined in the Merchant Brands Controls product pageDocs. Please note if this field is absent from request payload, or has a value of null or empty array [], then transactions from all merchant brand categories will be allowed.

authorization_controls.allowed_merchant_brands.idsarray

Allowed Merchant Brand identifiers for transactions. Please note if this field is absent from request payload, or has a value of null or empty array [], then transactions from all merchant brand ids will be allowed. You can search for Merchant Brands ids using the Merchant Brands API.

authorization_controls.allowed_merchant_brands.subcategoriesarray

Allowed Merchant Brands Subcategories for transactions. These must be provided using the codes defined in the Merchant Brands Controls product pageDocs. Please note if this field is absent from request payload, or has a value of null or empty array [], then transactions from all merchant brand subcategories will be allowed.

authorization_controls.allowed_merchant_categoriesarray

Allowed Merchant Category Codes. Please note if this field is absent from request payload, or has a value of null or empty array [], then all merchant categories will be allowed. Default value is [].

authorization_controls.allowed_merchant_countriesarray

Allowed Merchant Countries for transactions. Please note if this field is absent from request payload, or has a value of null or empty array [], then transactions from all merchant countries will be allowed (although some may still be blocked by our risk team).

authorization_controls.blocked_transaction_usagesarray

List of disabled transaction usages, based on transaction_scope and usage_scope values. You can add multiple transaction_scope and usage_scope values. The most restrictive scope(s) would apply.

authorization_controls.blocked_transaction_usages.transaction_scopestring

Types of transaction scope. It can be one of: ALL_TRANSACTIONS, ONLINE_TRANSACTION, CONTACTLESS_TRANSACTION, CONTACT_CHIP_TRANSACTION, MAGSTRIPE, CASH_WITHDRAWAL, BILL_PAYMENT, ACCOUNT_FUNDING.

authorization_controls.blocked_transaction_usages.usage_scopestring

Determines if a transaction can be made domestically and/or internationally. It can be one of: ALL, INTERNATIONAL, DOMESTIC.

authorization_controls.transaction_limitsobject

Transaction limits for the card. Multiple transaction limits can be configured based on single currency. Each transaction will be checked against the limits with interval after currency conversion rate applied.

authorization_controls.transaction_limits.cash_withdrawal_limitsrequiredarray

Cash withdrawal transaction limits are based on interval and amount.

If the daily limit is not set, the default daily limit amount for the selected limit currency will be used. The default daily limit amount is part of the account setting. To change the default daily limit amount, please reach out to your account manager.

Please note that the cash withdrawal transaction limits apply exclusively to cash withdrawals and are imposed to help manage potential liability for the account holder and for Airwallex. The account holder may be liable for any unauthorised spending on the card, so please apply the limits responsibly.

Important: This limit will only appear if you have cash withdrawals enabled. Please speak to your account manager if you would like to enable cash withdrawals.

authorization_controls.transaction_limits.cash_withdrawal_limits.amountrequirednumber

Transaction limit amount. This field is mandatory and must be greater than 0. Customer can set perTransaction limit up to a maximum amount (The maximum amount is part of account setting).

authorization_controls.transaction_limits.cash_withdrawal_limits.intervalrequiredstring

Transaction limit interval. This field is mandatory and must be one of: PER_TRANSACTION, DAILY, WEEKLY, MONTHLY, ALL_TIME.

authorization_controls.transaction_limits.limitsrequiredarray

Transaction limits are based on interval and amount.

If the per transaction limit is not set, the default per transaction limit amount for the selected limit currency will be used. The default per transaction amount is part of account settings. To change the default per transaction limit, please reach out to your account manager.

The account holder may be liable for any unauthorised spending on the card, so please apply limits responsibly.

authorization_controls.transaction_limits.limits.amountrequirednumber

Transaction limit amount. This field is mandatory and must be greater than 0. Customer can set perTransaction limit up to a maximum amount (The maximum amount is part of account setting).

authorization_controls.transaction_limits.limits.intervalrequiredstring

Transaction limit interval. This field is mandatory and must be one of: PER_TRANSACTION, DAILY, WEEKLY, MONTHLY, ALL_TIME.

authorization_controls.transaction_limits.currencystring

Currency for transaction limits (3-letter ISO-4217 code). Will keep current one if not provided.

card_statusstring

Card status, Allowed values are INACTIVE, ACTIVE, CLOSED.

metadataobject

A set of key-value pairs that can be attached to the Card. You can specify up to 20 keys, with key names up to 20 characters long and values up to 150 characters long.

nick_namestring

A nick name for the card.

primary_contact_detailsobject

Details of the primary contact for the card. May only be changed for cards issued to organisations.

primary_contact_details.emailstring

The email address of the primary contact of the new card.

primary_contact_details.full_namestring

Full name of the primary contact of the new card.

primary_contact_details.mobile_numberstring

The mobile number of the primary contact of the new card.

purposestring

Optional purpose for card's usage when card issueTo value is ORGANISATION. Can be one of - BUSINESS_EXPENSES, CLIENT_EXPENSES, MARKETING_EXPENSES, OFFICE_SUPPLIES, ONLINE_PURCHASING, OTHER, SUBSCRIPTIONS, TEAM_EXPENSES, TRAVEL_EXPENSES. Default value is BUSINESS_EXPENSES.

Response body - 200 OK
activate_on_issueboolean

Set this to true to activate the physical card when it is created. This will enable use of the card while it’s being delivered to the cardholder. Virtual cards will always be activated upon creation.

all_card_versionsarray

Contains information about all versions of a card. A version changes with change in PAN

all_card_versions.card_numberstring

Masked card number of this version

all_card_versions.card_statusstring

Card status of this version. See Card StatusDocs for definitions.

PENDING
FAILED
INACTIVE
ACTIVE
LOST
STOLEN
CLOSED
BLOCKED
EXPIRED
UNKNOWN
all_card_versions.card_versioninteger

Version Id which uniquely identifies this card version object

all_card_versions.created_atstring

Creation time of the card version.

authorization_controlsobject

Spend controls that determine the rules and restrictions to check for transaction authorizations.

authorization_controls.allowed_transaction_countstring

Specifies whether this card is a Single or Multiple Use card. Single Use means that the card can only be used for 1 successful debit transaction.

SINGLE
MULTIPLE
authorization_controls.transaction_limitsobject

Transaction limits for the card. Multiple transaction limits can be configured based on single currency. Each transaction will be checked against the limits with interval after currency conversion rate applied

authorization_controls.transaction_limits.limitsarray

Transaction limits are based on interval and amount.

If the per transaction limit is not set, the default per transaction limit amount for the selected limit currency will be used. The default per transaction amount is part of account settings. To change the default per transaction limit, please reach out to your account manager.

The account holder may be liable for any unauthorised spending on the card, so please apply limits responsibly.

authorization_controls.transaction_limits.limits.amountnumber

Transaction limit amount. This field is mandatory and must be greater than 0. Customer can set perTransaction limit up to a maximum amount (The maximum amount is part of account setting)

authorization_controls.transaction_limits.limits.intervalstring

Transaction limit interval. This field is mandatory and must be one of: PER_TRANSACTION, DAILY, WEEKLY, MONTHLY, ALL_TIME

authorization_controls.transaction_limits.cash_withdrawal_limitsarray

Cash withdrawal transaction limits are based on interval and amount.

If the daily limit is not set, the default daily limit amount for the selected limit currency will be used. The default daily limit amount is part of the account setting. To change the default daily limit amount, please reach out to your account manager.

Please note that the cash withdrawal transaction limits apply exclusively to cash withdrawals and are imposed to help manage potential liability for the account holder and for Airwallex. The account holder may be liable for any unauthorised spending on the card, so please apply the limits responsibly.

Important: This limit will only appear if you have cash withdrawals enabled. Please speak to your account manager if you would like to enable cash withdrawals.

authorization_controls.transaction_limits.cash_withdrawal_limits.amountnumber

Transaction limit amount. This field is mandatory and must be greater than 0. Customer can set perTransaction limit up to a maximum amount (The maximum amount is part of account setting)

authorization_controls.transaction_limits.cash_withdrawal_limits.intervalstring

Transaction limit interval. This field is mandatory and must be one of: PER_TRANSACTION, DAILY, WEEKLY, MONTHLY, ALL_TIME

authorization_controls.transaction_limits.currencystring

Currency for transaction limits (3-letter ISO-4217 code). Will use USD if not set. Examples of valid base currencies are USD, AUD, GBP, EUR, CNY, HKD, SGD, NZD, JPY, CAD, CHF. More currencies may be available for your account: you may query the full list by calling the Get issuing config endpoint.

authorization_controls.active_fromstring

If provided, authorizations prior to this time will be rejected.

authorization_controls.active_tostring

If provided, authorizations after this time will be rejected.

authorization_controls.allowed_currenciesarray

Allowed Currencies for transactions. Please note if this field is absent from request payload, or has a value of null or empty array [], then all transaction currencies will be allowed.

authorization_controls.allowed_merchant_brandsobject

Allowed Merchant Brands rules for transactions. Please note if this field is absent from request payload, then transactions from all merchant brands will be allowed.

authorization_controls.allowed_merchant_brands.categoriesarray

Allowed Merchant Brands Categories for transactions. These must be provided using the codes defined in the Merchant Brands Controls product pageDocs. Please note if this field is absent from request payload, or has a value of null or empty array [], then transactions from all merchant brand categories will be allowed.

authorization_controls.allowed_merchant_brands.idsarray

Allowed Merchant Brand identifiers for transactions. Please note if this field is absent from request payload, or has a value of null or empty array [], then transactions from all merchant brand ids will be allowed. You can search for Merchant Brands ids using the Merchant Brands API.

authorization_controls.allowed_merchant_brands.subcategoriesarray

Allowed Merchant Brands Subcategories for transactions. These must be provided using the codes defined in the Merchant Brands Controls product pageDocs. Please note if this field is absent from request payload, or has a value of null or empty array [], then transactions from all merchant brand subcategories will be allowed.

authorization_controls.allowed_merchant_categoriesarray

Allowed Merchant Category Codes. Please note if this field is absent from request payload, or has a value of null or empty array [], then all merchant categories will be allowed.

authorization_controls.allowed_merchant_countriesarray

Allowed Merchant Countries for transactions. Please note if this field is absent from request payload, or has a value of null or empty array [], then transactions from all merchant countries will be allowed (although some may still be blocked by our risk team).

authorization_controls.blocked_transaction_usagesarray

List of disabled transaction usages, based on transaction_scope and usage_scope values. Please note if this field is absent from request payload or has a value of null, then all transaction usages will be allowed unless a default configration is added.

You can add multiple transaction_scope and usage_scope values. The most restrictive scope(s) would apply.

authorization_controls.blocked_transaction_usages.transaction_scopestring

Types of transaction scope. It can be one of: ALL_TRANSACTIONS, ONLINE_TRANSACTION, CONTACTLESS_TRANSACTION, CONTACT_CHIP_TRANSACTION, MAGSTRIPE, CASH_WITHDRAWAL, BILL_PAYMENT, ACCOUNT_FUNDING

authorization_controls.blocked_transaction_usages.usage_scopestring

Determines if a transaction can be made domestically and/or internationally. It can be one of: ALL, INTERNATIONAL, DOMESTIC

brandstring

Card Brand

card_idstring

Unique Identifier for the card

card_numberstring

Masked card number

card_statusstring

Current card status. See Card StatusDocs for definitions.

PENDING
FAILED
INACTIVE
ACTIVE
LOST
STOLEN
CLOSED
BLOCKED
EXPIRED
UNKNOWN
card_versioninteger

Current version of the card

cardholder_idstring

The unique identifier of the cardholder this card is associated with if it is an individual card.

client_datastring

Client data which will be stored against the card record in Airwallex.

created_bystring

The creator of the card

delivery_detailsobject

Delivery detail of the card. Only available for physical cards.

delivery_details.delivery_modestring

MAIL: Delivery of the card is delivered via mail shipment. Tracking may or may not be provided. EXPRESS: Delivery of the card is tracked and delivered via express shipment. A tracking_link will always be provided.

MAIL
EXPRESS
UNKNOWN
delivery_details.delivery_vendorstring

Delivery vendor of this card.

UNKNOWN
AU_POST
EMS
HK_POST
CITY_LINK
DHL
CN_POST
PL_POST
USPS
FEDEX
delivery_details.mobile_numberstring

The mobile number for the card delivery.

delivery_details.preferred_delivery_modestring

The delivery mode customer selected when the Create Card API is called.

MAIL
EXPRESS
UNKNOWN
delivery_details.statusstring

See Delivery StatusDocs for definitions.

PENDING
PRINTED
FAILED_TO_PRINT
DISPATCHED
IN_TRANSIT
OUT_FOR_DELIVERY
DELIVERED
DELIVERY_FAILED
DELIVERY_DELAYED
UNKNOWN
delivery_details.status_descriptionstring

A brief description of the status

delivery_details.trackedboolean

Specifies if the delivery of the card is tracked. If true, a tracking link will be provided when status becomes DISPATCHED

delivery_details.tracking_numberstring

Delivery tracking number of this card.

delivery_details.updated_atstring

Last update time of the delivery details

form_factorstring

Form of the card

PHYSICAL
VIRTUAL
issue_tostring

Who the card is issued to - client or individual. A value of ORGANISATION indicates that the card will be issued to the client themselves i.e. Purchasing Card

ORGANISATION
INDIVIDUAL
metadataobject

A set of key-value pairs that can be attached to the Card. You can specify up to 20 keys, with key names up to 20 characters long and values up to 150 characters long.

name_on_cardstring

Name to be printed on card.

nick_namestring

A nick name for the card

notestring

Notes that are to be stored against the card request (for client reference)

postal_addressobject

Optional postal address of physical card delivery.

postal_address.citystring

City of address

postal_address.countrystring

ISO country code of address

postal_address.line1string

Address line 1

postal_address.postcodestring

Address postcode or ZIP code

postal_address.line2string

Address line 2

postal_address.statestring

Address state or region

primary_contact_detailsobject

Details of the primary contact of the card

primary_contact_details.emailstring

The email address of the primary contact of the new card.

primary_contact_details.full_namestring

Full name of the primary contact of the new card.

primary_contact_details.mobile_numberstring

The mobile number of the primary contact of the new card.

purposestring

The purpose of the card's usage. Only available for expense cards.

SUBSCRIPTIONS
OFFICE_SUPPLIES
MARKETING_EXPENSES
TRAVEL_EXPENSES
CLIENT_EXPENSES
TEAM_EXPENSES
ONLINE_PURCHASING
BUSINESS_EXPENSES
OTHER
request_idstring

A unique request identifier specified by the client. Requests with the same request_id will be ignored. This allows requests to be replayed if client is unsure of the outcome, e.g. due to network issues, system failures, etc. Note: Can be non-UUID as long as it is unique between requests

typestring

Card type - PREPAID, DEBIT, GOOD_FUNDS_CREDIT or DD_OTA. DD_OTA is Deferred Debit card available for OTA (Online Travel Agent) customers only in UK/Europe countries. If card type is not set, the default card type which is a part of your account setting will be used.

UNKNOWN
PREPAID
DEBIT
DD_OTA
GOOD_FUNDS_CREDIT
CREDIT
Errors
Error statusDescription
400

Possible errors: field_required, bad_request, invalid_argument

401

Possible errors: credentials_invalid, credentials_expired

429

Too many requests

500

Service unavailable

POST /api/v1/issuing/cards/{id}/update
$curl --request POST \
>  --url 'https://api.sandbox.airwallex.com/api/v1/issuing/cards/card_id/update' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "authorization_controls": {
>    "active_from": "2018-10-31T00:00:00+0000",
>    "active_to": "2018-10-31T00:00:00+0000",
>    "allowed_currencies": [
>      "USD",
>      "AUD"
>    ],
>    "allowed_merchant_brands": {
>      "categories": [
>        "10000",
>        "16000"
>      ],
>      "ids": [
>        "245e5003-58ec-540c-89a0-e148e54c2518"
>      ],
>      "subcategories": [
>        "10001",
>        "16003"
>      ]
>    },
>    "allowed_merchant_categories": [
>      "7531",
>      "7534"
>    ],
>    "allowed_merchant_countries": [
>      "US",
>      "AU"
>    ],
>    "blocked_transaction_usages": [
>      {
>        "transaction_scope": "MAGSTRIPE",
>        "usage_scope": "INTERNATIONAL"
>      },
>      {
>        "transaction_scope": "ONLINE_TRANSACTION",
>        "usage_scope": "ALL"
>      }
>    ],
>    "transaction_limits": {
>      "cash_withdrawal_limits": [
>        {
>          "amount": 1000,
>          "interval": "PER_TRANSACTION"
>        }
>      ],
>      "currency": "USD",
>      "limits": [
>        {
>          "amount": 1000,
>          "interval": "PER_TRANSACTION"
>        }
>      ]
>    }
>  },
>  "card_status": "INACTIVE",
>  "nick_name": "travelling",
>  "primary_contact_details": {
>    "email": "[email protected]",
>    "full_name": "John Smith",
>    "mobile_number": "619922334321"
>  },
>  "purpose": "<string>",
>  "metadata": {
>    "key1": "value1",
>    "key2": "value2"
>  }
>}'
Response (200 OK)
1{
2  "activate_on_issue": false,
3  "authorization_controls": {
4    "active_from": "2018-10-31T00:00:00+0000",
5    "active_to": "2018-10-31T00:00:00+0000",
6    "allowed_currencies": [
7      "USD",
8      "AUD"
9    ],
10    "allowed_merchant_categories": [
11      "7531",
12      "7534"
13    ],
14    "allowed_transaction_count": "SINGLE",
15    "allowed_merchant_countries": [
16      "US",
17      "AU"
18    ],
19    "blocked_transaction_usages": [
20      {
21        "transaction_scope": "MAGSTRIPE",
22        "usage_scope": "INTERNATIONAL"
23      },
24      {
25        "transaction_scope": "ONLINE_TRANSACTION",
26        "usage_scope": "ALL"
27      }
28    ],
29    "transaction_limits": {
30      "cash_withdrawal_limits": [
31        {
32          "amount": 1000,
33          "interval": "PER_TRANSACTION"
34        }
35      ],
36      "currency": "USD",
37      "limits": [
38        {
39          "amount": 1000,
40          "interval": "PER_TRANSACTION"
41        }
42      ]
43    }
44  },
45  "brand": "visa",
46  "card_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",
47  "card_number": "************4111",
48  "card_status": "ACTIVE",
49  "cardholder_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",
50  "client_data": "20190817_dfelsflkj73494lksdfg9480ww",
51  "created_by": "<string>",
52  "form_factor": "VIRTUAL",
53  "issue_to": "ORGANISATION",
54  "name_on_card": "John Smith",
55  "nick_name": "travelling",
56  "note": "This is my first card.",
57  "postal_address": {
58    "city": "Melbourne",
59    "country": "AU",
60    "line1": "44 Gillespie St",
61    "line2": "Unit 2",
62    "postcode": "3121",
63    "state": "VIC"
64  },
65  "primary_contact_details": {
66    "email": "[email protected]",
67    "full_name": "John Smith",
68    "mobile_number": "619922334321"
69  },
70  "purpose": "BUSINESS_EXPENSES",
71  "request_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",
72  "type": "UNKNOWN",
73  "card_version": 1,
74  "all_card_versions": [
75    {
76      "card_number": "************4111",
77      "card_status": "ACTIVE",
78      "card_version": 1,
79      "created_at": "2024-01-09T00:00:00+0000"
80    }
81  ],
82  "metadata": {
83    "key1": "value1",
84    "key2": "value2"
85  },
86  "delivery_details": {
87    "delivery_mode": "MAIL",
88    "delivery_vendor": "DHL",
89    "mobile_number": "+6512345678",
90    "preferred_delivery_mode": "MAIL",
91    "status": "DISPATCHED",
92    "status_description": "The card has been printed.",
93    "tracked": true,
94    "tracking_link": "https://www.dhl.com/global-en/home/tracking/tracking-parcel.html?submit=1&tracking-id=ABCD1234",
95    "tracking_number": "ABCD1234",
96    "updated_at": "2024-01-09T00:00:00+0000"
97  }
98}
Was this section helpful?

Activate a Card

POST /api/v1/issuing/cards/{id}/activate

Copy for LLMView as Markdown

Activate a physical card for card payment authorizations.

Path parameters
idrequiredstring

Unique Identifier for the card.

Response body - 202 Accepted
No response body
Errors
Error statusDescription
400

Possible errors: field_required, bad_request, invalid_argument

401

Possible errors: credentials_invalid, credentials_expired

429

Too many requests

500

Service unavailable

POST /api/v1/issuing/cards/{id}/activate
$curl --request POST \
>  --url 'https://api.sandbox.airwallex.com/api/v1/issuing/cards/card_id/activate' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json'
Was this section helpful?

Provision a Card to a Digital Wallet

POST /api/v1/issuing/cards/{id}/provision_digital_token

Copy for LLMView as Markdown

Provisions a card into a digital wallet for in-app (push) provisioning. Available only to accounts with white-label digital wallets enabled.

The request body is wallet-specific and selected by the type field. The interactive form shows a single body shape, so the per-type request bodies are documented here:

apple_pay (Apple Wallet / PassKit provisioning):

  • device_certs (array): device certificate chain, leaf certificate first
  • nonce_signature (string): signature over the nonce
  • nonce (string): one-time nonce

google_pay (Google Pay provisioning):

  • device_id (string): stable device identifier from the Google Pay SDK
  • client_customer_id (string): wallet account holder identifier

samsung_pay (Samsung Pay provisioning):

  • device_id (string): stable device identifier from the Samsung Pay SDK
  • client_customer_id (string): wallet account holder identifier
Path parameters
idrequiredstring

Unique Identifier for the card.

Request body
typerequiredstring

Digital wallet type.

apple_pay
google_pay
samsung_pay
client_customer_idstring

Required when type is google_pay or samsung_pay. Identifier for the wallet account holder, provided by the wallet SDK.

device_certsarray

Required when type is apple_pay. Device certificate chain from the Apple Wallet (PassKit) provisioning request, leaf certificate first.

device_idstring

Required when type is google_pay or samsung_pay. Stable device identifier provided by the wallet SDK.

noncestring

Required when type is apple_pay. One-time nonce supplied by Apple PassKit.

nonce_signaturestring

Required when type is apple_pay. Signature over the nonce, supplied by Apple PassKit.

server_session_idstring

Optional. Used for push provisioning with Google Pay.

Response body - 200 OK
activation_datastring

Present when type is apple_pay. Activation data to return to Apple PassKit.

card_idstring

Identifier of the provisioned card.

card_typestring

Present when type is samsung_pay. Card network / type.

enc_addressstring

Present when type is google_pay, when available. Encrypted billing address.

encrypted_pass_datastring

Present when type is apple_pay. Encrypted pass data to return to Apple PassKit to complete provisioning.

ephemeral_public_keystring

Present when type is apple_pay. Ephemeral public key to return to Apple PassKit.

expiration_dateobject

Present when type is google_pay. Expiration date of the provisioned token.

expiration_date.monthstring

Expiry month of the provisioned token.

expiration_date.yearstring

Expiry year of the provisioned token.

google_opaque_payment_cardstring

Present when type is google_pay. Used for push provisioning.

last4string

Present when type is google_pay or samsung_pay. Last four digits of the tokenized card.

opaque_payment_cardstring

Present when type is google_pay or samsung_pay. Opaque payment card payload to pass to the wallet SDK.

vcard_idstring

Present when type is samsung_pay.

Errors
Error statusDescription
400

Possible errors: field_required, bad_request, invalid_argument

401

Possible errors: credentials_invalid, credentials_expired

429

Too many requests

500

Service unavailable

POST /api/v1/issuing/cards/{id}/provision_digital_token
$curl --request POST \
>  --url 'https://api.sandbox.airwallex.com/api/v1/issuing/cards/card_id/provision_digital_token' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "type": "apple_pay",
>  "device_certs": [],
>  "nonce": "<string>",
>  "nonce_signature": "<string>"
>}'
Response (200 OK)
1{
2  "card_id": "<string>",
3  "activation_data": "<string>",
4  "encrypted_pass_data": "<string>",
5  "ephemeral_public_key": "<string>"
6}
Was this section helpful?

List all Sensitive Card Details

GET /api/v1/issuing/cards/{id}/details

Copy for LLMView as Markdown

Get sensitive card information for virtual cards. This endpoint will only return data for active cards.

Path parameters
idrequiredstring

Unique Identifier for the card.

Response body - 200 OK
card_numberstring

Card Number

cvvstring

Card Verification Value

expiry_monthinteger

Card Expiry Month

expiry_yearinteger

Card Expiry Year

name_on_cardstring

Name printed on card

Errors
Error statusDescription
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/cards/{id}/details
$curl --request GET \
>  --url 'https://api.sandbox.airwallex.com/api/v1/issuing/cards/card_id/details' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json'
Response (200 OK)
1{
2  "card_number": "4111111111111111",
3  "cvv": "123",
4  "expiry_month": 1,
5  "expiry_year": 2022,
6  "name_on_card": "John Smith"
7}
Was this section helpful?

List all Card Remaining Limits

GET /api/v1/issuing/cards/{id}/limits

Copy for LLMView as Markdown

Retrieve remaining limits of a card.

Path parameters
idrequiredstring

Unique Identifier for the card.

Response body - 200 OK
cash_withdrawal_limitsarray

Remaining Cash Withdrawal Limits for Intervals.

cash_withdrawal_limits.amountnumber

Transaction limit amount.

cash_withdrawal_limits.intervalstring

Transaction limit interval. One of: PER_TRANSACTION, DAILY, WEEKLY, MONTHLY, ALL_TIME

cash_withdrawal_limits.remainingnumber

Remaining amount of transaction limit for that interval. Refunds are always restored to active limits (each refund will increase the limit balance). Please check product doc for more details.

currencystring

Currency of transaction limits (3-letter ISO-4217 code).

limitsarray

Remaining limits for Intervals.

limits.amountnumber

Transaction limit amount.

limits.intervalstring

Transaction limit interval. One of: PER_TRANSACTION, DAILY, WEEKLY, MONTHLY, ALL_TIME

limits.remainingnumber

Remaining amount of transaction limit for that interval. Refunds are always restored to active limits (each refund will increase the limit balance). Please check product doc for more details.

Errors
Error statusDescription
401

Possible errors: credentials_invalid, credentials_expired

429

Too many requests

500

Service unavailable

GET /api/v1/issuing/cards/{id}/limits
$curl --request GET \
>  --url 'https://api.sandbox.airwallex.com/api/v1/issuing/cards/card_id/limits' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json'
Response (200 OK)
1{
2  "cash_withdrawal_limits": [
3    {
4      "amount": 1000,
5      "interval": "PER_TRANSACTION",
6      "remaining": 1000
7    }
8  ],
9  "currency": "USD",
10  "limits": [
11    {
12      "amount": 1000,
13      "interval": "PER_TRANSACTION",
14      "remaining": 1000
15    }
16  ]
17}
Was this section helpful?