Card
These APIs are designed for you to be able to manage your consumer's cards easily, allowing you to set spending limits, modify the status of the cards, or view a list of cards that belong to a specific profile.
The primary resource that you will be interacting with when managing your user's cards.
Token
Profile ID
Client ID
Status Text
Name of the card holder
Date when the card will expire
Last 4 digits of the card number
Bank identification number of the card
Phone number of the card
Name of the card program
Scheme of the card program. E.g. VISA
or MASTERCARD
Default currency of the card. E.g. GBP
Type of the card. E.g. PHYSICAL
or VIRTUAL
Time when the card is created
Time when the card was last modified
Table of available card status and descriptions
Code | Description |
---|---|
ACTIVE | Card is active and can be used |
INACTIVE | Physical card has not been activated |
BLOCKED | Card is blocked and cannot be reversed back to any state |
FROZEN | Card is “blocked” but temporarily |
PARTNER_SUSPENDED | Card is suspended by Wise temporarily due to e.g. fraud reasons. |
EXPIRED | Card is expired |
PURGED | The cardholder data (e.g. PAN, PIN) has been purged after the retention period (555 days after the card's expiry date) |
{"token": "ca0c8154-1e14-4464-a1ce-dcea7dc3de52","profileId": 123456,"clientId": "wise_api_docs","status": {"value": "ACTIVE"},"cardHolderName": "John Smith","expiryDate": "2028-05-31T00:00:00Z","lastFourDigits": "6320","bankIdentificationNumber": "459661","phoneNumber": "+441234567890","cardProgram": {"name": "VISA_DEBIT_BUSINESS_UK_1","scheme": "VISA","defaultCurrency": "GBP","cardType" : "VIRTUAL_NON_UPGRADEABLE"},"creationTime": "2022-05-31T01:43:24.596321434Z","modificationTime": "2022-05-31T01:43:24.596321825Z"}
The Spending resource returns a set of limits for each type of transaction that the card can make. This has been deprecated and you can access the redesigned card limits here.
The type of transaction. One of ATM_WITHDRAWAL
, ECOM_PURCHASE
, CHIP_WALLET_PURCHASE
or GENERAL
A list of limits assigned to each transaction type
{"type": "GENERAL","limits": [{"type": "LIFETIME","usage": 2993.76,"threshold": 5000.00,"currency": "AUD","expiresAt": null}]}
The Limits resource returns information on the existing spending limits that are configured on your user's cards. This has been deprecated and you can access the redesigned card limits here.
The type of limit. One of DAILY
, WEEKLY
, MONTHLY
, LIFETIME
The total authorised amount on the card till date
The limit configured on the specific transaction type
The currency code for the configured limits
The time when the limit expires. If set to null
, the limit is permanent. ISO-8601 timestamp with timezone (Z)
{"type": "LIFETIME","usage": 2993.76,"threshold": 5000.00,"currency": "AUD","expiresAt": null}
The Permissions resource returns information on the existing permissions that are configured on your user's cards.
The type of transaction. One of ECOM
, POS_CHIP
, ATM_WITHDRAWAL
, MOBILE_WALLETS
A flag indicated if the permissions for a specific type
are enabled
{"type": "ECOM","isEnabled": false}
Wise is a PCI DSS compliant provider, and stores all of your cards' data securely. The scope for PCI compliance depends on your use case and will impact how you integrate with Wise.
Sensitive card details endpoints allows you to retrieve card data such as Primary Account Number, CVV or PIN. You can use it to set a pin if required in the card order flow. For all sensitive card details endpoints, we are using client-side encryption. Please follow the flow detailed in client-side encryption flow.
Fetch RSA encryption key
This endpoint is used to fetch our RSA public key. This key is required in the client-side encryption flow.
Response
Version of the key
The RSA public key
curl -X GET https://twcard.sandbox.transferwise.tech/twcard-data/v1/clientSideEncryption/fetchEncryptingKey-H 'Authorization: Bearer <your api token>'
{"version": 1,"key": "<encryption key>"}
Get Card Sensitive Details
This endpoint is used to fetch the card Primary Account Number, security code (CVV2), expiry date and cardholder name. It requires an api token
and a card token
set in the headers.
Request
The version of the key to use. It is always set to 1.
Your JWE payload.
Response
An arbitrary UUID issued from the cryptographic communication
Your card CVV2
Your card Primary Account Number
Your card expiry date
Name on the card
curl -X POST https://twcard.sandbox.transferwise.tech/twcard-data/v1/sensitive-card-data/details-H 'Authorization: Bearer <your api token>'-H 'x-tw-twcard-card-token: <your card token>'-d '{"keyVersion": 1,"encryptedPayload": <your JWE>}'
{"nonce": "33d51227-9ad6-4624-b4b7-7853b56076dd","cvv2": "111","pan": "4396910000012345","expiryDate": "10/31","cardholderName": "John Smith"}
Get Card PIN
This endpoint is used to fetch the card PIN. It requires an api token
and a card token
set in the headers.
Request
The version of the key to use. It is always set to 1.
Your JWE payload.
Response
An arbitrary UUID issued from the cryptographic communication
Your card pin
curl -X POST https://twcard.sandbox.transferwise.tech/twcard-data/v1/sensitive-card-data/pin-H 'Authorization: Bearer <your api token>'-H 'x-tw-twcard-card-token: <your card token>'-d '{"keyVersion": 1,"encryptedPayload": <your JWE>}'
{"nonce": "33d51227-9ad6-4624-b4b7-7853b56076dd","pin": "1234",}
This endpoint will be accessible for partners that require to set a PIN on card order flow. It requires an api token
and a card order id
set in the headers.
Request
The version of the key to use. It is always set to 1.
Your JWE payload.
Response
The card order id on which the pin is set
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>}'
{"cardOrderId": "<your card order id>",}
POST /v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/reset-pin-count
If the wrong PIN have been entered more that 3 times, future transactions on the card will be blocked with PIN_ENTRY_TRIES_EXCEEDED
error message.
To unblock your transactions, use this endpoint to reset the PIN count to 0.
Additionally, there are instances where you will also need to reset the PIN count directly at the ATM.
Response
200 - No Content
curl -X POST https://api.sandbox.transferwise.tech/v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/reset-pin-count \-H 'Authorization: Bearer <your api token>' \-H 'Content-Type: application/json' \
GET /v3/spend/profiles/{{profileId}}/cards?pageSize=10&pageNumber=1
Returns a list of cards that belong to a specific profileId
.
The maximum number of cards 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 cards. The number has to be greater than 1, and will default to 1
curl -X GET https://api.sandbox.transferwise.tech/v3/spend/profiles/{{profileId}}/cards?pageSize=10&pageNumber=1 \-H 'Authorization: Bearer <your api token>'
Response
The total number of cards for this profileId
A collection of Cards for this profileId
{"cards": [{"token": "ca0c8154-1e14-4464-a1ce-dcea7dc3de52","profileId": 123456,"clientId": "wise_api_docs","status": {"value": "ACTIVE"},"cardHolderName": "John Smith","expiryDate": "2028-05-31T00:00:00Z","lastFourDigits": "6320","bankIdentificationNumber": "459661","phoneNumber": "+441234567890","cardProgram": {"name": "VISA_DEBIT_BUSINESS_UK_1","scheme": "VISA","defaultCurrency": "GBP","cardType": "VIRTUAL_NON_UPGRADEABLE"},"creationTime": "2022-05-31T01:43:24.596321434Z","modificationTime": "2022-05-31T01:43:24.596321825Z"}],"totalCount": 1}
GET /v3/spend/profiles/{{profileId}}/cards/{{cardToken}}
Retrieves a card based on the cardToken
provided.
curl -X GET https://api.sandbox.transferwise.tech/v3/spend/profiles/{{profileId}}/cards/{{cardToken}} \-H 'Authorization: Bearer <your api token>'
Response
Returns a Card resource.
{"token": "ca0c8154-1e14-4464-a1ce-dcea7dc3de52","profileId": 123456,"clientId": "wise_api_docs","status": {"value": "ACTIVE"},"cardHolderName": "John Smith","expiryDate": "2028-05-31T00:00:00Z","lastFourDigits": "6320","bankIdentificationNumber": "459661","phoneNumber": "+441234567890","cardProgram": {"name": "VISA_DEBIT_BUSINESS_UK_1","scheme": "VISA","defaultCurrency": "GBP","cardType" : "VIRTUAL_NON_UPGRADEABLE"},"creationTime": "2022-05-31T01:43:24.596321434Z","modificationTime": "2022-05-31T01:43:24.596321825Z"}
PUT /v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/status
Modifies the card status.
The status that you want to update the card to. One of ACTIVE
, FROZEN
or BLOCKED
The definition for the status values are:
ACTIVE
- the card is active and usableFROZEN
- the card is temporarily frozen resulting in all authorisation requests to be declinedBLOCKED
- the card is irreversibly blocked and is no longer usable
curl -X PUT https://api.sandbox.transferwise.tech/v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/status \-H 'Authorization: Bearer <your api token>' \-H 'Content-Type: application/json' \-d '{"status": "ACTIVE"}'
Response
Returns a Card object.
{"token": "ca0c8154-1e14-4464-a1ce-dcea7dc3de52","profileId": 123456,"clientId": "wise_api_docs","status": {"value": "ACTIVE"},"cardHolderName": "John Smith","expiryDate": "2028-05-31T00:00:00Z","lastFourDigits": "6320","bankIdentificationNumber": "459661","phoneNumber": "+441234567890","cardProgram": {"name": "VISA_DEBIT_BUSINESS_UK_1","scheme": "VISA","defaultCurrency": "GBP","cardType" : "VIRTUAL_NON_UPGRADEABLE"},"creationTime": "2022-05-31T01:43:24.596321434Z","modificationTime": "2022-05-31T01:43:24.596321825Z"}
GET /v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/spending-limits
Retrieves the spending limits set for a specific card. This has been deprecated and you can access the redesigned card limits here.
curl -X GET https://api.sandbox.transferwise.tech/v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/spending-limits \-H 'Authorization: Bearer <your api token>'
Response
Fields | Type | Definition |
---|---|---|
spendings | List<Spending> | A collection of Spending resources |
{"spendings": [{"type": "GENERAL","limits": [{"type": "TRANSACTION","usage": 0,"threshold": 100.00,"currency": "GBP","expiresAt": null},{"type": "DAILY","usage": 0,"threshold": 500.00,"currency": "GBP","expiresAt": "2023-07-17T23:00:00Z"},{"type": "MONTHLY","usage": 0,"threshold": 1000.00,"currency": "GBP","expiresAt": "2023-07-31T23:00:00Z"},{"type": "LIFETIME","usage": 0,"threshold": 100.00,"currency": "GBP","expiresAt": null}]}]}
PATCH /v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/spending-limits
Set or change card spending limits. Card limits cannot surpass profile level limits. See Retrieve spending limits for a profile. This has been deprecated and you can access the redesigned card limits here.
The type of limit to set. One of TRANSACTION
, DAILY
, MONTHLY
, LIFETIME
The maximum amount allowed to be spent for the chosen type
curl -X PATCH https://api.sandbox.transferwise.tech/v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/spending-limits \-H 'Authorization: Bearer <your api token>' \-H 'Content-Type: application/json' \-d '{"cardLimitType": "LIFETIME","maxLimitAmount": 5000.00}'
Response
Returns a 200 - No Content
DELETE /v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/spending-limits/{{cardLimitType}}
Delete the limits for a specific card. This has been deprecated and you can access the redesigned card limits here.
The type of limit to set. One of TRANSACTION
, DAILY
, MONTHLY
, LIFETIME
Response
Returns a 200 - No Content
curl -X DELETE https://api.sandbox.transferwise.tech/v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/spending-limits/{{cardLimitType}} \-H 'Authorization: Bearer <your api token>'
GET /v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/spending-permissions
Retrieves permissions for a card.
Response
A collection of Permissions
curl -X GET https://api.sandbox.transferwise.tech/v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/spending-permissions \-H 'Authorization: Bearer <your api token>'
{"permissions": [{"type": "ECOM","isEnabled": false},{"type": "POS_CHIP","isEnabled": true},{"type": "ATM_WITHDRAWAL","isEnabled": false},{"type": "MOBILE_WALLETS","isEnabled": true}]}
PATCH /v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/spending-permissions
Enable or disable permissions on a card.
One of ECOM
, POS_CHIP
, POS_MAGSTRIPE
,ATM_WITHDRAWAL
, POS_CONTACTLESS
,MOBILE_WALLETS
A flag indicating if the permissions for a specific type
are enabled
Response
Returns a 200 - No Content
curl -X PATCH https://api.sandbox.transferwise.tech/v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/spending-permissions \-H 'Authorization: Bearer <your api token>'--d '{"type": <permission type>,"isEnabled": <true or false>}'
PUT /v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/phone-number
Update the phone number of a card. The new phone number must be a valid phone number.
Must be a valid phone number prefixed with + and country code. An example of a valid phone number would be +6588888888
curl -X PUT 'https://api.sandbox.transferwise.tech/v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/phone-number' \--H 'Authorization: Bearer <your api token>' \--d '{"phoneNumber": "+6588888888}'
Response
The card token that you are modifying
The profile ID that the card is linked to
The new phone number associated with the card
{"token": "12345-12345-12345-12345","profileId": 30000000,"phoneNumber": "+6588888888"}