Card

Endpoints

GET/v3/spend/profiles/{{profileId}}/cards?pageNumber=1&pageSize=10

GET/v3/spend/profiles/{{profileId}}/cards/{{cardToken}}

POST/v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/status

GET/v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/spending-limits

POST/v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/spending-limits

DELETE/v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/spending-limits/lifetime

GET/v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/spending-permissions

PATCH/v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/spending-permissions

GET/v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/transactions?pageSize=10&pageNumber=1

GET/v3/spend/profiles/{{profileId}}/cards/transactions/{{transactionId}}

POST/

The Card resource

Card Object

{
  "id": 142,
  "profileId": 123456,
  "clientId": "{{clientId}}",
  "cardProgram": {
    "name": "VISA_DEBIT_BUSINESS_UK_1",
    "scheme": "VISA",
    "defaultCurrency": "GBP",
    "cardType" : "VIRTUAL_NON_UPGRADEABLE"
  },
  "billingAddress": {
    "country": "GB",
    "city": "London",
    "postCode": "E1 6JJ",
    "firstLine": "The Tea Building",
    "secondLine": "56 Shoreditch High St",
    "thirdLine": null,
    "state": null,
    "phoneNumber": "+442071111111"
  },
  "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": "Valentin K",
  "phoneNumber": "+442079640500",
  "lifetimeLimit": 100
}

Retrieve all cards by profile

GET /v3/spend/profiles/{{profileId}}/cards?pageSize=10&pageNumber=1

Retrieves the details of all cards that belong to a given profile.

The following parameters are optional:

pageSize - the maximal number of requested cards (used for pagination). This parameter has to be between 10 and 100 inclusive. If omitted the default value 10 is used.
pageNumber - the requested page number starting from 1 (used for pagination). This parameter has to be equal or greater than 1. If omitted the default value of 1 is used.

Both parameters are optional and if not provided their default values will be used.

Response

The returned response contains 2 elements:

totalCount - the total number of cards, this number is never affected by the given pageSize or pageNumber parameters
cards - the list of cards starting from the given pageNumber (please keep in mind that the size of this list is limited by the given pageSize parameter with a default value of 10)

Example Request

curl -X GET 'https://api.sandbox.transferwise.tech/v3/spend/profiles/{{profileId}}/cards?pageSize=10&pageNumber=1 \
     -H 'Authorization: Bearer <your api token>'

Retrieve details of a card by card token

GET /v3/spend/profiles/{{profileId}}/cards/{{cardToken}}

Retrieves the details of one card given its id (also referred as a card token).

Response

Returns a card object.

Example Request

curl -X GET https://api.sandbox.transferwise.tech/v3/spend/profiles/{{profileId}}/cards/{{cardToken}} \
     -H 'Authorization: Bearer <your api token>'

Set card status by card token

PUT /v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/status

Modifies the card status, where the possible new status values are:

ACTIVE - the card is active and usable
FROZEN - the card is temporarily frozen resulting in all authorisation requests to be declined
BLOCKED - the card is irreversibly blocked and is no longer usable

Response

Returns a card object.

Example Request

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

Get card limits

GET /v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/spending-limits

Retrieves the card limits

Response

Returns a set of limits for the card sent.

Example Request

curl -X GET https://api.sandbox.transferwise.tech/v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/spending-limits \
     -H 'Authorization: Bearer <your api token>'

Example Response

{
    "spendings": [
        {
            "type": "ATM_WITHDRAWAL",
            "limits": null
        },
        {
            "type": "ECOM_PURCHASE",
            "limits": null
        },
        {
            "type": "CHIP_WALLET_PURCHASE",
            "limits": null
        },
        {
            "type": "GENERAL",
            "limits": [
                {
                    "type": "LIFETIME",
                    "usage": 2993.76,
                    "threshold": 5000.00,
                    "currency": "AUD",
                    "expiresAt": null
                }
            ]
        }
    ]
}

Set card limits

PATCH /v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/spending-limits

Set or change card spending limits. By default, a new card will have a lifetime limit set to 0.

Request Fields

cardLimitTypetext

Card limit type (TRANSACTION, DAILY, MONTHLY, LIFETIME)

maxLimitAmountdecimal

Limit amount on the card for the specified limit type.

Response

Returns a 200 response - No Content

Example Request

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": <your spending limit value>
        }'

Delete lifetime limit

DELETE /v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/spending-limits/lifetime

Delete the lifetime limit.

Response

Returns a 200 response - No Content

Example Request

curl -X DELETE https://api.sandbox.transferwise.tech/v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/spending-limits/lifetime \
     -H 'Authorization: Bearer <your api token>'

Get card permissions

GET /v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/spending-permissions

Retrieves the card permissions

Response

Returns a set of permissions for the card sent.

The possible type values are:

ECOM
POS_CHIP
POS_MAGSTRIPE
ATM_WITHDRAWAL
POS_CONTACTLESS
MOBILE_WALLETS

Example Request

curl -X GET https://api.sandbox.transferwise.tech/v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/spending-permissions \
     -H 'Authorization: Bearer <your api token>'

Example Response

{
  "permissions": [
    {
      "type": "ECOM",
      "isEnabled": false
    },
    {
      "type": "POS_CHIP",
      "isEnabled": true
    },
    {
      "type": "ATM_WITHDRAWAL",
      "isEnabled": false
    },
    {
      "type": "MOBILE_WALLETS",
      "isEnabled": true
    }
  ]
}

Enable or disable card permissions

PATCH /v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/spending-permissions

Enable or disable a card permission

Request Fields

typetext

Must be one of the permission types as returned in get card permissions

isEnabledboolean

Whether to enable to disable the permission

The possible type values are:

ECOM
POS_CHIP
POS_MAGSTRIPE
ATM_WITHDRAWAL
POS_CONTACTLESS
MOBILE_WALLETS

Response

Returns a 200 response - No Content

Example Request

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>
          }'

Get card transactions

GET /v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/transactions?pageSize=10&pageNumber=1&fromTransactionDate=2022-11-01&toTransactionDate=2022-11-15

You can also use the card transaction webhook instead.

You can follow this guide to simulate various card transactions in the sandbox environment.

Retrieves the card transactions list.

The following parameters are optional:

pageSize - the maximal number of requested card orders (used for pagination). This parameter has to be between 10 and 100 inclusive. If ommitted the default value 10 is used.
pageNumber - the requested page number starting from 1 (used for pagination). This parameter has to be equal or greater than 1. If ommitted the default value of 1 is used.
fromTransactionDate - the starting date of the date filter. The date format is YYYY-MM-DD.
toTransactionDate - the end date of the date filter. The date format is YYYY-MM-DD.

The possible type values are:

ACCOUNT_CREDIT - Receiving money on the card, excluding Visa OCT or Mastercard MoneySend
ACCOUNT_FUNDING - Sending money to another card or e-wallet
CASH_ADVANCE - Cash disbursement
CASH_WITHDRAWAL - ATM withdrawal
CHARGEBACK - Currently unused. Reserved for future use.
CREDIT_TRANSACTION - Visa OCT and Mastercard MoneySend
ECOM_PURCHASE - Online purchase
POS_PURCHASE - Purchase via a POS Terminal
REFUND - Partial or full refund of an existing card transaction

The possible state values are:

IN_PROGRESS - The transaction has been authorized but not captured.
COMPLETED - The transaction has been captured and/or settled.
DECLINED - The transaction has been declined.
CANCELLED - The transaction has been cancelled.
UNKNOWN - Default fallback status if the state can't be confirmed.

When a refund happens, a separate transaction will be added with a REFUND transaction type.

Response

Returns a set of transactions for the card.

Example Request

curl -X GET https://api.sandbox.transferwise.tech/v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/transactions?pageSize=10&pageNumber=1&fromTransactionDate=2022-11-01&toTransactionDate=2022-11-15 \
     -H 'Authorization: Bearer <your api token>'

Example Response

{
  "totalCount": 1,
  "transactions": [
    {
      "id": "342671",
      "cardToken": "590b5b72-223d-45f9-b840-0ad4a4f80937",
      "type": "ECOM_PURCHASE",
      "declineReason": null,
      "createdDate": "2022-11-28T08:17:54.241236Z",
      "state": "IN_PROGRESS",
      "cardLastDigits": "3086",
      "transactionAmount": {
        "amount": 1.5,
        "currency": "SGD"
      },
      "fees": [],
      "transactionAmountWithFees": {
        "amount": 1.5,
        "currency": "SGD"
      },
      "merchant": {
        "id": "332512",
        "name": "Test Payment",
        "location": {
          "country": "France",
          "city": "Rouen",
          "zipCode": "00000",
          "region": null,
          "state": null
        },
        "category": {
          "name": "RMiscellaneousAndSpecial",
          "code": "5999",
          "description": "5999 R Miscellaneous and Special"
        }
      },
      "authorisationMethod": "MANUAL_ENTRY",
      "balanceTransactionId": 2598366,
      "debits": [
        {
          "balanceId": 52832,
          "debitedAmount": {
            "amount": 1.06,
            "currency": "EUR"
          },
          "forAmount": {
            "amount": 1.5,
            "currency": "SGD"
          },
          "rate": 1.43073,
          "fee": {
            "amount": 0.01,
            "currency": "EUR"
          }
        }
      ]
    }
  ]
}

Get card transaction by ID

GET /v3/spend/profiles/{{profileId}}/cards/transactions/{{transactionId}}

Retrieve a card transaction by transaction id.

The possible type values are:

ACCOUNT_CREDIT - Receiving money on the card, excluding Visa OCT or Mastercard MoneySend
ACCOUNT_FUNDING - Sending money to another card or e-wallet
CASH_ADVANCE - Cash disbursement
CASH_WITHDRAWAL - ATM withdrawal
CHARGEBACK - Currently unused. Reserved for future use.
CREDIT_TRANSACTION - Visa OCT and Mastercard MoneySend
ECOM_PURCHASE - Online purchase
POS_PURCHASE - Purchase via a POS Terminal
REFUND - Partial or full refund of an existing card transaction

The possible state values are:

IN_PROGRESS - The transaction has been authorized but not captured.
COMPLETED - The transaction has been captured and/or settled.
DECLINED - The transaction has been declined.
CANCELLED - The transaction has been cancelled.
UNKNOWN - Default fallback status if the state can't be confirmed.

When a refund happens, a separate transaction will be added with a REFUND transaction type.

Example Request

curl -X GET 'https://api.sandbox.transferwise.tech/v3/spend/profiles/{{profileId}}/cards/transactions/{{transactionId}}
     -H 'Authorization: Bearer {{API token}}'

Example Response

{
  "id": "342671",
  "cardToken": "590b5b72-223d-45f9-b840-0ad4a4f80937",
  "type": "ECOM_PURCHASE",
  "declineReason": null,
  "createdDate": "2022-11-28T08:17:54.241236Z",
  "state": "IN_PROGRESS",
  "cardLastDigits": "3086",
  "transactionAmount": {
    "amount": 1.5,
    "currency": "SGD"
  },
  "fees": [],
  "transactionAmountWithFees": {
    "amount": 1.5,
    "currency": "SGD"
  },
  "merchant": {
    "id": "332512",
    "name": "Test Payment",
    "location": {
      "country": "France",
      "city": "Rouen",
      "zipCode": "00000",
      "region": null,
      "state": null
    },
    "category": {
      "name": "RMiscellaneousAndSpecial",
      "code": "5999",
      "description": "5999 R Miscellaneous and Special"
    }
  },
  "authorisationMethod": "MANUAL_ENTRY",
  "balanceTransactionId": 2598366,
  "debits": [
    {
      "balanceId": 52832,
      "debitedAmount": {
        "amount": 1.06,
        "currency": "EUR"
      },
      "forAmount": {
        "amount": 1.5,
        "currency": "SGD"
      },
      "rate": 1.43073,
      "fee": {
        "amount": 0.01,
        "currency": "EUR"
      }
    }
  ]
}

Retrieve sensitive card details

The sensitive card details endpoint allows you to retrieve card data such as Primary Account Number, expiry date, CVV and PIN.

Wise is a PCI DSS compliant provider, and stores all of your Cards API data securely. The scope for PCI compliance depends on your use case and will impact how you integrate with Cards API.

Due to the sensitivity of this endpoint, we only make the documentation available to specific partners who require it. To know more, reach out to your implementation manager.