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.

Endpoints

GET/v3/spend/profiles/{{profileId}}/card-orders/availability

POST/v3/spend/address/validate

POST/v3/spend/profiles/{{profileId}}/card-orders

GET/v3/spend/profiles/{{profileId}}/card-orders?pageNumber=1&pageSize=10

GET/v3/spend/profiles/{{profileId}}/card-orders/{{cardOrderId}}

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

Billing Address Resource

{
    "billingAddress": {
        "firstLine": "1 Paya Lebar Link",
        "secondLine": "#13-06 PLQ 2",
        "thirdLine": "Paya Lebar Quarter",
        "postCode": "408533",
        "city": "Singapore",
        "state": null,
        "country": "SG",
    }
}

Delivery Address Resource

{
    "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`

Card Program Resource

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

idtext

ID of the card order

profileIdnumber

Profile ID

clientIdtext

Client ID

cardProgramCardProgram

Card Program of the card holder.

billingAddressAddress

Address set during card order

deliveryAddressAddress

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.

Virtual 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"
  },
  "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
}

Physical Card order Response

{
  "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)

Card order status transitions

Create card order statuses transition diagram

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

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

Example Request

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.

Example Response

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

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",
            "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

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

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

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",
               },
               "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.

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.