Card Order
With this set of APIs, you will be able to create cards for your customers. You can also retrieve and view the status of your current card orders, as well as the list of available card programs for the user.
The Address resource
An Address resource is used for billing and delivery address. Check address-validation for each field format.
Fields | Type | Definition |
---|---|---|
firstLine | String | The card holder's billing address |
secondLine | String | The card holder's billing address |
thirdLine | String | The card holder's billing address |
postCode | String | The card holder's billing postal code |
city | String | The card holder's billing city |
state | String | The card holder's billing state |
country | String | The card holder's billing country, in the 2 letter country code using ISO 3166-1 alpha-2 |
{"billingAddress": {"firstLine": "1 Paya Lebar Link","secondLine": "#13-06 PLQ 2","thirdLine": "Paya Lebar Quarter","postCode": "408533","city": "Singapore","state": null,"country": "SG",}}
{"deliveryAddress": {"firstLine": "27 English Street","secondLine": "#8-12 Block 1","thirdLine": null,"postCode": "5254","city": "Pallamana","state": "South Australia","country": "AU",}}
The Card Program resource
A Card Program is what Wise refers to all the cards that you will be issuing with us, grouped by product type and by issuing country.
Fields | Type | Definition |
---|---|---|
name | String | The name of the card program |
scheme | String | The scheme associated with the card program |
defaultCurrency | String | The default currency assigned to the card program |
cardType | String | The type of the card. It can be one of VIRTUAL_NON_UPGRADEABLE or PHYSICAL |
{"cardPrograms": [{"name": "VISA_DEBIT_BUSINESS_UK_1_CARDS_API","scheme": "VISA","defaultCurrency": "GBP","cardType" : "VIRTUAL_NON_UPGRADEABLE"}]}
The Card Order resource
For physical card response, expect to see the same value as billing address, it will be updated in the next release.
ID of the card order
Profile ID
Client ID
Card Program of the card holder.
Address set during card order
Address set during card order
Type of the card order. E.g. PHYSICAL
or VIRTUAL_<type>
Token of the card associated with card order. Nullable.
A string for replacement card. Not supported at the moment.
Time when the card order is created
Time when the card order was last modified
Status of the card order before card is issued.
Checkout card order statuses for more information.
Name of the card holder.
Phone number associated with the card order.
Maximum amount of spending on the card once issued. Nullable.
{"id": 142,"profileId": 123456,"clientId": "{{clientId}}","cardProgram": {"name": "VISA_DEBIT_BUSINESS_UK_1_CARDS_API","scheme": "VISA","defaultCurrency": "GBP","cardType" : "VIRTUAL_NON_UPGRADEABLE"},"billingAddress": {"firstLine": "56 Shoreditch High St","secondLine": "The Tea Bldg","thirdLine": null,"city": "London","postCode": "E1 6JJ","state": null,"country": "GB","phoneNumber": "+442071111111" // deprecated - please use cardOrder.phoneNumber instead},"cardType": "VIRTUAL_NON_UPGRADEABLE", // deprecated - field moved to cardProgram"cardToken": "4dc0be88-903f-49e4-8237-735f1139e3dd","replacesCard": null,"creationTime": "2023-07-31T01:43:24.596321434Z","modificationTime": "2023-07-31T01:43:24.596321825Z","status": "CARD_DETAILS_CREATED","cardHolderName": "John Smith","phoneNumber": "+441234567890","lifetimeLimit": 100}
{"id": 142,"profileId": 123456,"clientId": "{{clientId}}","cardProgram": {"name": "VISA_DEBIT_BUSINESS_UK_1_PHYSICAL_CARDS_API","scheme": "VISA","defaultCurrency": "GBP","cardType" : "PHYSICAL"},"billingAddress": {"firstLine": "56 Shoreditch High St","secondLine": "The Tea Bldg","thirdLine": null,"city": "London","postCode": "E1 6JJ","state": null,"country": "GB","phoneNumber": "+442071111111" // deprecated - please use cardOrder.phoneNumber instead},"deliveryAddress": {"firstLine": "92 Jubilee Market Hall","secondLine": "Covent Garden","thirdLine": "null","city": "London","postCode": "WC2E 8BD","state": null,"country": "GB","phoneNumber": "+442071111111" // deprecated - please use cardOrder.phoneNumber instead},"cardType": "VIRTUAL_NON_UPGRADEABLE", // deprecated - field moved to cardProgram"cardToken": "4dc0be88-903f-49e4-8237-735f1139e3dd","replacesCard": null,"creationTime": "2023-07-31T01:43:24.596321434Z","modificationTime": "2023-07-31T01:43:24.596321825Z","status": "COMPLETED","cardHolderName": "Smith John","phoneNumber": "+441234567890","lifetimeLimit": 100}
The Card Order status
The card order response will contain the status
field. The initial status is PLACED
or REQUIREMENT_FULFILLED
depending on the requirement fulfillment state.
The possible values are shown in the table below:
Status | Definition |
---|---|
PLACED | The card order is created. The card will be generated once it has fulfilled all the requirements |
REQUIREMENTS_FULFILLED | The card order has fulfilled all the requirements and the card should be generated in a short while |
CARD_DETAILS_CREATED | The card has been generated |
PRODUCED | The physical card has been produced and waiting to be picked up by delivery vendor (physical card only) |
COMPLETED | The card has been activated and is ready to use. The card order is completed |
CANCELLED | The card order has been cancelled. This can happen if you reach out to Wise Support to cancel a card order |
RETURNED | Delivery failed, the physical card has been returned and will be blocked (physical card only) |

Retrieve available card programs for a profile
GET /v3/spend/profiles/{{profileId}}/card-orders/availability
Retrieves the list of available card programs for each profileId
.
curl -X GET https://api.sandbox.transferwise.tech/v3/spend/profiles/{{profileId}}/card-orders/availability \-H 'Authorization: Bearer <your api token>' \-H 'Content-Type: application/json'
Response
Returns a collection of CardProgram resources available to the profileId
.
{"cardPrograms": [{"name": "VISA_DEBIT_BUSINESS_UK_1_CARDS_API","scheme": "VISA","defaultCurrency": "GBP","cardType" : "VIRTUAL_NON_UPGRADEABLE"}]}
Validate an Address
POST /v3/spend/address/validate
Validates the format of an address. Field validation is performed on the following criteria:
- value is required
- value length
- valid postCode for a country
Fields | Field max length (characters) | Required |
---|---|---|
firstLine | 30 | yes |
secondLine | 30 | no |
thirdLine | 30 | no |
postCode | 10 | no |
city | 30 | yes |
state | 30 | no |
country (ISO 3166-1 alpha-2) | 2 | yes |
curl -X GET https://api.sandbox.transferwise.tech/v3/spend/address/validate \-H 'Authorization: Bearer <your api token>' \-H 'Content-Type: application/json'-d '{"firstLine": "92 Jubilee Market Hall, Tavistock St, London WC2E 8BD, United Kingdom ","secondLine": "Covent Garden","thirdLine": "null","city": "","postCode": "12ab","state": null,"country": "GB"}'
Response
Returns a collection of errors on fields that did not pass the format validation. A successful address validation will return an empty collection.
{"errors": [{"field": "city","message": "Required Field"},{"field": "postCode","message": "Please enter a valid postcode"},{"field": "firstLine","message": "Must be less than 30 characters"}]}
Create a card order
POST /v3/spend/profiles/{{profileId}}/card-orders
Orders a new card for a given profileId
. The program
should be retrieved via the /card-orders/availability endpoint.
The cardType
determines what type of card is issued with a program
. cardType
value would be PHYSICAL
if the program
issue physical cards.
Fields | Type | Definition | Required |
---|---|---|---|
program | String | The name of the card program | Yes |
cardHolderName | String | The card holder's name | Yes |
embossedName | String | The card holder's name to print on the card (physical card only) | No |
phoneNumber | String | Must be a valid phone number prefixed with + and country code. An example of a valid phone number would be +6588888888 | Yes |
billingAddress | Address | The card holder's billing address | Yes |
deliveryAddress | Address | The card holder's delivery address (physical card only) | Yes |
lifetimeLimit | Integer | Optionally sets a lifetime spending limit on the card. A lifetime limit of 0 means that a card cannot be used until the lifetime limit is updated | No |
Response
Returns a Card Order.
curl -X POST https://api.sandbox.transferwise.tech/v3/spend/profiles/{{profileId}}/card-orders \-H 'Authorization: Bearer <your api token>' \-H 'Content-Type: application/json' \-H 'X-idempotence-uuid: 054064c9-e01e-49fb-8fd9-b0990b9442f4' \-d '{"program": "VISA_DEBIT_BUSINESS_UK_1_PHYSICAL_CARDS_API","cardHolderName": "John Smith,"embossedName": "Smith John", // Physical card order"phoneNumber": "+441234567890","billingAddress": {"firstLine": "56 Shoreditch High St","secondLine": "The Tea Bldg","thirdLine": null,"city": "London","postCode": "E1 6JJ","state": null,"country": "GB"},"deliveryAddress": { // Physical card order"firstLine": "92 Jubilee Market Hall","secondLine": "Covent Garden","thirdLine": "null","city": "London","postCode": "WC2E 8BD","state": null,"country": "GB"},"lifetimeLimit": 100,}'
Retrieve a list of card orders by profile
Returns a list of card orders created for the profileId
specified in the endpoint.
GET /v3/spend/profiles/{{profileId}}/card-orders?pageSize=10&pageNumber=1
Fields | Type | Definition | Required |
---|---|---|---|
pageSize | String | The maximum number of card orders to return per page. This number can be between 10 - 100, and will default to 10 | No |
pageNumber | String | The page number to retrieve the next set of card orders. The number has to be greater than 1, and will default to 1 | No |
curl -X GET https://api.sandbox.transferwise.tech/v3/spend/profiles/{{profileId}}/card-orders?pageSize=10&pageNumber=1 \-H 'Authorization: Bearer <your api token>'
Response
Fields | Type | Definition | Required |
---|---|---|---|
totalCount | Integer | The total number of card orders for this profileId | No |
cardOrders | List<CardOrder> | A collection of CardOrder for this profileId | No |
{"cardOrders": [{"id": 142,"profileId": 123456,"clientId": "wise_api_docs","cardProgram": {"name": "VISA_DEBIT_BUSINESS_UK_1_CARDS_API","scheme": "VISA","defaultCurrency": "GBP","cardType" : "VIRTUAL_NON_UPGRADEABLE",},"billingAddress": {"firstLine": "The Tea Building","secondLine": "56 Shoreditch High St","thirdLine": null,"city": "London","postCode": "E1 6JJ","state": null,"country": "GB","phoneNumber": "+441234567890" // deprecated - please use cardOrder.phoneNumber instead},"cardType" : "VIRTUAL_NON_UPGRADEABLE", // deprecated - field moved to cardProgram"cardToken": null,"replacesCard": null,"creationTime": "2022-05-31T01:43:24.596321434Z","modificationTime": "2022-05-31T01:43:24.596321825Z","status": "REQUIREMENTS_FULFILLED","cardHolderName": "John Smith","phoneNumber": "+441234567890","lifetimeLimit": 100}],"totalCount": 100}
Retrieve a card order by ID
GET /v3/spend/profiles/{{profileId}}/card-orders/{{cardOrderId}}
Retrieves a card order based on the cardOrderId
.
curl -X GET https://api.sandbox.transferwise.tech/v3/spend/profiles/{{profileId}}/card-orders/{{cardOrderId}} \-H 'Authorization: Bearer <your api token>'
Response
Returns a Card Order.