Search documentation

Ask Kai

Ask Kai

# Cards

Copy for LLMView as Markdown

You can create [virtual cardsDocs](/content/docs/issuing/get-started/create-cards/index.html) 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](/content/docs/api/issuing/cards/create/index.html) [GET /api/v1/issuing/cards/{id}Retrieve a Card](/content/docs/api/issuing/cards/retrieve/index.html) [GET /api/v1/issuing/cardsList all Cards](/content/docs/api/issuing/cards/list/index.html) [POST /api/v1/issuing/cards/{id}/updateUpdate a Card](/content/docs/api/issuing/cards/update/index.html) [POST /api/v1/issuing/cards/{id}/activateActivate a Card](/content/docs/api/issuing/cards/activate/index.html) [POST /api/v1/issuing/cards/{id}/provision\_digital\_tokenProvision a Card to a Digital Wallet](/content/docs/api/issuing/cards/provision_digital_token/index.html) [GET /api/v1/issuing/cards/{id}/detailsList all Sensitive Card Details](/content/docs/api/issuing/cards/details/index.html) [GET /api/v1/issuing/cards/{id}/limitsList all Card Remaining Limits](/content/docs/api/issuing/cards/limits/index.html)

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](/content/docs/api/issuing/config/retrieve/index.html) 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](/content/docs/issuing/card-controls/authorization-controls/merchant-brand-transaction-categories/index.html). 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](/content/docs/api/issuing/merchant_brands/retrieve/index.html).

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](/content/docs/issuing/card-controls/authorization-controls/merchant-brand-transaction-categories/index.html). 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 `enabled` set to `true` and `percent` set 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](/content/docs/issuing/get-started/create-cards/card-statuses/index.html) 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](/content/docs/issuing/get-started/create-cards/card-statuses/index.html) 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](/content/docs/issuing/manage-cards/retrieve-physical-card-delivery-details/index.html) 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

```bash
$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)

```json
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](/content/docs/issuing/get-started/create-cards/card-statuses/index.html) 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](/content/docs/issuing/get-started/create-cards/card-statuses/index.html) 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](/content/docs/issuing/manage-cards/retrieve-physical-card-delivery-details/index.html) 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}

```bash
$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

```bash
$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)

```json
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](/content/docs/issuing/get-started/create-cards/card-statuses/index.html) 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](/content/docs/issuing/get-started/create-cards/card-statuses/index.html) 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](/content/docs/issuing/manage-cards/retrieve-physical-card-delivery-details/index.html) 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

```bash
$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

```bash
$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 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.

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

```bash
$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)

```json
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

```bash
$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)

```json
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

```bash
$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)

```json
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](/content/docs/index.html), [Airwallex API](/content/docs/api/index.html), [Airwallex JS](/content/docs/js/index.html), and other public Airwallex knowledge bases. To get your questions answered right from your coding agent, try our [Developer MCP server](/content/docs/developer-tools/ai/developer-mcp/index.html).

Hi, how can I help?

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

Deep thinking

Powered by

[kapa.ai](https://www.kapa.ai/)

protected by reCAPTCHA

### Cookies on the Airwallex website

We use cookies to enhance your website experience at Airwallex. Visit our [cookie policy](/content/terms/cookie-policy/index.html) to learn more and manage your preferences at any time.

I accept

验证码

安全验证

返回

拖动下方滑块完成拼图

确定

AI生成背景

我不会

常规验证

确定
