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.
ID of the card order
Profile ID
Client ID
Card program of the card holder.
Address set during card order
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 status 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.
The estimated time when the card will be delivered. There are few scenarios to be mindful of:
- For virtual card the delivery estimate will be close to the creationTime. As it does not require delivery.
- For physical card in
PLACED
status, the delivery estimate is calculated assuming that the order requirements will be fulfilled today (refreshed daily). - 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.
Checkout delivery details for more information.
{"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"},"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"}}
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.
The name of the card program
The network of the card program. One of MASTERCARD
or VISA
The default currency assigned to the card program
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"}]}
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
.
The name of the delivery vendor
The url to track the card delivery
The tracking number of the card delivery
{"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 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 requirementsREQUIREMENTS_FULFILLED
- The card order has fulfilled all the requirements and the card should be generated in a short whileCARD_DETAILS_CREATED
- The card has been generatedPRODUCED
- 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 completedCANCELLED
- The card order has been cancelled. This can happen if you reach out to Wise Support to cancel a card orderRETURNED
- Delivery failed, the physical card has been returned and will be blocked (physical card only)
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
.
For virtual cards, the address field will be used as a billing address. It will be used for AVS checks in countries where is it required.
For physical cards, the address field will be used as a delivery address. It will be used to deliver your card as well as AVS checks in countries where is it required.
Please select a country:
POST /v3/spend/profiles/{{profileId}}/card-orders
The program
field value is retrieved from retrieve all card programs endpoint.
The name of the card program
The card holder's name
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).
Must be a valid phone number prefixed with + and country code. An example of a valid phone number would be +6588888888
The card holder's billing address or delivery address. See address
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.
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}'
Returns a Card Order
{"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"},"cardToken": "4dc0be88-903f-49e4-8237-735f1139e3dd","replacesCard": null,"creationTime": "2024-09-19T06:49:49.145021Z","modificationTime": "2024-09-19T06:49:49.145021Z","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"}}
GET /v3/spend/profiles/{{profileId}}/card-orders/{{cardOrderId}}
Retrieve 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.
{"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"},"cardToken": "4dc0be88-903f-49e4-8237-735f1139e3dd","replacesCard": null,"creationTime": "2024-07-22T07:29:33.720717Z","modificationTime": "2024-08-29T15:28:31.078399Z","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"}}
Retrieve a list of card orders created for the profileId
specified in the endpoint.
GET /v3/spend/profiles/{{profileId}}/card-orders?pageSize=10&pageNumber=1
The maximum number of card orders to return per page. This number can be between 10 - 100, and will default to 10
The page number to retrieve the next set of card orders. The number has to be greater or equal to 1, and will default to 1
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
totalCount
is the total number of card orders for this profile.
Returns collection of card order for this profileId
{"totalCount": 5,"cardOrders": [{"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"},"cardToken": null,"replacesCard": null,"creationTime": "2024-07-22T07:29:33.720717Z","modificationTime": "2024-08-29T15:28:31.078399Z","status": "REQUIREMENTS_FULFILLED","cardHolderName": "John Smith","phoneNumber": "+441234567890","lifetimeLimit": 100}]}
GET /v3/spend/profiles/{{profileId}}/card-orders/availability
Retrieve 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 card program resources available to the profileId
.
{"cardPrograms": [{"name": "VISA_DEBIT_BUSINESS_UK_1_CARDS_API","scheme": "VISA","defaultCurrency": "GBP","cardType" : "VIRTUAL_NON_UPGRADEABLE"}]}
GET /v3/spend/profiles/{{profileId}}/card-orders/{{cardOrderId}}/requirements
Retrieve all card requirements for a cardOrderId
. A valid card order needs all its requirements status to be COMPLETED
.
curl -X GET https://api.sandbox.transferwise.tech/v3/spend/profiles/{{profileId}}/card-orders/{{cardOrderId}}/requirements \-H 'Authorization: Bearer <your api token>'
Response
The type of requirements are:
PIN (optional)
: Set a pin on a virtual or physical card order. Contact the team if you need this feature.VERIFICATION
: Verify your customer by providing KYC evidences. Refer to the KYC guideADDRESS
: 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
{"requirements": [{"type": "PIN","status": "NOT_INITIATED"},{"type": "VERIFICATION","status": "PENDING"},{"type": "ADDRESS","status": "COMPLETED"}]}
POST /v3/spend/address/validate
To create a card order, make sure to follow country specific address fields and validation. Find more about each country specifics in this guide.
For virtual cards, the address field will be used as a billing address. It will be used for AVS checks in countries where is it required.
For physical cards, the address field will be used as a delivery address. It will be used to deliver your card and for AVS checks in countries where is it required.
curl -X POST 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"}'
This endpoint will be accessible for partners that require to set a PIN during the card order flow.
Please follow this guide to use this endpoint.
To use this endpoint, make sure to set the api token
and the card order id
in the headers.
Request
The version of the key to use. It is always set to 1.
Your JWE payload.
curl -X POST https://twcard.sandbox.transferwise.tech/twcard-data/v1/sensitive-card-data/preset-pin-H 'Authorization: Bearer <your api token>'-H 'x-tw-twcard-order-id: <your card order ID>'-d '{"keyVersion": 1,"encryptedPayload": <your JWE>}'
Response
Returns the card order ID.
{"cardOrderId": "<your card order ID>",}