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.
- Endpoints
- Webhook events
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:
- Only one notification per spend limit interval will be sent. A webhook is triggered only when the threshold is crossed, and further spending below the threshold will not trigger additional notifications. Example: if the percent enabled is 10, a webhook will be sent once the remaining limit is at or less than 10%.
- If the spend limit has been updated, a new notification will be sent when the new threshold is crossed.
- This alert only applies to multiple use cards.
- If not specified, this setting will be enabled by default with
enabledset totrueandpercentset to an account specific default value.
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):
device_certs(array): device certificate chain, leaf certificate firstnonce_signature(string): signature over the noncenonce(string): one-time nonce
google_pay (Google Pay provisioning):
device_id(string): stable device identifier from the Google Pay SDKclient_customer_id(string): wallet account holder identifier
samsung_pay (Samsung Pay provisioning):
device_id(string): stable device identifier from the Samsung Pay SDKclient_customer_id(string): wallet account holder identifier.
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
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生成背景
我不会
常规验证
确定