Airwallex logo
Airwallex logoAirwallex logo

Cards

Copy for LLMView as Markdown

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

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
POST /api/v1/issuing/cards/create
GET /api/v1/issuing/cards
GET /api/v1/issuing/cards/{id}/details
GET /api/v1/issuing/cards/{id}
POST /api/v1/issuing/cards/{id}/activate
POST /api/v1/issuing/cards/{id}/provision_digital_token
GET /api/v1/issuing/cards/{id}/limits
POST /api/v1/issuing/cards/{id}/update

Create a card

POST /api/v1/issuing/cards/create

Copy for LLMView as Markdown

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

Request body
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.

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 enabled set to true and percent set to an account specific default value.
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_controlsrequiredobject

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

authorization_controls.active_fromstring

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

authorization_controls.active_tostring

If provided, authorizations after this time will be rejected.

authorization_controls.allowed_currenciesarray

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

authorization_controls.allowed_merchant_brandsobject

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

authorization_controls.allowed_merchant_brands.categoriesarray

Allowed Merchant Brands Categories for transactions. These must be provided using the codes defined in the Merchant Brands Controls product page . 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 page . 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.allowed_transaction_countrequiredstring

Specifies whether this card is a Single or Multiple Use card. Possible values are SINGLE, MULTIPLE. Single Use means that the card can only be used for 1 successful debit transaction.

authorization_controls.blocked_transaction_usagesarray

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

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

authorization_controls.blocked_transaction_usages.transaction_scopestring

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

authorization_controls.blocked_transaction_usages.usage_scopestring

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

authorization_controls.transaction_limitsrequiredobject

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

authorization_controls.transaction_limits.cash_withdrawal_limitsarray

Cash withdrawal transaction limits are based on interval and amount.

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

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

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

authorization_controls.transaction_limits.cash_withdrawal_limits.amountrequirednumber

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

authorization_controls.transaction_limits.cash_withdrawal_limits.intervalrequiredstring

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

authorization_controls.transaction_limits.currencystring

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

authorization_controls.transaction_limits.limitsrequiredarray

Transaction limits are based on interval and amount.

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

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

authorization_controls.transaction_limits.limits.amountrequirednumber

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

authorization_controls.transaction_limits.limits.intervalrequiredstring

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

brandstring

Scheme for Issuance. Default VISA.

cardholder_idrequiredstring

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

client_datastring

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

created_byrequiredstring

Full legal name of user requesting new card

delivery_detailsobject

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

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.

form_factorrequiredstring

Form of the card - PHYSICAL or VIRTUAL

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.

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.

metadataobject

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

nick_namestring

A nick name for the card

notestring

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

postal_addressobject

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

postal_address.cityrequiredstring

City of address

postal_address.countryrequiredstring

ISO country code of address

postal_address.line1requiredstring

Address line 1

postal_address.line2string

Address line 2

postal_address.postcoderequiredstring

Address postcode or ZIP code

postal_address.statestring

Address state or region

programrequiredobject

Card program

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

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.

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

Response body - 202 Accepted
activate_on_issueboolean

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

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.

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 enabled set to true and percent set to an account specific default value.
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

all_card_versions.card_numberstring

Masked card number of this version

all_card_versions.card_statusstring

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

PENDING, FAILED, INACTIVE, ACTIVE, LOST, STOLEN, CLOSED, BLOCKED, EXPIRED, UNKNOWN

all_card_versions.card_versioninteger

Version Id which uniquely identifies this card version object

all_card_versions.created_atstring

Creation time of the card version.

authorization_controlsobject

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

authorization_controls.active_fromstring

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

authorization_controls.active_tostring

If provided, authorizations after this time will be rejected.

authorization_controls.allowed_currenciesarray

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

authorization_controls.allowed_merchant_brandsobject

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

authorization_controls.allowed_merchant_brands.categoriesarray

Allowed Merchant Brands Categories for transactions. These must be provided using the codes defined in the Merchant Brands Controls product page . 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 page . 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.allowed_transaction_countstring

Specifies whether this card is a Single or Multiple Use card. Possible values are SINGLE, MULTIPLE. Single Use means that the card can only be used for 1 successful debit transaction.

authorization_controls.blocked_transaction_usagesarray

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

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

authorization_controls.blocked_transaction_usages.transaction_scopestring

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

authorization_controls.blocked_transaction_usages.usage_scopestring

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

authorization_controls.transaction_limitsobject

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

authorization_controls.transaction_limits.cash_withdrawal_limitsarray

Cash withdrawal transaction limits are based on interval and amount.

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

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

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

authorization_controls.transaction_limits.cash_withdrawal_limits.amountnumber

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

authorization_controls.transaction_limits.cash_withdrawal_limits.intervalstring

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

authorization_controls.transaction_limits.currencystring

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

authorization_controls.transaction_limits.limitsarray

Transaction limits are based on interval and amount.

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

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

authorization_controls.transaction_limits.limits.amountnumber

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

authorization_controls.transaction_limits.limits.intervalstring

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

brandstring

Card Brand

card_idstring

Unique Identifier for card

card_numberstring

Masked card number

card_statusstring

Current card status. See Card Status for definitions.

PENDING, FAILED, INACTIVE, ACTIVE, LOST, STOLEN, CLOSED, BLOCKED, EXPIRED, UNKNOWN

card_versioninteger

Current version of the card

cardholder_idstring

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

client_datastring

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

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

delivery_details.delivery_modestring

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

MAIL, EXPRESS, UNKNOWN

delivery_details.delivery_vendorstring

Delivery vendor of this card.

UNKNOWN, AU_POST, EMS, HK_POST, CITY_LINK, DHL, CN_POST, PL_POST, USPS, FEDEX

delivery_details.mobile_numberstring

The mobile number for the card delivery.

delivery_details.preferred_delivery_modestring

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

MAIL, EXPRESS, UNKNOWN

delivery_details.statusstring

See Delivery Status for definitions.

PENDING, PRINTED, FAILED_TO_PRINT, DISPATCHED, IN_TRANSIT, OUT_FOR_DELIVERY, DELIVERED, DELIVERY_FAILED, DELIVERY_DELAYED, UNKNOWN

delivery_details.status_descriptionstring

A brief description of the status

delivery_details.trackedboolean

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

delivery_details.tracking_numberstring

Delivery tracking number of this card.

delivery_details.updated_atstring

Last update time of the delivery details

form_factorstring

Form of the card - PHYSICAL or VIRTUAL

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.

is_personalizedboolean

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.

metadataobject

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

name_on_cardstring

Name to be printed on card.

nick_namestring

A nick name for the card

notestring

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

postal_addressobject

Optional postal address of physical card delivery.

postal_address.citystring

City of address

postal_address.countrystring

ISO country code of address

postal_address.line1string

Address line 1

postal_address.line2string

Address line 2

postal_address.postcodestring

Address postcode or ZIP code

postal_address.statestring

Address state or region

primary_contact_detailsobject

Details of the primary contact of the card

primary_contact_details.emailstring

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

primary_contact_details.full_namestring

Full name of the primary contact of the new card.

primary_contact_details.mobile_numberstring

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

programobject

Card program

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

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

GOOD_FUNDS_CREDIT, B2B_TRAVEL, UNKNOWN

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.

UNKNOWN, DEBIT, PREPAID, CREDIT, DEFERRED_DEBIT

purposestring

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

SUBSCRIPTIONS, OFFICE_SUPPLIES, MARKETING_EXPENSES, TRAVEL_EXPENSES, CLIENT_EXPENSES, TEAM_EXPENSES, ONLINE_PURCHASING, BUSINESS_EXPENSES, OTHER

request_idstring

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

updated_atstring

Last update time of the card.

Errors
Error statusDescription
400

Possible errors: field_required, bad_request, invalid_argument

401

Possible errors: credentials_invalid, credentials_expired

429

Too many requests

500

Service unavailable

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

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

Parameters
card_statusstring

Current card status
One of PENDING, FAILED, INACTIVE, ACTIVE, LOST, STOLEN, CLOSED, BLOCKED, EXPIRED

PENDING, FAILED, INACTIVE, ACTIVE, LOST, STOLEN, CLOSED, BLOCKED, EXPIRED, UNKNOWN

cardholder_idstring

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

from_created_atstring

Created_from_date in ISO8601 format (inclusive)

from_updated_atstring

Updated_from_date in ISO8601 format (inclusive)

nick_namestring

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

page_numinteger

Page number, starts from 0

page_sizeinteger

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

to_created_atstring

Created_to_date in ISO8601 format (inclusive)

to_updated_atstring

Updated_to_date in ISO8601 format (inclusive)

Response body - 200 OK
has_moreboolean
itemsarray
items.additional_cardholder_idsarray

Unique Identifiers for additional cardholders.

items.brandstring

Card Brand

items.card_idstring

Unique Identifier for card

items.card_numberstring

Masked card number

items.card_statusstring

Current card status, one of:

PENDING, FAILED, INACTIVE, ACTIVE, LOST, STOLEN, CLOSED, BLOCKED, EXPIRED, UNKNOWN

items.cardholder_idstring

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

items.created_atstring

Date card was created

items.nick_namestring

Nickname on the card.

items.updated_atstring

Last update time of the card.

Errors
Error statusDescription
400

Possible errors: field_required, bad_request, invalid_argument

401

Possible errors: credentials_invalid, credentials_expired

429

Too many requests

500

Service unavailable

GET /api/v1/issuing/cards
$curl --request GET \
>  --url 'https://api-demo.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?

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

Parameters
idrequiredstring

Unique Identifier for card

Response body - 200 OK
card_numberstring

Card Number

cvvstring

Card Verification Value

expiry_monthinteger

Card Expiry Month

expiry_yearinteger

Card Expiry Year

name_on_cardstring

Name printed on card

Errors
Error statusDescription
400

Possible errors: field_required, bad_request, invalid_argument

401

Possible errors: credentials_invalid, credentials_expired

429

Too many requests

500

Service unavailable

GET /api/v1/issuing/cards/{id}/details
$curl --request GET \
>  --url 'https://api-demo.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?

Get card details

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

Copy for LLMView as Markdown

Retrieve Card details

Parameters
idrequiredstring

Unique Identifier for card

Response body - 200 OK
activate_on_issueboolean

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

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.

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 enabled set to true and percent set to an account specific default value.
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

all_card_versions.card_numberstring

Masked card number of this version

all_card_versions.card_statusstring

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

PENDING, FAILED, INACTIVE, ACTIVE, LOST, STOLEN, CLOSED, BLOCKED, EXPIRED, UNKNOWN

all_card_versions.card_versioninteger

Version Id which uniquely identifies this card version object

all_card_versions.created_atstring

Creation time of the card version.

authorization_controlsobject

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

authorization_controls.active_fromstring

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

authorization_controls.active_tostring

If provided, authorizations after this time will be rejected.

authorization_controls.allowed_currenciesarray

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

authorization_controls.allowed_merchant_brandsobject

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

authorization_controls.allowed_merchant_brands.categoriesarray

Allowed Merchant Brands Categories for transactions. These must be provided using the codes defined in the Merchant Brands Controls product page . 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 page . 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.allowed_transaction_countstring

Specifies whether this card is a Single or Multiple Use card. Possible values are SINGLE, MULTIPLE. Single Use means that the card can only be used for 1 successful debit transaction.

authorization_controls.blocked_transaction_usagesarray

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

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

authorization_controls.blocked_transaction_usages.transaction_scopestring

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

authorization_controls.blocked_transaction_usages.usage_scopestring

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

authorization_controls.transaction_limitsobject

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

authorization_controls.transaction_limits.cash_withdrawal_limitsarray

Cash withdrawal transaction limits are based on interval and amount.

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

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

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

authorization_controls.transaction_limits.cash_withdrawal_limits.amountnumber

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

authorization_controls.transaction_limits.cash_withdrawal_limits.intervalstring

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

authorization_controls.transaction_limits.currencystring

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

authorization_controls.transaction_limits.limitsarray

Transaction limits are based on interval and amount.

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

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

authorization_controls.transaction_limits.limits.amountnumber

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

authorization_controls.transaction_limits.limits.intervalstring

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

brandstring

Card Brand

card_idstring

Unique Identifier for card

card_numberstring

Masked card number

card_statusstring

Current card status. See Card Status for definitions.

PENDING, FAILED, INACTIVE, ACTIVE, LOST, STOLEN, CLOSED, BLOCKED, EXPIRED, UNKNOWN

card_versioninteger

Current version of the card

cardholder_idstring

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

client_datastring

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

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

delivery_details.delivery_modestring

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

MAIL, EXPRESS, UNKNOWN

delivery_details.delivery_vendorstring

Delivery vendor of this card.

UNKNOWN, AU_POST, EMS, HK_POST, CITY_LINK, DHL, CN_POST, PL_POST, USPS, FEDEX

delivery_details.mobile_numberstring

The mobile number for the card delivery.

delivery_details.preferred_delivery_modestring

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

MAIL, EXPRESS, UNKNOWN

delivery_details.statusstring

See Delivery Status for definitions.

PENDING, PRINTED, FAILED_TO_PRINT, DISPATCHED, IN_TRANSIT, OUT_FOR_DELIVERY, DELIVERED, DELIVERY_FAILED, DELIVERY_DELAYED, UNKNOWN

delivery_details.status_descriptionstring

A brief description of the status

delivery_details.trackedboolean

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

delivery_details.tracking_numberstring

Delivery tracking number of this card.

delivery_details.updated_atstring

Last update time of the delivery details

form_factorstring

Form of the card - PHYSICAL or VIRTUAL

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.

is_personalizedboolean

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.

metadataobject

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

name_on_cardstring

Name to be printed on card.

nick_namestring

A nick name for the card

notestring

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

postal_addressobject

Optional postal address of physical card delivery.

postal_address.citystring

City of address

postal_address.countrystring

ISO country code of address

postal_address.line1string

Address line 1

postal_address.line2string

Address line 2

postal_address.postcodestring

Address postcode or ZIP code

postal_address.statestring

Address state or region

primary_contact_detailsobject

Details of the primary contact of the card

primary_contact_details.emailstring

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

primary_contact_details.full_namestring

Full name of the primary contact of the new card.

primary_contact_details.mobile_numberstring

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

programobject

Card program

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

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

GOOD_FUNDS_CREDIT, B2B_TRAVEL, UNKNOWN

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.

UNKNOWN, DEBIT, PREPAID, CREDIT, DEFERRED_DEBIT

purposestring

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

SUBSCRIPTIONS, OFFICE_SUPPLIES, MARKETING_EXPENSES, TRAVEL_EXPENSES, CLIENT_EXPENSES, TEAM_EXPENSES, ONLINE_PURCHASING, BUSINESS_EXPENSES, OTHER

request_idstring

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

updated_atstring

Last update time of the card.

Errors
Error statusDescription
400

Possible errors: field_required, bad_request, invalid_argument

401

Possible errors: credentials_invalid, credentials_expired

429

Too many requests

500

Service unavailable

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

Activate a card

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

Copy for LLMView as Markdown

Activate a physical card for card payment authorizations.

Parameters
idrequiredstring

Unique Identifier for card

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

Possible errors: field_required, bad_request, invalid_argument

401

Possible errors: credentials_invalid, credentials_expired

429

Too many requests

500

Service unavailable

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

Provision a card to a digital wallet

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

Copy for LLMView as Markdown

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

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

apple_pay (Apple Wallet / PassKit provisioning):

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

google_pay (Google Pay provisioning):

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

samsung_pay (Samsung Pay provisioning):

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

Unique Identifier for card

Request body
typerequiredstring

Digital wallet type.

apple_pay, google_pay, samsung_pay

device_certsarray

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

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.

client_customer_idstring

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

device_idstring

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

server_session_idstring

Optional. Used for push provisioning with Google Pay.

Response body - 200 OK
card_idstring

Identifier of the provisioned card.

activation_datastring

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

encrypted_pass_datastring

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

ephemeral_public_keystring

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

expiration_dateobject

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

expiration_date.monthstring

Expiry month of the provisioned token.

expiration_date.yearstring

Expiry year of the provisioned token.

enc_addressstring

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

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.

google_opaque_payment_cardstring

Present when type is google_pay. Used for push provisioning.

card_typestring

Present when type is samsung_pay. Card network / type.

vcard_idstring

Present when type is samsung_pay.

Errors
Error statusDescription
400

Possible errors: field_required, bad_request, invalid_argument

401

Possible errors: credentials_invalid, credentials_expired

429

Too many requests

500

Service unavailable

POST /api/v1/issuing/cards/{id}/provision_digital_token
$curl --request POST \
>  --url 'https://api-demo.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?

Get card remaining limits

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

Copy for LLMView as Markdown

Retrieve remaining limits of a card

Parameters
idrequiredstring

Unique Identifier for card

Response body - 200 OK
cash_withdrawal_limitsarray

Remaining Cash Withdrawal Limits for Intervals.

cash_withdrawal_limits.amountnumber

Transaction limit amount.

cash_withdrawal_limits.intervalstring

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

cash_withdrawal_limits.remainingnumber

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

currencystring

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

limitsarray

Remaining limits for Intervals.

limits.amountnumber

Transaction limit amount.

limits.intervalstring

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

limits.remainingnumber

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

Errors
Error statusDescription
401

Possible errors: credentials_invalid, credentials_expired

429

Too many requests

500

Service unavailable

GET /api/v1/issuing/cards/{id}/limits
$curl --request GET \
>  --url 'https://api-demo.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?

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.

Parameters
idrequiredstring

Unique Identifier for 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.

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 enabled set to true and percent set to an account specific default value.
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.

authorization_controls.active_fromstring

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

authorization_controls.active_tostring

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

authorization_controls.allowed_currenciesarray

Allowed Currencies for transactions.

authorization_controls.allowed_merchant_brandsobject

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

authorization_controls.allowed_merchant_brands.categoriesarray

Allowed Merchant Brands Categories for transactions. These must be provided using the codes defined in the Merchant Brands Controls product page . 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 page . Please note if this field is absent from request payload, or has a value of null or empty array [], then transactions from all merchant brand subcategories will be allowed.

authorization_controls.allowed_merchant_categoriesarray

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

authorization_controls.allowed_merchant_countriesarray

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

authorization_controls.blocked_transaction_usagesarray

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

authorization_controls.blocked_transaction_usages.transaction_scopestring

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

authorization_controls.blocked_transaction_usages.usage_scopestring

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

authorization_controls.transaction_limitsobject

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

authorization_controls.transaction_limits.cash_withdrawal_limitsrequiredarray

Cash withdrawal transaction limits are based on interval and amount.

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

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

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

authorization_controls.transaction_limits.cash_withdrawal_limits.amountrequirednumber

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

authorization_controls.transaction_limits.cash_withdrawal_limits.intervalrequiredstring

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

authorization_controls.transaction_limits.currencystring

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

authorization_controls.transaction_limits.limitsrequiredarray

Transaction limits are based on interval and amount.

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

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

authorization_controls.transaction_limits.limits.amountrequirednumber

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

authorization_controls.transaction_limits.limits.intervalrequiredstring

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

card_statusstring

Card status, Allowed values are INACTIVE, ACTIVE, CLOSED

cardholder_idstring

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

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

purposestring

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

Response body - 200 OK
activate_on_issueboolean

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

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.

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 enabled set to true and percent set to an account specific default value.
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

all_card_versions.card_numberstring

Masked card number of this version

all_card_versions.card_statusstring

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

PENDING, FAILED, INACTIVE, ACTIVE, LOST, STOLEN, CLOSED, BLOCKED, EXPIRED, UNKNOWN

all_card_versions.card_versioninteger

Version Id which uniquely identifies this card version object

all_card_versions.created_atstring

Creation time of the card version.

authorization_controlsobject

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

authorization_controls.active_fromstring

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

authorization_controls.active_tostring

If provided, authorizations after this time will be rejected.

authorization_controls.allowed_currenciesarray

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

authorization_controls.allowed_merchant_brandsobject

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

authorization_controls.allowed_merchant_brands.categoriesarray

Allowed Merchant Brands Categories for transactions. These must be provided using the codes defined in the Merchant Brands Controls product page . 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 page . 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.allowed_transaction_countstring

Specifies whether this card is a Single or Multiple Use card. Possible values are SINGLE, MULTIPLE. Single Use means that the card can only be used for 1 successful debit transaction.

authorization_controls.blocked_transaction_usagesarray

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

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

authorization_controls.blocked_transaction_usages.transaction_scopestring

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

authorization_controls.blocked_transaction_usages.usage_scopestring

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

authorization_controls.transaction_limitsobject

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

authorization_controls.transaction_limits.cash_withdrawal_limitsarray

Cash withdrawal transaction limits are based on interval and amount.

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

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

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

authorization_controls.transaction_limits.cash_withdrawal_limits.amountnumber

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

authorization_controls.transaction_limits.cash_withdrawal_limits.intervalstring

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

authorization_controls.transaction_limits.currencystring

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

authorization_controls.transaction_limits.limitsarray

Transaction limits are based on interval and amount.

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

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

authorization_controls.transaction_limits.limits.amountnumber

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

authorization_controls.transaction_limits.limits.intervalstring

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

brandstring

Card Brand

card_idstring

Unique Identifier for card

card_numberstring

Masked card number

card_statusstring

Current card status. See Card Status for definitions.

PENDING, FAILED, INACTIVE, ACTIVE, LOST, STOLEN, CLOSED, BLOCKED, EXPIRED, UNKNOWN

card_versioninteger

Current version of the card

cardholder_idstring

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

client_datastring

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

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

delivery_details.delivery_modestring

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

MAIL, EXPRESS, UNKNOWN

delivery_details.delivery_vendorstring

Delivery vendor of this card.

UNKNOWN, AU_POST, EMS, HK_POST, CITY_LINK, DHL, CN_POST, PL_POST, USPS, FEDEX

delivery_details.mobile_numberstring

The mobile number for the card delivery.

delivery_details.preferred_delivery_modestring

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

MAIL, EXPRESS, UNKNOWN

delivery_details.statusstring

See Delivery Status for definitions.

PENDING, PRINTED, FAILED_TO_PRINT, DISPATCHED, IN_TRANSIT, OUT_FOR_DELIVERY, DELIVERED, DELIVERY_FAILED, DELIVERY_DELAYED, UNKNOWN

delivery_details.status_descriptionstring

A brief description of the status

delivery_details.trackedboolean

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

delivery_details.tracking_numberstring

Delivery tracking number of this card.

delivery_details.updated_atstring

Last update time of the delivery details

form_factorstring

Form of the card - PHYSICAL or VIRTUAL

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.

is_personalizedboolean

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.

metadataobject

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

name_on_cardstring

Name to be printed on card.

nick_namestring

A nick name for the card

notestring

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

postal_addressobject

Optional postal address of physical card delivery.

postal_address.citystring

City of address

postal_address.countrystring

ISO country code of address

postal_address.line1string

Address line 1

postal_address.line2string

Address line 2

postal_address.postcodestring

Address postcode or ZIP code

postal_address.statestring

Address state or region

primary_contact_detailsobject

Details of the primary contact of the card

primary_contact_details.emailstring

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

primary_contact_details.full_namestring

Full name of the primary contact of the new card.

primary_contact_details.mobile_numberstring

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

programobject

Card program

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

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

GOOD_FUNDS_CREDIT, B2B_TRAVEL, UNKNOWN

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.

UNKNOWN, DEBIT, PREPAID, CREDIT, DEFERRED_DEBIT

purposestring

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

SUBSCRIPTIONS, OFFICE_SUPPLIES, MARKETING_EXPENSES, TRAVEL_EXPENSES, CLIENT_EXPENSES, TEAM_EXPENSES, ONLINE_PURCHASING, BUSINESS_EXPENSES, OTHER

request_idstring

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

updated_atstring

Last update time of the card.

Errors
Error statusDescription
400

Possible errors: field_required, bad_request, invalid_argument

401

Possible errors: credentials_invalid, credentials_expired

429

Too many requests

500

Service unavailable

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