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
GET/v3/spend/profiles/{{profileId}}/card-orders/{{cardOrderId}}/requirements
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 Card Order resource

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

cardType (deprecated)text

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.

deliveryEstimatetext (ISO-8601)

The estimated time when the card will be delivered. There are few scenarios to be mindful of:

  1. For virtual card the delivery estimate will be close to the creationTime. As it does not require delivery.
  2. For physical card in PLACED status, the delivery estimate is calculated assuming that the order requirements will be fulfilled today (refreshed daily).
  3. For physical card after PLACED status, we provide a best effort estimation, and it should not be used as delivery timing as we will have separate delivery tracking (subject to region availability) for physical card that is coming soon.
deliveryDetails (optional)DeliveryDetails

Checkout DeliveryDetails for more information.

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"
  },
  "address": {
    "firstLine": "56 Shoreditch High St",
    "secondLine": "The Tea Bldg",
    "thirdLine": null,
    "city": "London",
    "postCode": "E1 6JJ",
    "state": null,
    "country": "GB"
  },
  "cardType": "PHYSICAL", // 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": "PRODUCED",
  "cardHolderName": "John Smith",
  "phoneNumber": "+441234567890",
  "lifetimeLimit": 100,
  "deliveryEstimate": "2023-10-30T07:11:00.848681Z",
  "deliveryDetails": {
    "deliveryVendor": "DHL",
    "trackingUrl": "https://www.dhl.com/gb-en/home/tracking/tracking-express.html?submit=1&tracking-id=1999473803",
    "trackingNumber": "1999473803"
  }
}

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 'status' values are:

  • 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

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.

nametext

The name of the card program

schemetext

The network of the card program. One of MASTERCARD or VISA

defaultCurrencytext

The default currency assigned to the card program

cardTypetext

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 Address Resource

To create a card order, make sure to follow country specific address fields and validation. If your country is not listed in the dropdown below, select Other.

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.

Please select a country:

The Delivery Details Resource

Tracking details can only be known for physical card when the status is PRODUCED or COMPLETED.

Delivery tracking details are currently available only for some regions such as Brazil.

The local post is usually used for standard deliveries. Tracking details are not available for this type of shipping method, so the value of deliveryDetails is null.

Resource
deliveryVendortext

The name of the delivery vendor

trackingUrltext

The url to track the card delivery

trackingNumbertext

The tracking number of the card delivery

Delivery details request
{
  "deliveryDetails": {
    "deliveryVendor": "DHL",
    "trackingUrl": "https://www.dhl.com/gb-en/home/tracking/tracking-express.html?submit=1&tracking-id=1999473803",
    "trackingNumber": "1999473803"
  }
}

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"
    }
  ]
}

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.

This request requires an extra field in the header, X-idempotence-uuid. This should be generated and used for any subsequent retries in the event that the initial request fails.
Request
programtext

The name of the card program

cardHolderNametext

The card holder's name

embossedNametext

The card holder's name to print on the card (physical card only). The field length should be between 1 and 22 characters (spaces included).

phoneNumbertext

Must be a valid phone number prefixed with + and country code. An example of a valid phone number would be +6588888888

addressAddress

The card holder's billing address or delivery address. See Address

lifetimeLimit (optional)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.

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"
            },
            "lifetimeLimit": 100,
         }'

Get card order requirements

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

Retrieve card requirements for a cardOrderId. A card order needs all the requirements' status to be COMPLETED to proceed.

Example Request
curl -X GET https://api.sandbox.transferwise.tech/v3/spend/profiles/{{profileId}}/card-orders/{{cardOrderId}}/requirements \
     -H 'Authorization: Bearer <your api token>'

Response

The types of requirement are:

  • PIN (optional): Set a pin on a physical card order. Contact the team if you need this feature.
  • VERIFICATION: Verify your customer by providing KYC evidences. Refer to the KYC guide
  • ADDRESS: Provide a valid address for your card order. Refer to address validation

A requirement status has the following values:

  • NOT_INITIATED
  • NEEDS_ACTION
  • PENDING
  • COMPLETED
  • FAILED
Example Response
{
    "requirements": [
        {
            "type": "PIN",
            "status": "NOT_INITIATED"
        },
        {
            "type": "VERIFICATION",
            "status": "PENDING"
        },
        {
            "type": "ADDRESS",
            "status": "COMPLETED"
        }
    ]
}

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

Request
pageSize (optional)integer

The maximum number of card orders to return per page. This number can be between 10 - 100, and will default to 10

pageNumber (optional)integer

The page number to retrieve the next set of card orders. The number has to be greater than 1, and will default to 1

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

Request
totalCountinteger

The total number of card orders for this profileId

cardOrderslist of card orders

A collection of CardOrder for this profileId

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