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

We are using 1 address field for card orders.

  • For virtual cards, the Address resource is a billing address. This address will only be used for AVS checks in countries where is it required.
  • For physical cards, the Address resource is a delivery address. This address will be used for AVS checks. It will also be used to deliver your card.

Check address-validation for each field format.

FieldsTypeDefinition
firstLineStringThe card holder's address
secondLineStringThe card holder's address
thirdLineStringThe card holder's address
postCodeStringThe card holder's postal code
cityStringThe card holder's city
stateStringThe card holder's state
countryStringThe card holder's country, it follows ISO 3166-1 alpha-2 standard
Address Resource
{
"address": {
"firstLine": "1 Paya Lebar Link",
"secondLine": "#13-06 PLQ 2",
"thirdLine": "Paya Lebar Quarter",
"postCode": "408533",
"city": "Singapore",
"state": null,
"country": "SG",
}
}
Billing Address Resource (deprecated)
{
"billingAddress": {
"firstLine": "1 Paya Lebar Link",
"secondLine": "#13-06 PLQ 2",
"thirdLine": "Paya Lebar Quarter",
"postCode": "408533",
"city": "Singapore",
"state": null,
"country": "SG",
}
}

Brazil Address resource

For a Brazil address, the fields are detailed below. Check address-validation-brazil for each field format.

FieldsTypeDefinition
addressNumberStringThe card holder's address number
addressStringThe card holder's address
districtStringThe card holder's district
complementStringThe card holder's complement
postCodeStringThe card holder's postal code
cityStringThe card holder's city
stateStringThe card holder's state
countryStringThe card holder's country, it follows ISO 3166-1 alpha-2 standard
Address Resource
{
"address": {
"addressNumber": "134534504",
"address": "Rua Moacir da Silva Mota",
"district": "Tancredo Neves",
"complement": null,
"state": "RR",
"city": "Boa Vista",
"postCode": "69313488",
"country": "BR"
}
}
Billing Address Resource (deprecated)
{
"billingAddress": {
"addressNumber": "134534504",
"address": "Rua Moacir da Silva Mota",
"district": "Tancredo Neves",
"complement": null,
"state": "RR",
"city": "Boa Vista",
"postCode": "69313488",
"country": "BR"
}
}

The Card Order resource

idtext

ID of the card order

profileIdnumber

Profile ID

clientIdtext

Client ID

cardProgramCardProgram

Card Program of the card holder.

addressAddress

Address set during card order

billingAddress (deprecated)Address

Address set during card order

cardTypetext

Type of the card order. E.g. PHYSICAL or VIRTUAL_<type>

cardTokentext

Token of the card associated with card order. Nullable.

replacesCardtext

A string for replacement card. Not supported at the moment.

creationTimetext

Time when the card order is created

modificationTimetext

Time when the card order was last modified

statusCardStatus

Status of the card order before card is issued.
Checkout card order statuses for more information.

cardHolderNametext

Name of the card holder.

phoneNumbertext

Phone number associated with the card order.

lifetimeLimitnumber

Maximum amount of spending on the card once issued. Nullable.

Card order Response
{
"id": 142,
"profileId": 123456,
"clientId": "{{clientId}}",
"cardProgram": {
"name": "VISA_DEBIT_BUSINESS_UK_1_CARDS_API",
"scheme": "VISA",
"defaultCurrency": "GBP",
"cardType" : "VIRTUAL_NON_UPGRADEABLE"
},
"address": {
"firstLine": "56 Shoreditch High St",
"secondLine": "The Tea Bldg",
"thirdLine": null,
"city": "London",
"postCode": "E1 6JJ",
"state": null,
"country": "GB"
},
"billingAddress": { // deprecated on the 16/10/2023
"firstLine": "56 Shoreditch High St",
"secondLine": "The Tea Bldg",
"thirdLine": null,
"city": "London",
"postCode": "E1 6JJ",
"state": null,
"country": "GB"
},
"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
}

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:

StatusDefinition
PLACEDThe card order is created. The card will be generated once it has fulfilled all the requirements
REQUIREMENTS_FULFILLEDThe card order has fulfilled all the requirements and the card should be generated in a short while
CARD_DETAILS_CREATEDThe card has been generated
PRODUCEDThe physical card has been produced and waiting to be picked up by delivery vendor (physical card only)
COMPLETEDThe card has been activated and is ready to use. The card order is completed
CANCELLEDThe card order has been cancelled. This can happen if you reach out to Wise Support to cancel a card order
RETURNEDDelivery failed, the physical card has been returned and will be blocked (physical card only)
Card order status transitions
Create card order statuses transition diagram

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.

FieldsTypeDefinition
nameStringThe name of the card program
schemeStringThe scheme associated with the card program
defaultCurrencyStringThe default currency assigned to the card program
cardTypeStringThe type of the card. It can be one of VIRTUAL_NON_UPGRADEABLE or PHYSICAL
Card Program Resource
{
"cardPrograms": [
{
"name": "VISA_DEBIT_BUSINESS_UK_1_CARDS_API",
"scheme": "VISA",
"defaultCurrency": "GBP",
"cardType" : "VIRTUAL_NON_UPGRADEABLE"
}
]
}

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.

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

Example Response
{
"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
FieldsField max length (characters)Required
firstLine30yes
secondLine30no
thirdLine30no
postCode10yes
city30yes
state30no
country (ISO 3166-1 alpha-2)2yes
Address request fields
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": "wrong-postcode",
"state": null,
"country": "GB"
}'

Validate a Australia address

It follows the same rules as address validation except the state field is mandatory. The possible value are as follow:

CodeState
ACTAustralian Capital Territory
NSWNew South Wales
NTNorthern Territory
QLDQueensland
SASouth Australia
TASTasmania
VICVictoria
WAWestern Australia

Validate a Brazil address

The fields are described here. Please follow fields validation described below:

FieldsField max length (characters)Required
addressNumber6yes
address100yes
district80yes
complement28no
postCode8yes
city30yes
state10yes
country (ISO 3166-1 alpha-2)2yes

The possible values for state are as follow:

CodeState
ACAcre
ALAlagoas
APAmapá
AMAmazonas
BABahia
CECeará
DFDistrito Federal
ESEspírito Santo
GOGoiás
MAMaranhão
MTMato Grosso
MSMato Grosso do Sul
MGMinas Gerais
PAPará
PBParaíba
PRParaná
PEPernambuco
PIPiauí
RJRio de Janeiro
RNRio Grande do Norte
RSRio Grande do Sul
RORondônia
RRRoraima
SCSanta Catarina
SPSão Paulo
SESergipe
TOTocantins
Brazil address request fields
curl -X GET https://api.sandbox.transferwise.tech/v3/spend/address/validate \
-H 'Authorization: Bearer <your api token>' \
-H 'Content-Type: application/json'
-d '{
"addressNumber": "134534504",
"address": "Rua Moacir da Silva Mota",
"district": "Tancredo Neves",
"complement": null,
"state": "RR",
"city": "Boa Vista",
"postCode": "69313488",
"country": "BR"
}'

Response

Returns a collection of errors on fields that did not pass the format validation. A successful address validation will return an empty collection.

Address Validation Response
{
"errors": [
{
"field": "city",
"message": "Required Field"
},
{
"field": "postCode",
"message": "Please enter a valid postcode"
},
{
"field": "firstLine",
"message": "Must be less than 30 characters"
}
]
}
Brazil Address Validation Response
{
"errors": [
{
"field": "addressNumber",
"message": "Must be less than 6 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.

FieldsTypeDefinitionRequired
programStringThe name of the card programYes
cardHolderName StringThe card holder's nameYes
embossedName StringThe card holder's name to print on the card (physical card only)No
phoneNumber StringMust be a valid phone number prefixed with + and country code. An example of a valid phone number would be +6588888888Yes
addressAddressThe card holder's billing address or delivery addressYes
billingAddressAddressThe card holder's billing address or delivery address (deprecated)Yes
lifetimeLimitIntegerOptionally 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 updatedNo

Response

Returns a Card Order.

Create card order Request
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",
"address": {
"firstLine": "56 Shoreditch High St",
"secondLine": "The Tea Bldg",
"thirdLine": null,
"city": "London",
"postCode": "E1 6JJ",
"state": null,
"country": "GB"
},
"billingAddress": { // deprecated on the 02/10/2023
"firstLine": "56 Shoreditch High St",
"secondLine": "The Tea Bldg",
"thirdLine": null,
"city": "London",
"postCode": "E1 6JJ",
"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

FieldsTypeDefinitionRequired
pageSizeStringThe maximum number of card orders to return per page. This number can be between 10 - 100, and will default to 10No
pageNumberStringThe page number to retrieve the next set of card orders. The number has to be greater than 1, and will default to 1No
Example Request
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

FieldsTypeDefinitionRequired
totalCountIntegerThe total number of card orders for this profileIdNo
cardOrdersList<CardOrder>A collection of CardOrder for this profileIdNo
Example Response
{
"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",
},
"address": {
"firstLine": "56 Shoreditch High St",
"secondLine": "The Tea Bldg",
"thirdLine": null,
"city": "London",
"postCode": "E1 6JJ",
"state": null,
"country": "GB"
},
"billingAddress": { // deprecated on the 02/10/2023
"firstLine": "56 Shoreditch High St",
"secondLine": "The Tea Building",
"thirdLine": null,
"city": "London",
"postCode": "E1 6JJ",
"state": null,
"country": "GB",
},
"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.

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