A developer's guide to start working with the Wise Platform API.
Integrating your application with the Wise API allows you to build key Wise Platform functionality directly into your app.
This guide will help you understand the foundations and key concepts of the Wise API and provide links to guides and references to help you get started more quickly.
During the partner onboarding process with the Wise sales and implementation teams, Wise provides a client ID and client secret for each environment, sandbox then production. These credentials are required for obtaining the tokens you’ll need to make requests to the Wise API and can be accessed and managed via our Developer Hub.
Your client credentials are scoped to the integration and access model determined during the partner onboarding process. The scope of your credentials determines how you interact with the API and its resources.
In addition to partner accounts, Wise business accounts can also gain limited access to certain endpoints so they can automate parts of their send money flow. These accounts generate a personal API token in the Wise.com app. If you are a small-to-medium business with a Wise business account, read our Personal API token guide and Payouts for SMBs guide to learn more.
Personal tokens are limited to a subset of endpoints and not intended for partner account integrations. If in doubt, please contact your CSM to ensure you are using the correct token type.
Developer Hub is your dedicated portal for managing credentials and security certificates. You can rotate and revoke client credentials as well as upload your mTLS certificate and retrieve the Wise certificate for your truststore.
Wise provides both a sandbox and production developer hub:
- Sandbox: https://wise-sandbox.com/developer-hub
- Production: https://wise.com/developer-hub
Wise must grant access to Developer Hub before you can log into it. Speak with your implementation team if you don’t have your access details.
The Wise Platform API implements OAuth 2.0 for all partner accounts. Wise also offers the following enhanced security frameworks for partners requiring additional protection: mTLS, JOSE, and SCA & 2FA.
Read the Security and Access guide to learn more about how Wise Platform handles security.
The Wise API reference documents our publicly available endpoints and operations. It provides operation descriptions, auth requirements, details about parameters and properties for requests and responses, status codes, and code samples you can copy and modify for your own use.
Our developer guides supplement the API reference. While the reference provides the specifications for each endpoint and operation, the guides provide context and instructions for specific workflows and use cases.
Wise provides a sandbox environment for development and testing before moving to the production environment.
Sandbox: This is your initial playground. Use the sandbox environment for development and testing your integration without affecting live data or customer funds.
- Base URL:
https://api.wise-sandbox.com - mTLS-enabled:
http://api-mtls.wise-sandbox.com
Production: Once your integration is thoroughly tested and approved, you'll move to the production environment for live operations.
- Base URL:
https://api.wise.com - mTLS-enabled:
http://api-mtls.transferwise.com
Visit the Environments guide to learn more about using each environment.
When you start development with the Wise API, it’s good to understand some of the key concepts around different integration models, the core resources you’ll be interacting with, and how the Wise API implements rate limiting, idempotency, and custom headers.
Wise Platform offers three integration models for partners to integrate with the API:
- The Enterprise model
- The Correspondent model
- The Embedded model
The model you use determines how you perform onboarding and account authorization tasks, as well as how you handle transfers and balance conversions.
By the time you start development, you should understand which integration model you use. The developer guides provide integration model-specific guidance to help you self-serve as much as possible. When an integration model requires specific endpoints or properties/values to successfully accomplish a task or workflow, our developer guides will provide the necessary details.
The core resources you’ll interact with are related to account setup, account access, sending money, and managing balances.
These resources are the foundation of much of the Wise API functionality, though by no means represent all capabilities. However, when getting started, it’s important to understand what these core resources are and how they relate to each other in various workflows.
| Resource | Description |
|---|---|
User | A user represents a Wise account holder and is the top-level identity in the Wise API hierarchy.
|
| Profile | A profile represents the personal or business entity associated with a user resource. It serves as the central identifier for nearly all Wise Platform API operations. The profileId is a required parameter in requests to create authenticated quotes, manage balance accounts, and fund transfers. |
KYC Review | A KYC review resource represents the verification state of a profile and allows you to track whether a customer has satisfied Wise's Know Your Customer (KYC) requirements.
|
Quote | A quote defines the basic information required for a Wise transfer: the currencies to send between, the amount to send, and the profile who is sending the money. An authenticated quote is one of the required resources to create a transfer, along with the recipient who is to receive the funds.
|
| Recipient | A recipient (also called a recipient account) represents the beneficiary account that will receive funds in a transfer. The recipient resource stores details like the account holder name, bank account fields, and other corridor-specific properties. The id returned when creating a recipient is used as the targetAccount value in the transfer creation request and can also be used to update a quote to ensure accurate pricing before the transfer is funded. |
| Transfer | A transfer represents the instruction to move money from a profile to a recipient, combining a quote and a recipient into a single payment object. The transfer id is used in the fund transfer request to trigger the actual movement of funds. |
Multi-currency account & balance account | A multi-currency account is the top-level account structure tied to a profile, capable of holding multiple currency-specific balance accounts.
|
Wise enforces rate limiting to ensure the security and stability of the Wise Platform API. Rate limits apply at the gateway level, but certain services will have additional rate limits for specific operations.
Gateway-level limits:
- Limits for partner accounts: max 100 requests per second, 1000 requests per minute per client owned by that partner.
- Limits for Wise business accounts using a personal API token: applied per-user, not per-client
- For Android and Web: 100 requests per second, 900 requests per minute.
- For iOS: 150 requests per second, 1500 requests per minute.
If you hit the rate limit, you’ll receive an HTTP 429 status code in the response. The response also includes a retry-after header, indicating how long to wait before retrying the request.
Service-level limits:
Rate limits can apply to certain actions, like the number of quotes that can be created or one-time tokens that can be generated in a specific time frame. These limits vary according to service and operation.
In most cases, you’ll receive the same 429 error if you reach the rate limit for these services.
It’s important to ensure certain resources are not created twice in the event of a network error or other type of service issue that necessitates a retry. Wise includes idempotency methods on key operations to prevent creating duplicate resources.
Some key operations that support idempotency include:
Idempotency applies to specific endpoints and operations that need it, rather than globally. Additionally, different services support idempotency in different ways. Here are a few examples:
- The convert or move money between balances operation and create a card order operation use the customer header
X-idempotence-uuidto hold the unique UUID you generate. - The create a transfer operation uses the
customerTransactionIdproperty in the request body.
Be sure to review the API reference for the operation you are performing to understand if and how idempotency is supported for that service.
- Learn about Wise security and authentication methods.
- Look closer at the Wise Platform API with our comprehensive API reference.
- Understand how to use webhooks to receive real-time notifications about events, which is crucial for handling asynchronous processes.
- Understand Wise error handling to best manage API responses and ensure a smooth user experience.
- Familiarize yourself with Wise’s API versioning strategy to ensure your integration remains compatible with future updates.
- Review information about testing in the Wise sandbox.