Cards - Airwallex API

Search documentation

Ask Kai

Ask Kai

Cards

Copy for LLMView as Markdown

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

Please note, this API version is incompatible with any Airwallex Business Account Products such as "Borderless Cards" or "Expense Management" via Airwallex web or mobile applications. If you're using any of these products, please use API version 2024-02-22. Contact your account manager for more information and to verify compatibility.

POST /api/v1/issuing/cards/createCreate a Card GET /api/v1/issuing/cards/{id}Retrieve a Card GET /api/v1/issuing/cardsList all Cards POST /api/v1/issuing/cards/{id}/updateUpdate a Card POST /api/v1/issuing/cards/{id}/activateActivate a Card POST /api/v1/issuing/cards/{id}/provision_digital_tokenProvision a Card to a Digital Wallet GET /api/v1/issuing/cards/{id}/detailsList all Sensitive Card Details GET /api/v1/issuing/cards/{id}/limitsList all Card Remaining Limits

issuing.3ds_notification.stepup_otpA transaction requiring 3DS OTP has occurred.

issuing.card.activeCard is active.

issuing.card.blockedCard Blocked.

issuing.card.closedCard Closed.

issuing.card.expiredCard Expired.

issuing.card.failedFailed to create card.

issuing.card.inactiveCard Inactive.

issuing.card.lostCard Lost.

issuing.card.low_remaining_transaction_limitCard low remaining transaction limit.

issuing.card.modifiedThe card has been modified.

issuing.card.pendingCard is pending creation.

issuing.card.stolenCard stolen.

issuing.card_notification.createdA card has been created.

issuing.card_notification.physical_activatedA physical card has been activated.

issuing.digital_wallet_notification.abandoned_provisioningA digital wallet token has been abandoned during setup.

issuing.digital_wallet_notification.payment_reminderA digital wallet token has not been used for an extended period.

issuing.digital_wallet_notification.token_activatedA digital wallet token has been activated.

issuing.digital_wallet_notification.token_activated_smsA digital wallet token has been activated (SMS for EMEA).

issuing.digital_wallet_notification.token_provisioning_otpA digital wallet token provisioning OTP request has occurred.

issuing.digital_wallet_notification.wallet_availableA digital wallet has become available for a card.

issuing.reissue.succeededA single card has been renewed successfully.

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).

Access:Scoped API keysOAuth scopesOn behalf of

Scoped API key permissions

IssuingCardsWrite

OAuth scopes

issuing.card:write

On behalf of

Supports x-on-behalf-of header

Request body

authorization_controlsrequiredobject

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

Show child attributes

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.

Hide possible values

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.

Show child attributes

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.

Show child attributes

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, QUARTERLY, YEARLY, 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.

Show child attributes

authorization_controls.transaction_limits.cash_withdrawal_limits.amountrequirednumber

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, QUARTERLY, YEARLY, 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.

Show child attributes

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.

Show child attributes

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.

cardholder_idrequiredstring

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

created_byrequiredstring

Full legal name of user requesting new card.

form_factorrequiredstring

Form of the card - PHYSICAL or VIRTUAL.

is_personalizedrequiredboolean

Determines whether the card should be assigned to a singular individual or to the business with multiple cardholders who are authorized to use the card. Note - only personalized cards can be created as physical and added to digital wallet providers.

programrequiredobject

Card program.

Show child attributes

program.purposerequiredstring

COMMERCIAL: A card used for business purposes backed by funding belonging to a business.

CONSUMER: A card used for personal purposes backed by funding belonging to an individual.

program.binstring

Optional 6- or 8-digit network BIN. If provided, the requested BIN is used only if it is active, mapped to your program, and compatible with the card. Otherwise, the request is rejected with an ineligible_bin error. If omitted, Airwallex selects an eligible BIN automatically. Values that are not 6 or 8 digits return invalid_bin_format. This field is available only to accounts enabled for BIN selection. Contact your Airwallex Account Manager to request access.

program.interchange_percentstring

Interchange percent of the card - This is only available for sub_type="B2B_TRAVEL" cards. Interchange can vary from 0.8 to 1.9, with increments of 0.1.

program.sub_typestring

Sub type of the program - This is used for specific products under the defined program types. e.g B2B_TRAVEL which designates BINs for travel use cases (E.g OTAs).

program.typestring

Card type - PREPAID, DEBIT, CREDIT or DEFERRED_DEBIT. DEFERRED_DEBIT 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.

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.

additional_cardholder_idsarray

The IDs of additional cardholders to associate this card with. Only valid if is_personalized is false.

alert_settingsobject

Contains alert configuration settings for the card.

Show child attributes

alert_settings.low_remaining_transaction_limitobject

Configures an alert for when the remaining spending limit dips below a specified percentage. When enabled, a webhook notification will be triggered if the remaining limit falls below the defined threshold. Note that:

Show child attributes

alert_settings.low_remaining_transaction_limit.enabledrequiredboolean

Indicates whether the alert is active.

alert_settings.low_remaining_transaction_limit.percentrequiredinteger

Specifies the percentage threshold for the alert.

auto_close_datestring

If provided, the card is automatically closed at the start of the specified day (00:00 GMT). The date must be in the format YYYY-MM-DD and must be at least 1 day and no more than 5 years after the card is created. If not provided, the card is not automatically closed and follows the standard expiry and reissue behavior.

brandstring

Scheme for Issuance. Default VISA.

client_datastring

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

delivery_detailsobject

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

Show child attributes

delivery_details.mobile_numberstring

Optional mobile number for physical card delivery in E.164 format (e.g., +6512345678). Defaults to the cardholder's registered number if not provided. Required for EXPRESS delivery or when the destination country is China.

delivery_details.preferred_delivery_modestring

Customizable options that customers can specify for physical card delivery. The requested delivery mode will be provided on a best-effort basis. MAIL: Delivery of the card is delivered via mail shipment. EXPRESS: Delivery of the card is tracked and delivered via express shipment.

funding_source_idstring

A unique identifier that links a card to its designated funding source. This unique identifier determines which funding source will be accessed for the deduction of funds during transactions. The funding_source_id can be retrieved from the client's account manager. If funding_source_id is not provided, the default funding source would be the account's wallet.

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.

Show child attributes

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.

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.

Response body - 202 Accepted

activate_on_issueboolean

additional_cardholder_idsarray

The ID of additional cardholders of this card. Only valid if is_personalized is false.

alert_settingsobject

Contains alert configuration settings for the card.

Show child attributes

alert_settings.low_remaining_transaction_limitobject

Show child attributes

alert_settings.low_remaining_transaction_limit.enabledboolean

Indicates whether the alert is active.

alert_settings.low_remaining_transaction_limit.percentinteger

Specifies the percentage threshold for the alert.

all_card_versionsarray

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

Show child attributes

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.

Hide possible values

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.

Show child attributes

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.

Hide possible values

SINGLE

MULTIPLE

authorization_controls.transaction_limitsobject

Show child attributes

authorization_controls.transaction_limits.limitsarray

Transaction limits are based on interval and amount.

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

Show child attributes

authorization_controls.transaction_limits.limits.amountnumber

authorization_controls.transaction_limits.limits.intervalstring

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

authorization_controls.transaction_limits.cash_withdrawal_limitsarray

Cash withdrawal transaction limits are based on interval and amount.

Show child attributes

authorization_controls.transaction_limits.cash_withdrawal_limits.amountnumber

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, QUARTERLY, YEARLY, ALL_TIME.

authorization_controls.transaction_limits.currencystring

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

authorization_controls.allowed_merchant_brandsobject

Show child attributes

authorization_controls.allowed_merchant_brands.categoriesarray

authorization_controls.allowed_merchant_brands.idsarray

authorization_controls.allowed_merchant_brands.subcategoriesarray

authorization_controls.allowed_merchant_categoriesarray

authorization_controls.allowed_merchant_countriesarray

authorization_controls.blocked_transaction_usagesarray

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

Show child attributes

authorization_controls.blocked_transaction_usages.transaction_scopestring

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.

auto_close_datestring

The date on which the card is automatically closed, at the start of that day (00:00 GMT). The date is in the format YYYY-MM-DD. Returns null if no automatic closure is scheduled.

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.

Hide possible values

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_atstring

Creation time of the card.

created_bystring

The creator of the card.

delivery_detailsobject

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

Show child attributes

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.

Hide possible values

MAIL

EXPRESS

UNKNOWN

delivery_details.delivery_vendorstring

Delivery vendor of this card.

Hide possible values

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.

Hide possible values

MAIL

EXPRESS

UNKNOWN

delivery_details.statusstring

See Delivery StatusDocs for definitions.

Hide possible values

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_linkstring

Tracking link of the card.

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.

Hide possible values

PHYSICAL

VIRTUAL

funding_source_idstring

is_personalizedboolean

metadataobject

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.

Show child attributes

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.

Show child attributes

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.

programobject

Card program.

Show child attributes

program.interchange_percentstring

Interchange percent of the card - This is only available for sub_type="B2B_TRAVEL" cards. Interchange can vary from 0.8 to 1.9, with increments of 0.1.

program.purposestring

Hide possible values

CONSUMER

A card used for personal purposes backed by funding belonging to an individual.

COMMERCIAL

A card used for business purposes backed by funding belonging to a business.

program.sub_typestring

Hide possible values

GOOD_FUNDS_CREDIT

B2B_TRAVEL

UNKNOWN

program.typestring

Hide possible values

UNKNOWN

DEBIT

PREPAID

CREDIT

DEFERRED_DEBIT

purposestring

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

Hide possible values

SUBSCRIPTIONS

OFFICE_SUPPLIES

MARKETING_EXPENSES

TRAVEL_EXPENSES

CLIENT_EXPENSES

TEAM_EXPENSES

ONLINE_PURCHASING

BUSINESS_EXPENSES

OTHER

request_idstring

updated_atstring

Last update time of the card.

Errors

Error status Description
400 Possible errors: field_required, bad_request, invalid_argument, invalid_bin_format, ineligible_bin, invalid_card_profile
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,
>  "additional_cardholder_ids": [\
>    "7f687fe6-dcf4-4462-92fa-80335301d9d2",\
>    "b0a1b145-4853-4456-b4b3-d690c7f3535c"\
>  ],
>  "auto_close_date": "2027-01-31",
>  "alert_settings": {
>    "low_remaining_transaction_limit": {
>      "enabled": false,
>      "percent": 10
>    }
>  },
>  "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"\
>        }\
>      ]
>    }
>  },
>  "brand": "VISA",
>  "cardholder_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",
>  "client_data": "20190817_dfelsflkj73494lksdfg9480ww",
>  "created_by": "John Smith",
>  "delivery_details": {
>    "mobile_number": "+6512345678",
>    "preferred_delivery_mode": "MAIL"
>  },
>  "form_factor": "VIRTUAL",
>  "funding_source_id": "6682111f-cb4a-47ce-8e95-5abcc5394727",
>  "is_personalized": true,
>  "metadata": {
>    "key1": "value1",
>    "key2": "value2"
>  },
>  "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"
>  },
>  "program": {
>    "interchange_percent": "1.0",
>    "purpose": "COMMERCIAL",
>    "sub_type": "GOOD_FUNDS_CREDIT",
>    "type": "PREPAID"
>  },
>  "purpose": "<string>",
>  "request_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2"
>}'

Response (202 Accepted)

1{
2  "activate_on_issue": false,
3  "additional_cardholder_ids": [\
4    "7f687fe6-dcf4-4462-92fa-80335301d9d2",\
5    "b0a1b145-4853-4456-b4b3-d690c7f3535c"\
6  ],
7  "auto_close_date": "2027-01-31",
8  "alert_settings": {
9    "low_remaining_transaction_limit": {
10      "enabled": false,
11      "percent": 10
12    }
13  },
14  "all_card_versions": [\
15    {\
16      "card_number": "************4111",\
17      "card_status": "ACTIVE",\
18      "card_version": 1,\
19      "created_at": "2024-01-09T00:00:00+0000"\
20    }\
21  ],
22  "authorization_controls": {
23    "active_from": "2018-10-31T00:00:00+0000",
24    "active_to": "2018-10-31T00:00:00+0000",
25    "allowed_currencies": [\
26      "USD",\
27      "AUD"\
28    ],
29    "allowed_merchant_brands": {
30      "categories": [\
31        "10000",\
32        "16000"\
33      ],
34      "ids": [\
35        "245e5003-58ec-540c-89a0-e148e54c2518"\
36      ],
37      "subcategories": [\
38        "10001",\
39        "16003"\
40      ]
41    },
42    "allowed_merchant_categories": [\
43      "7531",\
44      "7534"\
45    ],
46    "allowed_merchant_countries": [\
47      "US",\
48      "AU"\
49    ],
50    "allowed_transaction_count": "SINGLE",
51    "blocked_transaction_usages": [\
52      {\
53        "transaction_scope": "MAGSTRIPE",\
54        "usage_scope": "INTERNATIONAL"\
55      },\
56      {\
57        "transaction_scope": "ONLINE_TRANSACTION",\
58        "usage_scope": "ALL"\
59      }\
60    ],
61    "transaction_limits": {
62      "cash_withdrawal_limits": [\
63        {\
64          "amount": 1000,\
65          "interval": "PER_TRANSACTION"\
66        }\
67      ],
68      "currency": "USD",
69      "limits": [\
70        {\
71          "amount": 1000,\
72          "interval": "PER_TRANSACTION"\
73        }\
74      ]
75    }
76  },
77  "brand": "visa",
78  "card_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",
79  "card_number": "************4111",
80  "card_status": "ACTIVE",
81  "card_version": 1,
82  "cardholder_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",
83  "client_data": "20190817_dfelsflkj73494lksdfg9480ww",
84  "created_at": "2024-01-09T00:00:00+0000",
85  "created_by": "<string>",
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  "form_factor": "VIRTUAL",
99  "funding_source_id": "6682111f-cb4a-47ce-8e95-5abcc5394727",
100  "is_personalized": true,
101  "issue_to": "ORGANISATION",
102  "metadata": {
103    "key1": "value1",
104    "key2": "value2"
105  },
106  "name_on_card": "John Smith",
107  "nick_name": "travelling",
108  "note": "This is my first card.",
109  "postal_address": {
110    "city": "Melbourne",
111    "country": "AU",
112    "line1": "44 Gillespie St",
113    "line2": "Unit 2",
114    "postcode": "3121",
115    "state": "VIC"
116  },
117  "primary_contact_details": {
118    "email": "john@example.com",
119    "full_name": "John Smith",
120    "mobile_number": "619922334321"
121  },
122  "program": {
123    "interchange_percent": "1.0",
124    "purpose": "COMMERCIAL",
125    "sub_type": "GOOD_FUNDS_CREDIT",
126    "type": "PREPAID"
127  },
128  "purpose": "BUSINESS_EXPENSES",
129  "request_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",
130  "updated_at": "2024-01-09T00:00:00+0000"
131}

Was this section helpful?

YesNo

Retrieve a Card

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

Copy for LLMView as Markdown

Retrieve Card details.

Access:Scoped API keysOAuth scopesOn behalf of

Scoped API key permissions

IssuingCardsRead

OAuth scopes

issuing.card:read

On behalf of

Supports x-on-behalf-of header

Path parameters

idrequiredstring

Unique Identifier for the card.

Response body - 200 OK

activate_on_issueboolean

additional_cardholder_idsarray

The ID of additional cardholders of this card. Only valid if is_personalized is false.

alert_settingsobject

Contains alert configuration settings for the card.

Show child attributes

alert_settings.low_remaining_transaction_limitobject

Show child attributes

alert_settings.low_remaining_transaction_limit.enabledboolean

Indicates whether the alert is active.

alert_settings.low_remaining_transaction_limit.percentinteger

Specifies the percentage threshold for the alert.

all_card_versionsarray

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

Show child attributes

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.

Hide possible values

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.

Show child attributes

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.

Hide possible values

SINGLE

MULTIPLE

authorization_controls.transaction_limitsobject

Show child attributes

authorization_controls.transaction_limits.limitsarray

Transaction limits are based on interval and amount.

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

Show child attributes

authorization_controls.transaction_limits.limits.amountnumber

authorization_controls.transaction_limits.limits.intervalstring

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

authorization_controls.transaction_limits.cash_withdrawal_limitsarray

Cash withdrawal transaction limits are based on interval and amount.

Show child attributes

authorization_controls.transaction_limits.cash_withdrawal_limits.amountnumber

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, QUARTERLY, YEARLY, ALL_TIME.

authorization_controls.transaction_limits.currencystring

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

authorization_controls.allowed_merchant_brandsobject

Show child attributes

authorization_controls.allowed_merchant_brands.categoriesarray

authorization_controls.allowed_merchant_brands.idsarray

authorization_controls.allowed_merchant_brands.subcategoriesarray

authorization_controls.allowed_merchant_categoriesarray

authorization_controls.allowed_merchant_countriesarray

authorization_controls.blocked_transaction_usagesarray

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

Show child attributes

authorization_controls.blocked_transaction_usages.transaction_scopestring

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.

auto_close_datestring

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.

Hide possible values

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_atstring

Creation time of the card.

created_bystring

The creator of the card.

delivery_detailsobject

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

Show child attributes

delivery_details.delivery_modestring

Hide possible values

MAIL

EXPRESS

UNKNOWN

delivery_details.delivery_vendorstring

Delivery vendor of this card.

Hide possible values

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.

Hide possible values

MAIL

EXPRESS

UNKNOWN

delivery_details.statusstring

See Delivery StatusDocs for definitions.

Hide possible values

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_linkstring

Tracking link of the card.

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.

Hide possible values

PHYSICAL

VIRTUAL

funding_source_idstring

is_personalizedboolean

metadataobject

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.

Show child attributes

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.

Show child attributes

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.

programobject

Card program.

Show child attributes

program.interchange_percentstring

Interchange percent of the card - This is only available for sub_type="B2B_TRAVEL" cards. Interchange can vary from 0.8 to 1.9, with increments of 0.1.

program.purposestring

Hide possible values

CONSUMER

A card used for personal purposes backed by funding belonging to an individual.

COMMERCIAL

A card used for business purposes backed by funding belonging to a business.

program.sub_typestring

Hide possible values

GOOD_FUNDS_CREDIT

B2B_TRAVEL

UNKNOWN

program.typestring

Hide possible values

UNKNOWN

DEBIT

PREPAID

CREDIT

DEFERRED_DEBIT

purposestring

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

Hide possible values

SUBSCRIPTIONS

OFFICE_SUPPLIES

MARKETING_EXPENSES

TRAVEL_EXPENSES

CLIENT_EXPENSES

TEAM_EXPENSES

ONLINE_PURCHASING

BUSINESS_EXPENSES

OTHER

request_idstring

updated_atstring

Last update time of the card.

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/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)

Was this section helpful?

YesNo

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.

Access:Scoped API keysOAuth scopesOn behalf of

Scoped API key permissions

IssuingCardsRead

OAuth scopes

issuing.card:read

On behalf of

Supports x-on-behalf-of header

Query parameters

card_statusstring

Current card status

One of PENDING, FAILED, INACTIVE, ACTIVE, LOST, STOLEN, CLOSED, BLOCKED, EXPIRED.

Hide possible values

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

Show child attributes

items.brandstring

Card Brand.

items.card_idstring

Unique Identifier for the card.

items.card_numberstring

Masked card number.

items.card_statusstring

Current card status, one of:

Hide possible values

PENDING

FAILED

INACTIVE

ACTIVE

LOST

STOLEN

CLOSED

BLOCKED

EXPIRED

UNKNOWN

items.created_atstring

Date card was created.

items.additional_cardholder_idsarray

Unique Identifiers for additional cardholders.

items.cardholder_idstring

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

items.nick_namestring

Nickname on the card.

items.updated_atstring

Last update time of the card.

Errors

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      "additional_cardholder_ids": [\
6        "7f0216e7-0348-4a36-9871-d1ba82c13410",\
7        "b0a1b145-4853-4456-b4b3-d690c7f3535c"\
8      ],\
9      "brand": "visa",\
10      "card_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",\
11      "card_number": "************4111",\
12      "card_status": "ACTIVE",\
13      "cardholder_id": "7f0216e7-0348-4a36-9871-d1ba82c13410",\
14      "created_at": "2018-10-31T00:00:00+0000",\
15      "nick_name": "Travel",\
16      "updated_at": "2024-01-09T00:00:00+0000"\
17    }\
18  ]
19}

Was this section helpful?

YesNo

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.

Access:Scoped API keysOAuth scopesOn behalf of

Scoped API key permissions

IssuingCardsWrite

OAuth scopes

issuing.card:write

On behalf of

Supports x-on-behalf-of header

Path parameters

idrequiredstring

Unique Identifier for the card.

Request body

additional_cardholder_idsarray

The IDs of additional cardholders to associate this card with. Only valid if is_personalized is false.

alert_settingsobject

Contains alert configuration settings for the card.

Show child attributes

alert_settings.low_remaining_transaction_limitobject

Show child attributes

alert_settings.low_remaining_transaction_limit.enabledrequiredboolean

Indicates whether the alert is active.

alert_settings.low_remaining_transaction_limit.percentrequiredinteger

Specifies the percentage threshold for the alert.

authorization_controlsobject

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

Show child attributes

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

Show child attributes

authorization_controls.allowed_merchant_brands.categoriesarray

authorization_controls.allowed_merchant_brands.idsarray

authorization_controls.allowed_merchant_brands.subcategoriesarray

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

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.

Show child attributes

authorization_controls.blocked_transaction_usages.transaction_scopestring

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

Show child attributes

authorization_controls.transaction_limits.cash_withdrawal_limitsrequiredarray

Cash withdrawal transaction limits are based on interval and amount.

Show child attributes

authorization_controls.transaction_limits.cash_withdrawal_limits.amountrequirednumber

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, QUARTERLY, YEARLY, ALL_TIME.

authorization_controls.transaction_limits.limitsrequiredarray

Transaction limits are based on interval and amount.

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

Show child attributes

authorization_controls.transaction_limits.limits.amountrequirednumber

authorization_controls.transaction_limits.limits.intervalrequiredstring

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

authorization_controls.transaction_limits.currencystring

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

auto_close_datestring

If provided, the card is automatically closed at the start of the specified day (00:00 GMT). The date must be in the format YYYY-MM-DD and must be at least 1 day and no more than 5 years after the update request is made. Set the field to null to clear the scheduled closure. If not provided, the current value is maintained.

card_statusstring

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

cardholder_idstring

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

metadataobject

nick_namestring

A nick name for the 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

additional_cardholder_idsarray

The ID of additional cardholders of this card. Only valid if is_personalized is false.

alert_settingsobject

Contains alert configuration settings for the card.

Show child attributes

alert_settings.low_remaining_transaction_limitobject

Show child attributes

alert_settings.low_remaining_transaction_limit.enabledboolean

Indicates whether the alert is active.

alert_settings.low_remaining_transaction_limit.percentinteger

Specifies the percentage threshold for the alert.

all_card_versionsarray

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

Show child attributes

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.

Hide possible values

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.

Show child attributes

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.

Hide possible values

SINGLE

MULTIPLE

authorization_controls.transaction_limitsobject

Show child attributes

authorization_controls.transaction_limits.limitsarray

Transaction limits are based on interval and amount.

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

Show child attributes

authorization_controls.transaction_limits.limits.amountnumber

authorization_controls.transaction_limits.limits.intervalstring

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

authorization_controls.transaction_limits.cash_withdrawal_limitsarray

Cash withdrawal transaction limits are based on interval and amount.

Show child attributes

authorization_controls.transaction_limits.cash_withdrawal_limits.amountnumber

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, QUARTERLY, YEARLY, ALL_TIME.

authorization_controls.transaction_limits.currencystring

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

authorization_controls.allowed_merchant_brandsobject

Show child attributes

authorization_controls.allowed_merchant_brands.categoriesarray

authorization_controls.allowed_merchant_brands.idsarray

authorization_controls.allowed_merchant_brands.subcategoriesarray

authorization_controls.allowed_merchant_categoriesarray

authorization_controls.allowed_merchant_countriesarray

authorization_controls.blocked_transaction_usagesarray

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

Show child attributes

authorization_controls.blocked_transaction_usages.transaction_scopestring

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.

auto_close_datestring

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.

Hide possible values

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_atstring

Creation time of the card.

created_bystring

The creator of the card.

delivery_detailsobject

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

Show child attributes

delivery_details.delivery_modestring

Hide possible values

MAIL

EXPRESS

UNKNOWN

delivery_details.delivery_vendorstring

Delivery vendor of this card.

Hide possible values

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.

Hide possible values

MAIL

EXPRESS

UNKNOWN

delivery_details.statusstring

See Delivery StatusDocs for definitions.

Hide possible values

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_linkstring

Tracking link of the card.

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.

Hide possible values

PHYSICAL

VIRTUAL

funding_source_idstring

is_personalizedboolean

metadataobject

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.

Show child attributes

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.

Show child attributes

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.

programobject

Card program.

Show child attributes

program.interchange_percentstring

Interchange percent of the card - This is only available for sub_type="B2B_TRAVEL" cards. Interchange can vary from 0.8 to 1.9, with increments of 0.1.

program.purposestring

Hide possible values

CONSUMER

A card used for personal purposes backed by funding belonging to an individual.

COMMERCIAL

A card used for business purposes backed by funding belonging to a business.

program.sub_typestring

Hide possible values

GOOD_FUNDS_CREDIT

B2B_TRAVEL

UNKNOWN

program.typestring

Hide possible values

UNKNOWN

DEBIT

PREPAID

CREDIT

DEFERRED_DEBIT

purposestring

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

Hide possible values

SUBSCRIPTIONS

OFFICE_SUPPLIES

MARKETING_EXPENSES

TRAVEL_EXPENSES

CLIENT_EXPENSES

TEAM_EXPENSES

ONLINE_PURCHASING

BUSINESS_EXPENSES

OTHER

request_idstring

updated_atstring

Last update time of the card.

Errors

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 '{
>  "additional_cardholder_ids": [\
>    "7f687fe6-dcf4-4462-92fa-80335301d9d2",\
>    "b0a1b145-4853-4456-b4b3-d690c7f3535c"\
>  ],
>  "auto_close_date": "2027-01-31",
>  "alert_settings": {
>    "low_remaining_transaction_limit": {
>      "enabled": false,
>      "percent": 10
>    }
>  },
>  "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",
>  "cardholder_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",
>  "metadata": {
>    "key1": "value1",
>    "key2": "value2"
>  },
>  "nick_name": "travelling",
>  "purpose": "<string>"
>}'

Response (200 OK)

Was this section helpful?

YesNo

Activate a Card

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

Copy for LLMView as Markdown

Activate a physical card for card payment authorizations.

Access:Scoped API keysOAuth scopesOn behalf of

Scoped API key permissions

IssuingCardsWrite

OAuth scopes

issuing.card:write

On behalf of

Supports x-on-behalf-of header

Path parameters

idrequiredstring

Unique Identifier for the card.

Response body - 202 Accepted

No response body

Errors

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?

YesNo

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):

google_pay (Google Pay provisioning):

samsung_pay (Samsung Pay provisioning):

Access:Scoped API keysOAuth scopesOn behalf of

Scoped API key permissions

IssuingCardsWrite

OAuth scopes

issuing.card:write

On behalf of

Supports x-on-behalf-of header

Path parameters

idrequiredstring

Unique Identifier for the card.

Request body

typerequiredstring

Digital wallet type.

Hide possible values

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.

Show child attributes

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

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?

YesNo

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.

Access:Scoped API keysOAuth scopesOn behalf of

Scoped API key permissions

IssuingCardsRead

OAuth scopes

issuing.card:read

On behalf of

Supports x-on-behalf-of header

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

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?

YesNo

List all Card Remaining Limits

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

Copy for LLMView as Markdown

Retrieve remaining limits of a card.

Access:Scoped API keysOAuth scopesOn behalf of

Scoped API key permissions

IssuingCardsRead

OAuth scopes

issuing.card:read

On behalf of

Supports x-on-behalf-of header

Path parameters

idrequiredstring

Unique Identifier for the card.

Response body - 200 OK

cash_withdrawal_limitsarray

Remaining Cash Withdrawal Limits for Intervals.

Show child attributes

cash_withdrawal_limits.amountnumber

Transaction limit amount.

cash_withdrawal_limits.intervalstring

Transaction limit interval. One of: PER_TRANSACTION, DAILY, WEEKLY, MONTHLY, QUARTERLY, YEARLY, 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.

Show child attributes

limits.amountnumber

Transaction limit amount.

limits.intervalstring

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

limits.remainingnumber

Errors

Error status Description
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?

YesNo

Ask AI

Docs AI Assistant answers questions using sources from Airwallex Docs, Airwallex API, Airwallex JS, and other public Airwallex knowledge bases. To get your questions answered right from your coding agent, try our Developer MCP server.

Hi, how can I help?

How do I start as a merchant?How can I accept payments?

Deep thinking

Powered by

kapa.ai

protected by reCAPTCHA

Cookies on the Airwallex website

We use cookies to enhance your website experience at Airwallex. Visit our cookie policy to learn more and manage your preferences at any time.

I accept

验证码

安全验证

返回

拖动下方滑块完成拼图

确定

AI生成背景

我不会

常规验证

确定