Skip to content

Wise Platform API

The Wise Platform API is a REST-based interface that enables programmatic access to Wise's payment infrastructure. All endpoints return JSON-formatted responses and use standard HTTP methods and status codes.

New to wise?

We strongly recommend first reading our Getting Started Guide to help you set up credentials and make your first call.

Before you begin

To use this API reference effectively, you should have:

  • Received Valid API credentials from Wise (Client ID and Client Secret)
  • Understand OAuth 2.0 authentication
  • Be familiar with RESTful API concepts

Core API resources

ResourcePurpose
QuoteExchange rate and fee calculations
RecipientBeneficiary account management
TransferPayment creation and execution
BalanceMulti-currency account operations
ProfileAccount ownership details
RateCurrent and historical exchange rates

Not sure which workflow to build?
Start with our Integration Guides for step-by-step implementation examples.

Languages
Servers
Production Environment
https://api.wise.com/
Sandbox Environment
https://api.wise-sandbox.com/

3D Secure Authentication

To manage certain aspects of the 3D Secure (3DS) authentication, you will need to integrate with the following APIs.

Operations

Activity

Activity represents a snapshot of a performed action for a profile.

Operations

Additional Customer Verification

In certain situations, additional evidence is required to verify customers and ensure we’re compliant with the KYC regulations.

Additional Verification APIs support a list of evidences that can be found in the Supported Evidences guide.

If you use the Customer Account with Partner KYC model and your customers are primarily based in the EU, refer to this Onboarding EU customers guide for instructions on how to use these APIs.

If you use the Customer Account with Partner KYC model and you are onboarding high risk business customers based primarily based in the US, refer to this Onboarding High Risk US Businesses guide for instructions on how to use these APIs.

Operations

Address

Manage physical addresses associated with user profiles.

Address requirements vary by country — use the address requirements endpoints to dynamically discover which fields are needed before creating an address.

SchemasOperations

Balance

Create and manage balance accounts within a multi-currency account.

Each profile can hold multiple balance accounts in different currencies. A STANDARD balance is limited to one per currency, while SAVINGS balances (Jars) allow multiple in the same currency. Creating the first balance for a profile automatically creates the multi-currency account.

Balances include an investmentState field. Only balances with NOT_INVESTED can be operated on via the API. Invested balances should be shown but not actionable.

For a complete guide on multi-currency accounts, see Multi-Currency Accounts.

SchemasOperations

Balance Statement

Balance statements contain transactional activities on a Wise Multi-Currency Account, including deposits, withdrawals, conversions, card transactions, and fees.

Statements can be retrieved in multiple formats: JSON, CSV, PDF, XLSX, CAMT.053, MT940, or QIF.

Operations

Bank Account Details

Bank account details allow users to receive money into their Wise Multi-Currency Account. Each currency balance can have local bank details (for domestic payments) and international bank details (for SWIFT payments) where available.

Bank account details can be retrieved for existing balances, or new details can be ordered for currencies where they're available but not yet issued.

SchemasOperations

Batch Group

A batch group is a named collection of up to 1000 transfers that can be managed as a single unit. Batch groups are primarily used for funding multiple transfers with a single payment.

Workflow:

  1. Create a batch group with a source currency
  2. Add transfers to the group (up to 1000)
  3. Complete the batch group to close it for modifications
  4. Fund the batch group from a balance or via direct debit

Individual transfers in the group follow standard transfer lifecycle and can be tracked separately.

SchemasOperations

Bulk Settlement

Bulk settlement allows partners to settle multiple transfers in a single bank transfer at the end of a settlement period. This model splits transfer creation/funding from final settlement, allowing Wise to process transfers before receiving funds based on a partner's guarantee.

Use the settlement journal endpoint to submit a list of transfers to be settled, along with the settlement reference that matches your bank transfer payment.

Operations

Card

Manage your customers' cards programmatically. These APIs allow you to retrieve card details, control card status, manage spending permissions, and access sensitive card data securely.

Key capabilities:

  • List and retrieve card details for a profile
  • Update card status (active, frozen, blocked)
  • Control spending permissions (e-commerce, ATM, contactless, etc.)
  • Access sensitive card data (PAN, CVV, PIN) via encrypted JWE payloads

Sensitive card details: Wise is a PCI DSS compliant provider and stores all card data securely. The scope for PCI compliance depends on your use case and will impact how you integrate. For all sensitive card details endpoints, follow the detailed guide.

For ordering new cards, see the Card Order API. For transaction history, see the Card Transaction API.

SchemasOperations

Card Kiosk Collection

These APIs are designed to allow you to print and encrypt your card directly from a kiosk machine. The card information will be sent to our card manufacturer to configure and print the card on-site on a kiosk machine.

The card printing process will automatically begin once the request is received by our card manufacturer.

During the printing process, you will be notified via webhook about any card production status change.

Before using these APIs, make sure to read the guide on kiosk collection.

Please reach out to your Implementation Manager for more information on these APIs.

Testing: In the sandbox environment, use the card production simulation API to test your integration with various production statuses and error scenarios.

Production status flow

These statuses represent the lifecycle of a card production:

  • READY - Card is ready for production. The produce card endpoint can be called.
  • IN_PROGRESS - Card is being produced at the kiosk machine (chip encryption and printing in progress).
  • PRODUCED - Card has been successfully produced and collected from the kiosk. This is a final state.
  • PRODUCTION_ERROR - Card production failed. Check the errorCode to identify the issue, resolve it, then retry using the produce card endpoint.

A card with production status PRODUCED will trigger an asynchronous call to update the associated card order to PRODUCED status.

Card production status flow

Operations

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.

On production, each personal profile can order at most 1 physical card and 3 virtual cards. On sandbox, we allow up to 10 physical cards and 30 virtual cards for testing purpose. However, no more than 3 virtual cards can be ordered per day. This limit includes cards and card orders.

Card order status flow

The card order response will contain the status field. The initial status is PLACED or REQUIREMENTS_FULFILLED depending on the requirement fulfillment state:

  • 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 state machine

SchemasOperations

Card Order

idinteger(int64)

ID of the card order.

Example: 142
profileIdinteger(int64)

Profile ID.

Example: 123456
clientIdstring

Client ID.

Example: "your-client-id"
cardProgramobject

The card program associated with this card order. 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.

cardProgram.​namestring

The name of the card program.

Example: "VISA_DEBIT_BUSINESS_UK_1_PHYSICAL_CARDS_API"
cardProgram.​schemestring

The network of the card program:

  • MASTERCARD
  • VISA
Enum"MASTERCARD""VISA"
Example: "VISA"
cardProgram.​defaultCurrencystring

The default currency assigned to the card program.

Example: "GBP"
cardProgram.​cardTypestring

The type of the card:

  • VIRTUAL_NON_UPGRADEABLE
  • PHYSICAL
Enum"VIRTUAL_NON_UPGRADEABLE""PHYSICAL"
Example: "PHYSICAL"
addressobject

Address set during card order. Fields vary by country. See the card address validation guide for country-specific fields and validation rules.

address.​firstLinestring

Card holder's address.

Example: "56 Shoreditch High St"
address.​secondLinestring or null

Card holder's address.

Example: "The Tea Bldg"
address.​thirdLinestring or null

Card holder's address.

Example: null
address.​citystring

Card holder's city.

Example: "London"
address.​postCodestring

Card holder's postal code.

Example: "E1 6JJ"
address.​statestring or null

Card holder's state.

Example: null
address.​countrystring

Card holder's country (ISO 3166-1 alpha-2).

Example: "GB"
address.​property name*anyadditional property
cardTokenstring or null

Token of the card associated with card order. Nullable.

Example: "4dc0be88-903f-49e4-8237-735f1139e3dd"
replacesCardstring or null

A string for replacement card. Not supported at the moment.

Example: null
creationTimestring(date-time)

Time when the card order is created.

Example: "2023-07-31T01:43:24.596321434Z"
modificationTimestring(date-time)

Time when the card order was last modified.

Example: "2023-07-31T01:43:24.596321825Z"
statusstring

Status of the card order. See card order status flow for details.

Enum"PLACED""REQUIREMENTS_FULFILLED""CARD_DETAILS_CREATED""PRODUCED""COMPLETED""CANCELLED""RETURNED"
Example: "PRODUCED"
cardHolderNamestring

Name of the card holder.

Example: "John Smith"
phoneNumberstring

Phone number associated with the card order.

Example: "+441234567890"
lifetimeLimitnumber or null

Maximum amount of spending on the card once issued. Nullable.

Example: 100
deliveryEstimatestring(date-time)

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.
Example: "2023-10-30T07:11:00.848681Z"
deliveryDetailsobject

Delivery details of a physical card order. For virtual cards, this value is null.

deliveryDetails.​deliveryOptionstring

The delivery option used on the card order.

Enum"POSTAL_SERVICE_STANDARD""POSTAL_SERVICE_WITH_TRACKING""KIOSK_COLLECTION"
Example: "POSTAL_SERVICE_WITH_TRACKING"
deliveryDetails.​deliveryVendorstring or null

The name of the delivery vendor.

Example: "DHL"
deliveryDetails.​trackingUrlstring or null

The URL to track the card delivery.

Example: "https://www.dhl.com/gb-en/home/tracking/tracking-express.html?submit=1&tracking-id=1999473803"
deliveryDetails.​trackingNumberstring or null

The tracking number of the card delivery.

Example: "1999473803"
{
  "id": 142,
  "profileId": 123456,
  "clientId": "your-client-id",
  "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": {
    "deliveryOption": "POSTAL_SERVICE_WITH_TRACKING",
    "deliveryVendor": "DHL",
    "trackingUrl": "https://www.dhl.com/gb-en/home/tracking/tracking-express.html?submit=1&tracking-id=1999473803",
    "trackingNumber": "1999473803"
  }
}

Create a card order

Request

Creates a new card order. The program field value is retrieved from the retrieve all card programs endpoint.

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.

When you issue a card under a business profile, the cardholder will automatically default to the business representative.

If the cardholder is not the business representative, create a cardholder personal profile and add the profileId of the cardholder profile to the cardHolderProfileId field on the card order request.

For country-specific address fields and validation rules, see the card address validation guide.

Security
UserToken
Path
profileIdinteger(int64)required

The profile ID (personal or business).

Example: 123456
Headers
X-idempotence-uuidstring(uuid)required

Idempotency key. Should be generated and used for any subsequent retries.

Example: 054064c9-e01e-49fb-8fd9-b0990b9442f4
Bodyapplication/jsonrequired
programstringrequired

The name of the card program.

Example: "VISA_DEBIT_BUSINESS_UK_1_PHYSICAL_CARDS_API"
cardHolderNamestringrequired

The cardholder's name.

Example: "John Smith"
embossedNamestring

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

Example: "Smith John"
phoneNumberstring

For partners onboarded after 1/3/2025, we will use the profile phone number for any Card-related One-Time Password (OTP) requests. See 3ds. Ensure that the phone number is valid and starts with a "+" followed by the country code.

Example: "+441234567890"
addressobjectrequired

The cardholder's billing address or delivery address. Fields vary by country. See the card address validation guide.

address.​firstLinestring
Example: "56 Shoreditch High St"
address.​secondLinestring or null
Example: "The Tea Bldg"
address.​thirdLinestring or null
Example: null
address.​citystring
Example: "London"
address.​postCodestring
Example: "E1 6JJ"
address.​statestring or null
Example: null
address.​countrystring

ISO 3166-1 alpha-2 country code.

Example: "GB"
address.​property name*anyadditional property
deliveryOptionstring

The delivery method for the card order. The delivery method will be defined during scoping phase. Please reach out to your Implementation Manager for more information.

Only specify this field for KIOSK_COLLECTION. If not specified, the default delivery method for your region will be used.

  • POSTAL_SERVICE_STANDARD - Default delivery method. Not traceable.
  • POSTAL_SERVICE_WITH_TRACKING - Available in certain regions. Default in Brazil.
  • KIOSK_COLLECTION - Available in select regions. See the kiosk collection guide.
Enum"POSTAL_SERVICE_STANDARD""POSTAL_SERVICE_WITH_TRACKING""KIOSK_COLLECTION"
Example: null
lifetimeLimitnumber

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.

Example: 100
cardHolderProfileIdinteger(int64)

The cardholder profile for this card. This is used for business profiles.

Example: 654321
replacementDetailsobject

The replacement details for this card.

replacementDetails.​cardTokenstring

Token of the card to replace.

Example: "4a75fdb7-5791-49ac-832c-81c4347e4df0"
replacementDetails.​reasonstring

Reason for replacing the card:

  • CARD_DAMAGED
  • CARD_EXPIRING
Enum"CARD_DAMAGED""CARD_EXPIRING"
Example: "CARD_DAMAGED"
curl -i -X POST \
  https://api.wise.com/v3/spend/profiles/123456/card-orders \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -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",
    "phoneNumber": "+441234567890",
    "address": {
      "firstLine": "56 Shoreditch High St",
      "secondLine": "The Tea Bldg",
      "thirdLine": null,
      "city": "London",
      "postCode": "E1 6JJ",
      "state": null,
      "country": "GB"
    },
    "deliveryOption": null,
    "lifetimeLimit": 100,
    "cardHolderProfileId": 654321,
    "replacementDetails": {
      "cardToken": "4a75fdb7-5791-49ac-832c-81c4347e4df0",
      "reason": "CARD_DAMAGED"
    }
  }'

Responses

OK - Card order created successfully.

Bodyapplication/json
idinteger(int64)

ID of the card order.

Example: 142
profileIdinteger(int64)

Profile ID.

Example: 123456
clientIdstring

Client ID.

Example: "your-client-id"
cardProgramobject

The card program associated with this card order. 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.

cardProgram.​namestring

The name of the card program.

Example: "VISA_DEBIT_BUSINESS_UK_1_PHYSICAL_CARDS_API"
cardProgram.​schemestring

The network of the card program:

  • MASTERCARD
  • VISA
Enum"MASTERCARD""VISA"
Example: "VISA"
cardProgram.​defaultCurrencystring

The default currency assigned to the card program.

Example: "GBP"
cardProgram.​cardTypestring

The type of the card:

  • VIRTUAL_NON_UPGRADEABLE
  • PHYSICAL
Enum"VIRTUAL_NON_UPGRADEABLE""PHYSICAL"
Example: "PHYSICAL"
addressobject

Address set during card order. Fields vary by country. See the card address validation guide for country-specific fields and validation rules.

address.​firstLinestring

Card holder's address.

Example: "56 Shoreditch High St"
address.​secondLinestring or null

Card holder's address.

Example: "The Tea Bldg"
address.​thirdLinestring or null

Card holder's address.

Example: null
address.​citystring

Card holder's city.

Example: "London"
address.​postCodestring

Card holder's postal code.

Example: "E1 6JJ"
address.​statestring or null

Card holder's state.

Example: null
address.​countrystring

Card holder's country (ISO 3166-1 alpha-2).

Example: "GB"
address.​property name*anyadditional property
cardTokenstring or null

Token of the card associated with card order. Nullable.

Example: "4dc0be88-903f-49e4-8237-735f1139e3dd"
replacesCardstring or null

A string for replacement card. Not supported at the moment.

Example: null
creationTimestring(date-time)

Time when the card order is created.

Example: "2023-07-31T01:43:24.596321434Z"
modificationTimestring(date-time)

Time when the card order was last modified.

Example: "2023-07-31T01:43:24.596321825Z"
statusstring

Status of the card order. See card order status flow for details.

Enum"PLACED""REQUIREMENTS_FULFILLED""CARD_DETAILS_CREATED""PRODUCED""COMPLETED""CANCELLED""RETURNED"
Example: "PRODUCED"
cardHolderNamestring

Name of the card holder.

Example: "John Smith"
phoneNumberstring

Phone number associated with the card order.

Example: "+441234567890"
lifetimeLimitnumber or null

Maximum amount of spending on the card once issued. Nullable.

Example: 100
deliveryEstimatestring(date-time)

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.
Example: "2023-10-30T07:11:00.848681Z"
deliveryDetailsobject

Delivery details of a physical card order. For virtual cards, this value is null.

deliveryDetails.​deliveryOptionstring

The delivery option used on the card order.

Enum"POSTAL_SERVICE_STANDARD""POSTAL_SERVICE_WITH_TRACKING""KIOSK_COLLECTION"
Example: "POSTAL_SERVICE_WITH_TRACKING"
deliveryDetails.​deliveryVendorstring or null

The name of the delivery vendor.

Example: "DHL"
deliveryDetails.​trackingUrlstring or null

The URL to track the card delivery.

Example: "https://www.dhl.com/gb-en/home/tracking/tracking-express.html?submit=1&tracking-id=1999473803"
deliveryDetails.​trackingNumberstring or null

The tracking number of the card delivery.

Example: "1999473803"
Response
application/json
{
  "id": 142,
  "profileId": 123456,
  "clientId": "your-client-id",
  "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": {
    "deliveryOption": "POSTAL_SERVICE_WITH_TRACKING",
    "deliveryVendor": "DHL",
    "trackingUrl": "https://www.dhl.com/gb-en/home/tracking/tracking-express.html?submit=1&tracking-id=1999473803",
    "trackingNumber": "1999473803"
  }
}

Retrieve all card orders

Request

Retrieves a list of card orders created for the specified profileId.

Security
UserToken
Path
profileIdinteger(int64)required

The profile ID (personal or business).

Example: 123456
Query
pageSizeinteger(int32)

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

Example: pageSize=10
pageNumberinteger(int32)

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.

Example: pageNumber=1
curl -i -X GET \
  'https://api.wise.com/v3/spend/profiles/123456/card-orders?pageSize=10&pageNumber=1' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

OK - Successfully retrieved card orders.

Bodyapplication/json
totalCountinteger

The total number of card orders for this profile.

Example: 5
cardOrdersArray of objects
cardOrders[].​idinteger(int64)

ID of the card order.

Example: 142
cardOrders[].​profileIdinteger(int64)

Profile ID.

Example: 123456
cardOrders[].​clientIdstring

Client ID.

Example: "your-client-id"
cardOrders[].​cardProgramobject

The card program associated with this card order. 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.

cardOrders[].​addressobject

Address set during card order. Fields vary by country. See the card address validation guide for country-specific fields and validation rules.

cardOrders[].​cardTokenstring or null

Token of the card associated with card order. Nullable.

Example: "4dc0be88-903f-49e4-8237-735f1139e3dd"
cardOrders[].​replacesCardstring or null

A string for replacement card. Not supported at the moment.

Example: null
cardOrders[].​creationTimestring(date-time)

Time when the card order is created.

Example: "2023-07-31T01:43:24.596321434Z"
cardOrders[].​modificationTimestring(date-time)

Time when the card order was last modified.

Example: "2023-07-31T01:43:24.596321825Z"
cardOrders[].​statusstring

Status of the card order. See card order status flow for details.

Enum"PLACED""REQUIREMENTS_FULFILLED""CARD_DETAILS_CREATED""PRODUCED""COMPLETED""CANCELLED""RETURNED"
Example: "PRODUCED"
cardOrders[].​cardHolderNamestring

Name of the card holder.

Example: "John Smith"
cardOrders[].​phoneNumberstring

Phone number associated with the card order.

Example: "+441234567890"
cardOrders[].​lifetimeLimitnumber or null

Maximum amount of spending on the card once issued. Nullable.

Example: 100
cardOrders[].​deliveryEstimatestring(date-time)

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.
Example: "2023-10-30T07:11:00.848681Z"
cardOrders[].​deliveryDetailsobject

Delivery details of a physical card order. For virtual cards, this value is null.

Response
application/json
{
  "totalCount": 5,
  "cardOrders": [
    {
      "id": 142,
      "profileId": 123456,
      "clientId": "your-client-id",
      "cardProgram": { … },
      "address": { … },
      "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": { … }
    }
  ]
}

Retrieve a card order

Request

Retrieves a card order based on the cardOrderId.

Security
UserToken
Path
profileIdinteger(int64)required

The profile ID (personal or business).

Example: 123456
cardOrderIdinteger(int64)required

The card order ID.

Example: 142
curl -i -X GET \
  https://api.wise.com/v3/spend/profiles/123456/card-orders/142 \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

OK - Successfully retrieved card order.

Bodyapplication/json
idinteger(int64)

ID of the card order.

Example: 142
profileIdinteger(int64)

Profile ID.

Example: 123456
clientIdstring

Client ID.

Example: "your-client-id"
cardProgramobject

The card program associated with this card order. 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.

cardProgram.​namestring

The name of the card program.

Example: "VISA_DEBIT_BUSINESS_UK_1_PHYSICAL_CARDS_API"
cardProgram.​schemestring

The network of the card program:

  • MASTERCARD
  • VISA
Enum"MASTERCARD""VISA"
Example: "VISA"
cardProgram.​defaultCurrencystring

The default currency assigned to the card program.

Example: "GBP"
cardProgram.​cardTypestring

The type of the card:

  • VIRTUAL_NON_UPGRADEABLE
  • PHYSICAL
Enum"VIRTUAL_NON_UPGRADEABLE""PHYSICAL"
Example: "PHYSICAL"
addressobject

Address set during card order. Fields vary by country. See the card address validation guide for country-specific fields and validation rules.

address.​firstLinestring

Card holder's address.

Example: "56 Shoreditch High St"
address.​secondLinestring or null

Card holder's address.

Example: "The Tea Bldg"
address.​thirdLinestring or null

Card holder's address.

Example: null
address.​citystring

Card holder's city.

Example: "London"
address.​postCodestring

Card holder's postal code.

Example: "E1 6JJ"
address.​statestring or null

Card holder's state.

Example: null
address.​countrystring

Card holder's country (ISO 3166-1 alpha-2).

Example: "GB"
address.​property name*anyadditional property
cardTokenstring or null

Token of the card associated with card order. Nullable.

Example: "4dc0be88-903f-49e4-8237-735f1139e3dd"
replacesCardstring or null

A string for replacement card. Not supported at the moment.

Example: null
creationTimestring(date-time)

Time when the card order is created.

Example: "2023-07-31T01:43:24.596321434Z"
modificationTimestring(date-time)

Time when the card order was last modified.

Example: "2023-07-31T01:43:24.596321825Z"
statusstring

Status of the card order. See card order status flow for details.

Enum"PLACED""REQUIREMENTS_FULFILLED""CARD_DETAILS_CREATED""PRODUCED""COMPLETED""CANCELLED""RETURNED"
Example: "PRODUCED"
cardHolderNamestring

Name of the card holder.

Example: "John Smith"
phoneNumberstring

Phone number associated with the card order.

Example: "+441234567890"
lifetimeLimitnumber or null

Maximum amount of spending on the card once issued. Nullable.

Example: 100
deliveryEstimatestring(date-time)

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.
Example: "2023-10-30T07:11:00.848681Z"
deliveryDetailsobject

Delivery details of a physical card order. For virtual cards, this value is null.

deliveryDetails.​deliveryOptionstring

The delivery option used on the card order.

Enum"POSTAL_SERVICE_STANDARD""POSTAL_SERVICE_WITH_TRACKING""KIOSK_COLLECTION"
Example: "POSTAL_SERVICE_WITH_TRACKING"
deliveryDetails.​deliveryVendorstring or null

The name of the delivery vendor.

Example: "DHL"
deliveryDetails.​trackingUrlstring or null

The URL to track the card delivery.

Example: "https://www.dhl.com/gb-en/home/tracking/tracking-express.html?submit=1&tracking-id=1999473803"
deliveryDetails.​trackingNumberstring or null

The tracking number of the card delivery.

Example: "1999473803"
Response
application/json
{
  "id": 142,
  "profileId": 123456,
  "clientId": "your-client-id",
  "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": {
    "deliveryOption": "POSTAL_SERVICE_WITH_TRACKING",
    "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

Request

Retrieves the list of available card programs for each profileId.

Security
UserToken
Path
profileIdinteger(int64)required

The profile ID (personal or business).

Example: 123456
curl -i -X GET \
  https://api.wise.com/v3/spend/profiles/123456/card-orders/availability \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

OK - Successfully retrieved available card programs.

Bodyapplication/json
cardProgramsArray of objects

List of available card programs. 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.

cardPrograms[].​namestring

The name of the card program.

Example: "VISA_DEBIT_BUSINESS_UK_1_CARDS_API"
cardPrograms[].​schemestring

The network of the card program:

  • MASTERCARD
  • VISA
Enum"MASTERCARD""VISA"
Example: "VISA"
cardPrograms[].​defaultCurrencystring

The default currency assigned to the card program.

Example: "GBP"
cardPrograms[].​cardTypestring

The type of the card:

  • VIRTUAL_NON_UPGRADEABLE
  • PHYSICAL
Enum"VIRTUAL_NON_UPGRADEABLE""PHYSICAL"
Example: "VIRTUAL_NON_UPGRADEABLE"
Response
application/json
{
  "cardPrograms": [
    {
      "name": "VISA_DEBIT_BUSINESS_UK_1_CARDS_API",
      "scheme": "VISA",
      "defaultCurrency": "GBP",
      "cardType": "VIRTUAL_NON_UPGRADEABLE"
    }
  ]
}

Retrieve card order requirements

Request

Retrieves all card requirements for a cardOrderId. A valid card order needs all its requirements status to be COMPLETED.

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 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
Security
UserToken
Path
profileIdinteger(int64)required

The profile ID (personal or business).

Example: 123456
cardOrderIdinteger(int64)required

The card order ID.

Example: 142
curl -i -X GET \
  https://api.wise.com/v3/spend/profiles/123456/card-orders/142/requirements \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

OK - Successfully retrieved card order requirements.

Bodyapplication/json
requirementsArray of objects
requirements[].​typestring

The type of requirement:

  • PIN - Set a PIN on the card order
  • VERIFICATION - Verify customer by providing KYC evidences
  • ADDRESS - Provide a valid address for the card order
Enum"PIN""VERIFICATION""ADDRESS"
Example: "PIN"
requirements[].​statusstring

The status of the requirement:

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

Update card order status

Request

Updates the status of a card order based on its cardOrderId. The status can be updated to one of the following:

  1. CANCELLED
  2. COMPLETED (deprecated)

The behaviour for card order cancellation differs across card order statuses:

  • PLACED: Card order can be cancelled with no further action required.
  • REQUIREMENTS_FULFILLED, CARD_DETAILS_CREATED, PRODUCED: Card order can be cancelled, and its associated card will be blocked. However, the physical card may have already been produced and may be in delivery. If so, the card will still reach the end user's address. This should be communicated to the end user to prevent confusion.
  • COMPLETED, RETURNED: Card orders in these statuses cannot be cancelled.

Updating a card order status to COMPLETED is deprecated. Check with our team whether this is supported in your integration.

Security
UserToken
Path
profileIdinteger(int64)required

The profile ID (personal or business).

Example: 123456
cardOrderIdinteger(int64)required

The card order ID.

Example: 142
Bodyapplication/jsonrequired
statusstringrequired

The intended new status of the card order:

  • CANCELLED
  • COMPLETED (deprecated)
Enum"CANCELLED""COMPLETED"
Example: "CANCELLED"
curl -i -X PUT \
  https://api.wise.com/v3/spend/profiles/123456/card-orders/142/status \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "CANCELLED"
  }'

Responses

Accepted - Card order status update has been accepted.

Validate an address

Request

Validates the format of an address for a card order. Make sure to follow country-specific address fields and validation as described in the card address validation guide.

For virtual cards, the address field will be used as a billing address. It will be used for AVS checks in countries where it is 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 it is required.

We do not support PO BOX addresses.

Security
UserToken
Bodyapplication/jsonrequired
firstLinestring

Card holder's address (max 30 characters).

Example: "56 Shoreditch High St"
secondLinestring or null

Card holder's address (max 30 characters).

Example: "The Tea Bldg"
thirdLinestring or null

Card holder's address (max 30 characters).

Example: null
citystring

Card holder's city (max 30 characters).

Example: "London"
postCodestring

Card holder's postal code (max 10 characters).

Example: "E1 6JJ"
statestring or null

Card holder's state (max 30 characters).

Example: null
countrystring

Card holder's country (ISO 3166-1 alpha-2, max 2 characters).

Example: "GB"
property name*anyadditional property
curl -i -X POST \
  https://api.wise.com/v3/spend/address/validate \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "firstLine": "56 Shoreditch High St",
    "secondLine": "The Tea Bldg",
    "thirdLine": null,
    "city": "London",
    "postCode": "E1 6JJ",
    "state": null,
    "country": "GB"
  }'

Responses

OK - Validation result returned. An empty errors collection means the address is valid.

Bodyapplication/json
errorsArray of objects

Collection of validation errors. Empty if address is valid.

errors[].​fieldstring

The field that failed validation.

Example: "postCode"
errors[].​messagestring

Description of the validation error.

Example: "Please enter a valid postcode"
Response
application/json
{
  "errors": [
    {
      "field": "city",
      "message": "Required Field"
    },
    {
      "field": "postCode",
      "message": "Please enter a valid postcode"
    },
    {
      "field": "firstLine",
      "message": "Must be less than 30 characters"
    }
  ]
}

Set card PIN

Request

Sets a PIN during the card order flow. 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.

Security
UserToken
Headers
x-tw-twcard-order-idstringrequired

The card order ID.

Example: 142
Bodyapplication/jsonrequired
keyVersionintegerrequired

The version of the key to use. It is always set to 1.

Example: 1
encryptedPayloadstringrequired

Your JWE payload.

Example: "eyJhbGciOiJSU0..."
curl -i -X POST \
  https://twcard.wise.com/twcard-data/v1/sensitive-card-data/preset-pin \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'x-tw-twcard-order-id: 142' \
  -d '{
    "keyVersion": 1,
    "encryptedPayload": "eyJhbGciOiJSU0..."
  }'

Responses

OK - PIN set successfully.

Bodyapplication/json
cardOrderIdstring

The card order ID.

Example: "142"
Response
application/json
{
  "cardOrderId": "142"
}

Card Transaction

Retrieve information on transactions made on your users' cards.

Transaction types

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

Transaction states

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 cannot be confirmed

The transition from CANCELLED to COMPLETED is an edge case. Wise releases the customer funds after 7 days (30 days for pre-authorization) if the merchant has not captured the transaction, and the state becomes CANCELLED. However, the merchant can decide to capture the transaction at a later date, at which point the state will become COMPLETED.

Transaction state flow

Decline reasons

The decline reason field provides information about the specific issue that led to the transaction being declined, helping the merchant and the customer troubleshoot the problem.

While the decline reason field provides valuable information, it may not cover all possible reasons for a decline, such as technical issues or unforeseen circumstances.

New decline reasons may be added in the future, and not all decline reasons are currently documented. Review this documentation regularly to ensure accuracy.

Exercise caution when communicating decline reasons to your customers, as some may not be relevant or may cause confusion.

  • ACCOUNT_INACTIVE - Balance related to the transaction is not active. Ensure that all outstanding actions have been completed before using the card, as this may help avoid potential issues or declines
  • ACCOUNT_SUSPENDED - The transaction has been declined pending further compliance checks. It may have been flagged for potential sanctions issues
  • ATM_PIN_CHANGE_NOT_ALLOWED - PIN change via ATM terminal is not allowed
  • BLOCKED_COUNTRY - Transactions were made in unsupported countries. Check this link to see if the country is included in the list of supported nations. It is possible for a merchant to be based in a supported country and have an address registered in a blocked country, albeit infrequently
  • BLOCKED_SUBSCRIPTION - The system cannot facilitate this transaction as the customer has opted out of recurring payments with this merchant
  • CARD_EXPIRED - The card provided has reached its expiration date, making it invalid for this transaction
  • CARD_FROZEN - The customer or the customer service team has put this card on a temporary hold. If the card has not been frozen by the customer, it may be worth investigating further. To resume spending, advise the customer to unfreeze the card
  • CARD_INACTIVE - The card is either not active or has not been received by the customer, so the transaction cannot proceed
  • CARD_BLOCKED - The card has been blocked and cannot be used anymore
  • CARD_PARTNER_SUSPENDED - The internal team has deactivated the account for compliance reasons related to AML, fraud, or EDD. Contact the team if this is believed to be an error
  • CHIP_PIN_ENTRY_TRIES_EXCEEDED - The PIN is restricted on the chip of the card due to excessive incorrect entries. The blocked PIN can be unlocked at an ATM using specific steps that vary depending on the machine and country, such as PIN management or PIN operations followed by unblocking the PIN
  • CONNECTION_ISSUE - A connection problem occurred during the transaction
  • CONTACTLESS_PIN_ENTRY_REQUIRED - Contactless payment systems sometimes require a PIN for authentication purposes to protect users' accounts from potential fraud or tampering. In Europe, contactless payment transactions that follow one after the other require PIN verification as an additional security measure
  • CREDIT_TRANSACTIONS_NOT_SUPPORTED - Credit is not supported for this specific transaction. Review the Acceptable Use Policy for further information
  • CUMULATIVE_LIMIT_EXCEEDED - In certain jurisdictions, there are restrictions on the amount that can be spent. Refer to spending limits for further details
  • DECLINED_ADVICE - There is a problem with the message from the processor, so it might not be accepted because it could be incomplete or unsafe. This does not indicate a problem with the card. Advise the customer that there was a technical issue with the payment and to try again later
  • INCORRECT_CVV - The customer entered the wrong security code. Advise the customer to check their card details and try again. If the saved card details are correct, they should remove their card details from the merchant's website and add them back again
  • INCORRECT_EXPIRY_DATE - The customer entered the wrong expiration date for their card. If the saved card details are correct, they should remove their card details from the merchant's website and add them back again
  • INCORRECT_PIN - The customer entered their PIN incorrectly. Advise the customer to check their PIN and try again. If the PIN is correct and still fails, suggest resetting the PIN
  • INSUFFICIENT_FUNDS - The customer does not have enough money in their account to make the payment. Advise the customer to add money to their account and try again. In most cases, this will resolve the issue
  • INVALID_3DS_UCAF - The 3D Secure checks failed during the transaction. The customer should try again and request authentication
  • INCORRECT_ARQC - ARQC (Authorization Request Cryptogram) is a cryptogram generated by the card during a transaction, which is validated on the server side. If incorrect, it could indicate a faulty card, a fraudulent attack, or an issue with the POS terminal
  • INCORRECT_ICVV - ICVV (Integrated Circuit Card Verification Value) is a security feature used to validate the authenticity of a card during chip-based transactions. There were problems reading the chip on the card, which may indicate an issue with the card's chip, the terminal, or the transaction process. Wait and try again
  • INVALID_MERCHANT - Transaction from a specific merchant is declined by scheme. The merchant should clarify the exact cause with the scheme
  • INVALID_TRANSACTION - Certain types of transactions are not supported. The customer should ask the merchant to use a different payment method or try a different merchant
  • MANDATE_DCC_NON_SUPPORTED_FOR_CARD_COUNTRY - The transaction was declined because the system does not support conversions for Brazilian cards when BRL is involved. BRL will not be automatically exchanged to other currencies. If the customer wants to continue with the payment, they need to change the currency
  • MANDATE_LOCAL_CASH_WITHDRAWAL_NOT_ALLOWED - ATM withdrawal services are not provided in the country where the transaction is taking place
  • NON_SUPPORTED_CURRENCY - The currency in this transaction is not supported
  • NON_SUPPORTED_MCC_FOR_COUNTRY - Transactions in this category are not supported for customers in the country of purchase. Consider using an alternative payment method or changing merchant
  • PAYMENT_METHOD_DAILY_LIMIT_EXCEEDED - The customer has reached the daily spending limit for the card or their profile. Advise if they would like to update card or profile limit
  • PAYMENT_METHOD_LIFETIME_LIMIT_EXCEEDED - The customer has reached the lifetime spending limit. Advise if they would like to increase their lifetime limit
  • PAYMENT_METHOD_MONTHLY_LIMIT_EXCEEDED - The customer has reached the monthly spending limit for the card or their profile. Advise if they would like to update card or profile limit
  • PAYMENT_METHOD_NOT_ALLOWED - This payment type has been disabled. Advise if they would like to enable the payment type
  • PAYMENT_METHOD_TRANSACTION_LIMIT_EXCEEDED - The customer has exceeded the transaction limit for the card. Advise if they would like to update their card limit
  • PIN_ENTRY_TRIES_EXCEEDED - The customer has reached the maximum number of allowed online PIN entry attempts. Consider implementing a reset PIN feature within the app to help the customer regain access to their card
  • PRE_ACTIVATED_CARD_PIN_ENTRY_REQUIRED - The customer has attempted to make a contactless payment at a POS or ATM, but their card has not been activated for chip and PIN transactions. To modify the card activation strategy for all cards, contact the implementation manager
  • PROCESSING_ERROR - The system is currently experiencing technical difficulties. Advise the customer to try again after a brief period
  • RESTRICTED_MODE - Although rare, restricted mode can occur. Advise the customer to replace their card promptly as the system should have already informed them. In this mode, more secure payment methods like chip and PIN, contactless, mobile wallets, and online payments with 3DS are allowed, while less secure methods like magnetic stripe and online payments without 3DS are not permitted
  • REVERSAL_NOT_MATCHING_AUTH_CURRENCY - The merchant has issued a reversal instruction for a different currency than what was originally requested during the authorization process
  • SCA_SOFT_DECLINE - The transaction cannot proceed due to SCA regulations. Suggest the customer contact the merchant and use a more secure authentication method such as 3DS. For example, the customer can try chip and PIN, or a mobile wallet like Apple Pay or Google Pay
  • SCHEME_BLOCKED_TRANSACTION - This transaction has been flagged by the scheme and cannot be processed
  • SECURITY_CVM_FAILURE - The system has detected that the POS terminal was misconfigured and failed security checks. Suggest the customer use an alternative payment method like contactless or mobile wallets, or recommend asking the merchant to accept a signature instead
  • SECURITY_MAGSTRIPE_SECURE_ELEMENTS_INCORRECT_OR_MISSING - The merchant has entered the wrong type of purchase. Advise the customer to contact the merchant and ask them to correct this issue
  • SECURITY_PIN_ENTRY_REQUIRED - To proceed with this transaction, the customer is required to enter their PIN
  • SUSPECTED_FRAUD - This transaction has been labeled as high-risk by Wise
  • SUSPECTED_FRAUD_AML - This transaction has been flagged as high-risk based on AML compliance protocols. This reason cannot be disclosed to end customers
  • SUSPECTED_FRAUD_COMPLIANCE - The compliance system has flagged this transaction as high-risk. This reason cannot be disclosed to end customers
  • SUSPECTED_FRAUD_CORE_FRAUD - This transaction has been blocked based on fraud policies and procedures
  • SUSPECTED_FRAUD_SANCTIONS - This transaction has been flagged as high-risk based on sanctions list analysis. This reason cannot be disclosed to end customers. This classification is final and cannot be appealed
  • SUSPECTED_FRAUD_SOFT_DECLINE - This e-commerce transaction cannot be processed due to high risk factors. The merchant must complete 3DS before the transaction can be approved
  • TRANSACTION_TYPE_NOT_SUPPORTED - There are restrictions on this type of transaction, and sometimes the scheme will not allow it. Check if spend control is set up to block this transaction
  • UNEXPECTED_ERROR - There may have been a communication error between the merchant's system and the server, but the POS system may have already notified the user of this issue
Operations