SWIFT Receive Implementation Guide
This guide describes in detail the technical implementation of SWIFT Receive from Wise. If you need any help please reach out to the Wise team here.
How It Works
At its simplest, the SWIFT Receive integration enables a partner's customers to receive international payments via SWIFT. Customers use the partners BIC and their IBAN to direct a payment over SWIFT, which after moving through correspondents is accepted by Wise and deposited into the partners balance.
Partners can then manage their balance and transactions as any other balance with Wise, including sweeping funds, transaction reconciliation, and generating statements. We also provide a specific webhook to notify partners of incoming SWIFT payments in real time.
Implementing SWIFT Receive
Implementing the SWIFT Receive solution with Wise will generally take 4-6 weeks or more. Following this guide, with the aid of your implementation manager, can ensure this goes smoothly.
It's also important to note that partners are required to build some tools and features on the Wise API to enable certain features and functionality. This guide documents the steps required to get this completed. Generally, this can be completed in a few days of development time, depending on the level of automation required by the partner.
Getting Started
To begin technical setup, we recommend first having a kick-off call with your implementation manager. They will walk through the steps outline din this guide and help assist with the non-technical components.
For the technical integration, two distinct steps are required:
Step one can be completed at any time and should be done as soon as possible on the recommendation of our implementation team. Once received, we will complete all other pieces in order to begin the process of step 2. We recommend waiting to build out the integration until the implementation team supplies you with sandbox credentials.
Configuration + Access
In order to configure SWIFT Receive, we require some essential steps to be completed by partners. Once those are completed, we can configure your accounts to allow the receipt of SWIFT messages and ensure that those messages are routed to the right balances.
Your implementation manager will assist with this process and collect the right details as described below.
1. Setup Wise Account
SWIFT Receive requires a profile with a balance account to complete transactions and deposits. We recommend that this profile and balance be separate from any other profiles and balances used by the partner to aid in reconciliation and integration management
Please follow the steps below in both our sandbox and production environments.
- Login or register for a new account. Make note of the credentials used for this as these will be needed later in your implementation
- Ensure that a personal profile is configured on the account. Speak with your implementation manager if you are unsure of who should be included in this profile.
- Create a new business profile. The name on this account should match the name of the partner's bank account. Further, the partner must use an email address which is actively monitored and which their back office team has access to; this ensures that any RFIs can and will be dealt with efficiently.
- Record the Membership Number (P#######) for the newly created business profile.
The membership number for both environments should then be given to your implementation manager. The business profile in each environment will be given access to SWIFT Receive and all transfers to the configured BICs will deposit to the production profile.
2. Provide BIC(s)
In order to complete configuration, we need to know the BICs you would like us to match and deposit into your balance. This can be a list of specific BICs or can be based on a "starts with" match.
For example, if we configure "BANKDE12", any branch code will also be matched, such as "BANKDE12XXX". If you would like for us to match specific branch codes, those should be provided.
3. Update Test Standing Settlement Instruction
Due to the length of time it can take for the SWIFT network to update the standing settlement instructions for BICs, it's advised that a test BIC to be used for testing be updated to point towards Wise's BIC.
This should only be done for a BIC that is not used by your customers in production at this point. Often this is a separate BIC that is unused or reserved for testing.
Speak with your implementation manager further about this and when it is applicable to make this change.
Build Requirements
Partners are required to build out a few components and leverage the Wise API to conduct certain actions. These include:
- Configure Profiles
- Subscribe to SWIFT webhook
- Develop process for sweeping balance funds
- Develop process for reconciliation of transfers
Building these features generally requires access to our sandbox environment, and specific settings are required to make that work. Your implementation manager will direct you on completing the initial configuration + access portion of the integration, and will then provide credentials for access to the sandbox environment.
We do not recommend starting the build of these components until this access has been granted.
1. Configuring Profiles
You will be supplied with a set of credentials specific for your integration. These credentials must be used to follow our OAuth process, which in turn will allow you to generate an access_token and a refresh_token.
This connection is important, as it is what allows your specific profiles to be linked to SWIFT Receive. This will be a one time operation, but is required to be completed in both our sandbox and production environments.
Please follow the details below to complete this link.
Step 1 - OAuth Account
To start, in a web browser, login to the Wise account you want to link to. If asked, you can access the business profile that you want to use for SWIFT Receive.
In your URL browser, open the following link based on the environment. Note that you will also need to update clientId.
Sandbox: https://sandbox.transferwise.tech/oauth/authorize/?client_id={clientId}&redirect_uri=localhost
Production: https://wise.com/oauth/authorize/?client_id={clientId}&redirect_uri=localhost
This will open a screen that will ask you to select the correct profile, and then authorize the connection to your account and profile. Complete this process.
Once complete, you will be redirected to localhost with a set of URL parameters included. One of these parameters is the code. Take note of this for step 2.
Example Request:
curl \
'https://api.sandbox.transferwise.tech/oauth/token' \
-u '[your-api-client-id]:[your-api-client-secret]' \
-d 'grant_type=authorization_code' \
-d 'client_id=[your-api-client-id]' \
-d 'code=[code-from-redirect-uri]' \
-d 'redirect_uri=https://www.yourbank.com'
You will be returned an access token and a refresh token.
Example Response:
{
"access_token":"ba8k9935-62f2-475a-60d8-6g45377b4062",
"token_type":"bearer",
"refresh_token":"a235uu9c-9azu-4o28-a1kn-e15500o151cx",
"expires_in": 43199,
"scope":"transfers"
}
Step 2 - Exchange Auth Code
Once you have the code, you need to exchange this for an access_token and a refresh_token. To do this, see the example request to the right.
Example Request:
curl \
'https://api.sandbox.transferwise.tech/oauth/token' \
-u '[your-api-client-id]:[your-api-client-secret]' \
-d 'grant_type=refresh_token' \
-d 'refresh_token=[user refresh token]'
Example Response:
{
"access_token":"be69d566-971e-4e15-9648-85a486195863",
"token_type":"bearer",
"refresh_token":"1d0ec7b9-b569-426d-a18d-8dead5b6a3cc",
"expires_in":43199,
"scope":"transfers"
}
Step 3 - Refresh Access Tokens
Access tokens are designed to expire after a short period of time, representing a login session to the Wise Platform API. This increases security of the account and profile in case the token is leaked.
In order to maintain an uninterrupted connection, you can request a new access token whenever the previous one is close to expiring. There is no need to wait for the actual expiration to happen first.
Request
POST https://api.sandbox.transferwise.tech/oauth/token
Use Basic Authentication with your api-client-id/api-client-secret as the username/password. The body of the request must be sent as x-www-form-urlencoded.
| Field | Description | Format |
|---|---|---|
| grant_type | "refresh_token" | Text |
| refresh_token | User's refresh_token obtained from creating or linking to a TW user. | Text |
Response
| Field | Description | Format |
|---|---|---|
| access_token | Access token to be used when calling API endpoints on behalf of user. Valid for 12 hours. | Text |
| token_type | "bearer" | Text |
| refresh_token | Refresh token which you need to use in order to request new access_token once the existing one expires | Text |
| expires_in | Expiry time in seconds | Integer |
| scope | "transfers" | Text |
2. Subscribe to Webhook
When a SWIFT message is received and deposited, we trigger a webhook to be sent to our partners. This notifies you of the transaction, includes the full SWIFT message as it was received, and is confirmation that the funds have been deposited into your balance.
Each partner must subscribe to the webhook following our standard webhook documentation. See the SWIFT-in#credit webhook documentation for complete details on subscribing to and consuming this webhook.
3. Sweeping Balance
All SWIFT messages and subsequent fund transfers are deposited into a single balance account for the partner. While you can store those funds with Wise, you likely will want to sweep these funds on a regular basis. Due to this, you must create a balance pay out.
To do this, you must create a quote, associate it to a recipient, create the transfer, and then fund that transfer. As this will likely be the same for each sweep, we recommend to follow these steps:
Step 1 - Create Recipient
As part of the initial setup, you will need to create the recipient that you want to sweep funds to. This is a one time operation, and will result in the generation of the accountID that can be used in the subsequent quote call.
Step 2 - Create Quote with Previously Created Recipient
Once you have a recipient, you will want to call the quote create endpoint, making sure to include the targetAccount. This removes the need to patch the quote with the recipient in the future.
You will additionally need to know how much you are looking to transfer. It's recommended that you first reconcile and determine the amount you want to transfer. This will be based on your processes though.
Step 3 - Create Transfer
Once the quote is created, it will then need to be confirmed as a transfer. This is straight forward and will include the targetAccount and quoteUUID along with any given transfer requirements.
Step 4 - Fund Transfer from Balance
Once the transfer is created, you will need to fund that from BALANCE. See the reference on successfully funding from balance.
4. Reconciliation
While we will send webhooks for each SWIFT message received, you will want to reconcile the transfers in your account. To do this, you can use the API to get statements and then reconcile those against what was received.
Testing + Go Live
Testing Swift Receive
Testing over the SWIFT Network is currently not very straight forward, as we have no way to do tests or use any kind of sandbox environment for sending SWIFT messages.
In order to test, we are required to do real payments over the network. As SWIFT messages take some time to complete, testing can be slow through this method. Further, updating SSI details can often take time as well.
To manage these issues, there are two ways we will test the integration.
Mock MT103 with Sandbox
Once we have configured Sandbox, you will be able to complete the initial tech build for webhook subscriptions, balance statements, and sweeping of funds. In addition, we will provide a simulation endpoint to send a mock MT103 to sandbox. This will allow you to check all settings, your webhook subscription, and your process for sweeping your account before moving to production.
Unused/Test BIC in Production
Many of our partners have additional BICs specifically for testing. We recommend updating the SSI on this to our BIC once your implementation manager informs you to. This ensures we can test proper flows and production testing when ready to go live.
Going Live
Once configuration is completed, and production testing has been completed, you will need to update your SSI for your production BIC to point to our BIC.
It is also recommended that you notify other members that the SSI has been updated, as it can often take a long time for members to update on their own. This can be done through an MT670 message sent directly to SWIFT, after which they will send an MT671 to all institutions. Wise needs to send this message on the partner's behalf, and this comes at a cost which will be discussed and invoiced directly.
Quotes
Create
Example Request:
curl -X POST https://api.sandbox.transferwise.tech/v3/profiles/101/quotes \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"sourceCurrency": "GBP",
"targetCurrency": "USD",
"sourceAmount": 100,
"targetAmount": null,
"payOut": null,
"preferredPayIn": null
}'
Example Response:
{
"id": "11144c35-9fe8-4c32-b7fd-d05c2a7734bf",
"sourceCurrency": "GBP",
"targetCurrency": "USD",
"sourceAmount": 100,
"payOut": "BANK_TRANSFER",
"preferredPayIn": "BANK_TRANSFER",
"rate": 1.30445,
"createdTime": "2019-04-05T13:18:58Z",
"user": 55,
"profile": 101,
"rateType": "FIXED",
"rateExpirationTime": "2019-04-08T13:18:57Z",
"guaranteedTargetAmountAllowed": true,
"targetAmountAllowed": true,
"guaranteedTargetAmount": false,
"providedAmountType": "SOURCE",
"paymentOptions": [
{
"disabled": false,
"estimatedDelivery": "2019-04-08T12:30:00Z",
"formattedEstimatedDelivery": "by Apr 8",
"estimatedDeliveryDelays": [],
"fee": {
"transferwise": 3.04,
"payIn": 0,
"discount": 2.27,
"partner": 0,
"total": 0.77
},
"price": {
"priceSetId": 238,
"total": {
"type": "TOTAL",
"label": "Total fees",
"value": {
"amount": 0.77,
"currency": "GBP",
"label:": "0.77 GBP"
}
},
"items": [
{
"type": "FEE",
"label": "fee",
"value": {
"amount": 0,
"currency": "GBP",
"label": "0 GBP"
}
},
{
"type": "TRANSFERWISE",
"label": "Our fee",
"value": {
"amount": 3.04,
"currency": "GBP",
"label": "3.04 GBP"
}
},
{
"id": 123,
"type": "DISCOUNT",
"value": {
"amount": -2.27,
"currency": "GBP",
"label": "2.27 GBP"
},
"label": "Discount applied",
"explanation": {
"plainText": "You can have a discount for a number of reasons..."
}
}
]
},
"sourceAmount": 100,
"targetAmount": 129.24,
"sourceCurrency": "GBP",
"targetCurrency": "USD",
"payIn": "BANK_TRANSFER",
"payOut": "BANK_TRANSFER",
"allowedProfileTypes": [
"PERSONAL",
"BUSINESS"
],
"payInProduct": "CHEAP",
"feePercentage": 0.0092
},
{
"disabled": true,
"estimatedDelivery": null,
"formattedEstimatedDelivery": null,
"estimatedDeliveryDelays": [],
"fee": {
"transferwise": 3.04,
"payIn": 0,
"discount": 0,
"partner": 0,
"total": 3.04
},
"price": {
"priceSetId": 238,
"total": {
"type": "TOTAL",
"label": "Total fees",
"value": {
"amount": 3.04,
"currency": "GBP",
"label:": "3.04 GBP"
}
},
"items": [
{
"type": "FEE",
"label": "fee",
"value": {
"amount": 0,
"currency": "GBP",
"label": "0 GBP"
}
},
{
"type": "TRANSFERWISE",
"label": "Our fee",
"value": {
"amount": 3.04,
"currency": "GBP",
"label": "3.04 GBP"
}
}
]
},
"sourceAmount": 100,
"targetAmount": 129,
"sourceCurrency": "GBP",
"targetCurrency": "USD",
"payIn": "BALANCE",
"payOut": "BANK_TRANSFER",
"allowedProfileTypes": [
"PERSONAL",
"BUSINESS"
],
"disabledReason": {
"code": "error.payInmethod.disabled",
"message": "Open a multi-currency account and add funds to instantly pay for your transfers."
},
"payInProduct": "BALANCE",
"feePercentage": 0.0111
}
],
"status": "PENDING",
"expirationTime": "2019-04-05T13:48:58Z",
"notices": [
{
"text": "You can have a maximum of 3 open transfers with a guaranteed rate. After that, they'll be transferred using the live rate. Complete or cancel your other transfers to regain the use of guaranteed rate.",
"link": null,
"type": "WARNING"
}
]
}
The quote resource 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. The profile must be included when creating a quote.
Quote is one of the required resources to create a transfer, along with the recipient who is to receive the funds.
The quote response contains other information such as the exchange rate, the estimated delivery time and the methods the user can pay for the transfer. Not all of this information may apply to your use case.
Upon creating a quote the current mid-market exchange rate is locked and will be used for the transfer that is created from the quote. The rate will be locked for 30 minutes to give a user time to complete the transfer creation flow.
Request
POST https://api.sandbox.transferwise.tech/v3/profiles/{profileId}/quotes
| Field | Description | Format |
|---|---|---|
| profileId | Personal or business profile id of the sender - required. | Integer |
| sourceCurrency | Source (sending) currency code. | Text |
| targetCurrency | Target (receiving) currency code. | Text |
| targetAmount | Amount in target currency. | Decimal |
| sourceAmount | Amount in source currency. Either sourceAmount or targetAmount is required, never both. |
Decimal |
| targetAccount | Optional. If provided can be used as an alternative to updating the quote. | Integer |
| payOut | Optional. Preferred payout method. Default value is BANK_TRANSFER. Other possible values are BALANCE, SWIFT, SWIFT_OUR and INTERAC. |
Text |
| preferredPayIn | Optional. Preferred payin method. Use BANK_TRANSFER to return this method at the top of the response's results. |
Text |
Note - When SWIFT_OUR is set as payOut value, it enables payment protection for swift recipients for global currency transfers. By using this payOut method, you can guarantee your customers that the fee will be charged to the sender and can ensure that the recipient gets the complete target amount.
Response
The following describes the fields of the quote response that may be useful when building your integration.
The payOut field is used to select the correct entry in the paymentOptions array in order to know which fees to display to your customer. Find the paymentOption that matches the payOut field shown at the top level of the quote resource and payIn based on the settlement model the bank is using. By default this is BANK_TRANSFER, unless you are using a prefunded or bulk settlement model. The payOut field will change based on the type of recipient you add to the quote in the PATCH /quote call, for example to-USD swift_code or to-CAD interac have different fees.
For example sending USD to a country other than the United States is supported but with different fees to domestic USD transfers. Please see the later section on Global Currencies to learn more about how to offer this useful feature.
For each paymentOption there is a price field. It gives a full breakdown of all the taxes, fees and discounts. It is preferable to refer to this structure to show breakdowns and totals, rather than the fee structre, found as well in each paymentOption element, that only gives a summary and is not able to surface important specifics such as taxes.
When showing the price of a transfer always show the 'price.total.value.amount' of a payment option.
Disabled Payment Options
Each payment option is either enabled or disabled based on the disabled value. Disabled payment options should be shown to the user in a disabled state in most cases. This ensures users are given the options that they are familiar with regardless of their availability, as well as with options that can be beneficial to their accounts.
The option.disabledReason contains both the code and message, with the message being the user-friendly text to surface to the user if necessary.
| Field | Description | Format |
|---|---|---|
| id | ID of this quote (GUID format). | Text |
| sourceCurrency | Source (sending) currency code. | Text |
| targetCurrency | Target (receive) currency code. | Text |
| sourceAmount | Amount in source currency to send. | Decimal |
| targetAmount | Amount in target currency to be received by the recipient. | Decimal |
| payOut | Mechanism we use to deliver the transfer. Not usually of interest to the user. | Text |
| rate | Exchange rate value used for the conversion. | Decimal |
| createdTime | Quote created timestamp. | Timestamp |
| user | User ID who created the quote. | Integer |
| profile | Personal or business profile id. | Integer |
| rateExpirationTime | Time the locked rate will expire. | Timestamp |
| providedAmountType | Whether the quote was created as "SOURCE" or "TARGET". | Text |
| paymentOptions | List of the methods a user can pay for the transfer. See above for help on choosing the correct one to display. | [PaymentOption] |
| option.disabled | Whether this option is enabled or not for this quote. | Boolean |
| option.estimatedDelivery | The estimated delivery time for this combination of payIn and payOut methods, assuming payIn is performed now. | Timestamp |
| option.formattedEstimatedDelivery | A string to display to users for the estimated delivery date. | Text |
| option.estimatedDeliveryDelays | Array of strings for delivery delays to display to users. | [Text] |
| option.fee | Object containing fee information. | Fee |
| option.fee.transferwise | The fee to be paid by the sender based on the current state of the quote. | Decimal |
| option.fee.payIn | The fee for this payment option, based on the product type of the payment option. | Decimal |
| option.fee.discount | Any discounts that have been applied to this quote for the user. | Decimal |
| option.fee.partner | If you have agreed a custom price, it will be displayed here. | Decimal |
| option.fee.total | The total fees to be paid - use this figure when displaying fees on your app. | Decimal |
| option.price | Object containing the price information. | Price |
| option.price.priceSetId | Id if the price structure. | Integer |
| option.price.total | The total fees to be paid - use this figure when displaying fees on your app. | Total |
| option.price.total.id | ID of this structure. | Integer |
| option.price.total.type | Type of the pricing element - "TOTAL" in this case. | Text |
| option.price.total.label | Short text describing the price structure this field is nested in. | Text |
| option.price.total.value | Object containing value elements. | Value |
| option.price.total.value.amount | Amount to be paid. | Decimal |
| option.price.total.value.currency | Currency of the amount to be paid. | Text |
| option.price.total.value.label | Text version of the price. | Text |
| option.price.total.explanation | Text element giving more details about the price. | Text |
| option.price.items | Object containing the detals of the different elements of the total price. | List |
| option.price.items.id | Id of this item. | Integer |
| option.price.items.type | Type of the pricing item. It could be "DISCOUNT" for example. | Text |
| option.price.items.label | Short text describing the pricing element. | Text |
| option.price.items.value | Object containing value elements. | Value |
| option.price.items.value.amount | Amount associated to this pricing element. Can be negative for discounts. | Decimal |
| option.price.items.value.currency | Currency on the pricing element. | Text |
| option.price.items.value.label | Text feild containing the price and its currency. | Text |
| option.price.items.explanation | Text element giving more details about the item. | Text |
| option.sourceAmount | sourceAmount when using this payment option. | Decimal |
| option.targetAmount | targetAmount when using this payment option. | Decimal |
| option.payIn | Type of pay in method for this payment option. | Text |
| option.payOut | Type of pay out method for this payment option. | Text |
| option.allowedProfileTypes | Array of the allowed types of profile to use this payment option for this quote "PERSONAL", "BUSINESS" or both. | [Text] |
| option.disabledReason | Object present if a payment option is disabled. | Disabled Reason |
| option.disabledReason.code | Code to denote the reason a payment method is unavailable. | Text |
| option.disabledReason.message | User friendly message to display when a method is unavailable. | Text |
| status | Current status of this quote, one of: "PENDING", "ACCEPTED", "FUNDED" or "EXPIRED". | Text |
| expirationTime | The time the quote expires. | Timestamp |
| notices | Array of messages to display to the user in case of useful information based on their selections. May be empty ([]) if there are no messages. |
[QuoteNotice] |
| notice.text | The message to display. | Text |
| notice.link | URL that provides more information to the message. May be null if there's no URL. |
Text |
| notice.type | Type of message, WARNING or INFO or BLOCKED. If it is BLOCKED, don't allow the quote to be used to create the transfer. |
Text |
Update Quote
Example Request:
curl -X PATCH \
https://api.sandbox.transferwise.tech/v3/profiles/101/quotes/11144c35-9fe8-4c32-b7fd-d05c2a7734bf \
-H 'Authorization: Bearer <your api token>' \
-H 'Content-Type: application/merge-patch+json' \
-d '{
"targetAccount": 12345,
"payOut": "SWIFT_OUR"
}'
| Field | Description | Format |
|---|---|---|
| targetAccount | ID of transfer recipient, found in response from POST v1/accounts (recipient creation) | Integer |
| payOut | Optional. Preferred payout method. Default value is BANK_TRANSFER. Other possible values are BALANCE, SWIFT, SWIFT_OUR and INTERAC. |
Text |
Example Response:
{
"id": "11144c35-9fe8-4c32-b7fd-d05c2a7734bf",
"sourceCurrency": "GBP",
"targetCurrency": "USD",
"sourceAmount": 100,
"payOut": "BANK_TRANSFER",
"rate": 1.30445,
"createdTime": "2019-04-05T13:18:58Z",
"user": 55,
"profile": 101,
"rateType": "FIXED",
"rateExpirationTime": "2019-04-08T13:18:57Z",
"guaranteedTargetAmountAllowed": true,
"targetAmountAllowed": true,
"guaranteedTargetAmount": false,
"providedAmountType": "SOURCE",
"targetAccount": 12345,
"paymentOptions": [
{
"disabled": false,
"estimatedDelivery": "2019-04-08T12:30:00Z",
"formattedEstimatedDelivery": "by Apr 8",
"estimatedDeliveryDelays": [],
"fee": {
"transferwise": 3.04,
"payIn": 0,
"discount": 2.27,
"partner": 0,
"total": 0.77
},
"price": {
"priceSetId": 238,
"total": {
"type": "TOTAL",
"label": "Total fees",
"value": {
"amount": 0.77,
"currency": "GBP",
"label:": "0.77 GBP"
}
},
"items": [
{
"type": "FEE",
"label": "fee",
"value": {
"amount": 0,
"currency": "GBP",
"label": "0 GBP"
}
},
{
"type": "TRANSFERWISE",
"label": "Our fee",
"value": {
"amount": 3.04,
"currency": "GBP",
"label": "3.04 GBP"
}
},
{
"type": "DISCOUNT",
"value": {
"amount": -2.27,
"currency": "GBP",
"label": "2.27 GBP"
},
"label": "Discount applied",
"explanation": {
"plainText": "You can have a discount for a number of reasons..."
}
}
]
},
"sourceAmount": 100,
"targetAmount": 129.24,
"sourceCurrency": "GBP",
"targetCurrency": "USD",
"payIn": "BANK_TRANSFER",
"payOut": "BANK_TRANSFER",
"allowedProfileTypes": [
"PERSONAL",
"BUSINESS"
],
"payInProduct": "CHEAP",
"feePercentage": 0.0092
},
{
"disabled": true,
"estimatedDelivery": null,
"formattedEstimatedDelivery": null,
"estimatedDeliveryDelays": [],
"fee": {
"transferwise": 3.04,
"payIn": 0,
"discount": 0,
"partner": 0,
"total": 3.04
},
"price": {
"priceSetId": 238,
"total": {
"type": "TOTAL",
"label": "Total fees",
"value": {
"amount": 3.04,
"currency": "GBP",
"label:": "3.04 GBP"
}
},
"items": [
{
"type": "FEE",
"label": "fee",
"value": {
"amount": 0,
"currency": "GBP",
"label": "0 GBP"
}
},
{
"type": "TRANSFERWISE",
"label": "Our fee",
"value": {
"amount": 3.04,
"currency": "GBP",
"label": "3.04 GBP"
}
}
]
},
"sourceAmount": 100,
"targetAmount": 129,
"sourceCurrency": "GBP",
"targetCurrency": "USD",
"payIn": "BALANCE",
"payOut": "BANK_TRANSFER",
"allowedProfileTypes": [
"PERSONAL",
"BUSINESS"
],
"disabledReason": {
"code": "error.payInmethod.disabled",
"message": "Open a multi-currency account and add funds to instantly pay for your transfers."
},
"payInProduct": "BALANCE",
"feePercentage": 0.0111
}
],
"status": "PENDING",
"expirationTime": "2019-04-05T13:48:58Z",
"notices": []
}
You should update a quote using a PATCH call to add a recipient. This will update the saved quote's data based on who and where the money will be sent to.
Updating the quote with a recipient may cause the available payment options, prices and estimated delivery times to change from the original quoted amounts. This is due to the fact that sending some currencies to some destinations costs a different amount based on the payment networks we use, for example sending USD to a country outside the USA uses international rather than domestic payment networks and as such costs more, or sending CAD over the Interac network is a more expensive operation.
When updating a quote the payOut field may change to denote the payment option you should select when sending to this recipient. For example sending USD to a swift_code recipient or CAD to an interac recipient with change payOut to SWIFT or INTERAC respectively. This field defaults to BANK_TRANSFER so it can be used in all cases to help select the correct paymentOption and hence show the correct pricing to users.
If you want to provide more transparency in terms of fees charged when your customers create quote with swift recipient for global currencies, you might consider to set payOut field with SWIFT_OUR value. This will ensure that the recipient receives complete target amount.
In this case, where pricing changes after a user selects recipient, you should show a message to your customer before confirming the transfer. Please see the section on Global Currencies to learn more how and why this works and the messaging you need to display.
Request
PATCH https://api.sandbox.transferwise.tech/v3/profiles/{profileId}/quotes/{quoteId}
Get By Id
Example Request:
curl -X GET https://api.sandbox.transferwise.tech/v3/profiles/{profileId}/quotes/{quoteId} \
-H "Authorization: Bearer <your api token>"
Example Response:
{
"id": "11144c35-9fe8-4c32-b7fd-d05c2a7734bf",
"sourceCurrency": "GBP",
"targetCurrency": "USD",
"sourceAmount": 100,
"payOut": "BANK_TRANSFER",
"rate": 1.30445,
"createdTime": "2019-04-05T13:18:58Z",
"user": 55,
"profile": 101,
"rateType": "FIXED",
"rateExpirationTime": "2019-04-08T13:18:57Z",
"guaranteedTargetAmountAllowed": true,
"targetAmountAllowed": true,
"guaranteedTargetAmount": false,
"providedAmountType": "SOURCE",
"paymentOptions": [
{
"disabled": false,
"estimatedDelivery": "2019-04-08T12:30:00Z",
"formattedEstimatedDelivery": "by Apr 8",
"estimatedDeliveryDelays": [],
"fee": {
"transferwise": 3.04,
"payIn": 0,
"discount": 2.27,
"partner": 0,
"total": 0.77
},
"price": {
"priceSetId": 238,
"total": {
"type": "TOTAL",
"label": "Total fees",
"value": {
"amount": 0.77,
"currency": "GBP",
"label:": "0.77 GBP"
}
},
"items": [
{
"type": "FEE",
"label": "fee",
"value": {
"amount": 0,
"currency": "GBP",
"label": "0 GBP"
}
},
{
"type": "TRANSFERWISE",
"label": "Our fee",
"value": {
"amount": 3.04,
"currency": "GBP",
"label": "3.04 GBP"
}
},
{
"type": "DISCOUNT",
"value": {
"amount": -2.27,
"currency": "GBP",
"label": "2.27 GBP"
},
"label": "Discount applied",
"explanation": {
"plainText": "You can have a discount for a number of reasons..."
}
}
]
},
"sourceAmount": 100,
"targetAmount": 129.24,
"sourceCurrency": "GBP",
"targetCurrency": "USD",
"payIn": "BANK_TRANSFER",
"payOut": "BANK_TRANSFER",
"allowedProfileTypes": [
"PERSONAL",
"BUSINESS"
],
"payInProduct": "CHEAP",
"feePercentage": 0.0092
},
{
"disabled": true,
"estimatedDelivery": null,
"formattedEstimatedDelivery": null,
"estimatedDeliveryDelays": [],
"fee": {
"transferwise": 3.04,
"payIn": 0,
"discount": 0,
"partner": 0,
"total": 3.04
},
"price": {
"priceSetId": 238,
"total": {
"type": "TOTAL",
"label": "Total fees",
"value": {
"amount": 3.04,
"currency": "GBP",
"label:": "3.04 GBP"
}
},
"items": [
{
"type": "FEE",
"label": "fee",
"value": {
"amount": 0,
"currency": "GBP",
"label": "0 GBP"
}
},
{
"type": "TRANSFERWISE",
"label": "Our fee",
"value": {
"amount": 3.04,
"currency": "GBP",
"label": "3.04 GBP"
}
}
]
},
"sourceAmount": 100,
"targetAmount": 129,
"sourceCurrency": "GBP",
"targetCurrency": "USD",
"payIn": "BALANCE",
"payOut": "BANK_TRANSFER",
"allowedProfileTypes": [
"PERSONAL",
"BUSINESS"
],
"disabledReason": {
"code": "error.payInmethod.disabled",
"message": "Open a multi-currency account and add funds to instantly pay for your transfers."
},
"payInProduct": "BALANCE",
"feePercentage": 0.0111
}
],
"status": "PENDING",
"expirationTime": "2019-04-05T13:48:58Z",
"notices": [{
"text": "You can have a maximum of 3 open transfers with a guaranteed rate. After that, they'll be transferred using the live rate. Complete or cancel your other transfers to regain the use of guaranteed rate.",
"link": null,
"type": "WARNING"
}]
}
Get quote info by id.
Request
GET https://api.sandbox.transferwise.tech/v3/profiles/{profileId}/quotes/{quoteId}
Get Temporary Quote
Use this endpoint to get example quotes for people to see the exchange rate and fees Wise offers before a user has created or linked an account. This can drive a version of the quote screen that shows the user what Wise offers before they sign up. Note that this endpoint does not require a token to create the resource, however, since it is just an example, the returned quote has no ID so can't be used later to create a transfer.
In order to get an accurate partner fee, we require a client credentials token to be provided. If you are a partner and would like your fee to be included in the quote returned, you must provide your auth token. If not, you do not require the Authorization header.
Example Request:
curl -X POST \
https://api.transferwise.com/v3/quotes/ \
-H "Authorization: Bearer <your client credentials token>"
-H 'Content-type: application/json' \
-d '{
"sourceCurrency": "GBP",
"targetCurrency": "USD",
"sourceAmount": null,
"targetAmount": 110
}'
Example Response:
{
"sourceCurrency": "GBP",
"targetCurrency": "USD",
"targetAmount": 110,
"payOut": "BANK_TRANSFER",
"rate": 1.30745,
"createdTime": "2019-04-09T11:46:38Z",
"rateType": "FIXED",
"guaranteedTargetAmountAllowed": true,
"targetAmountAllowed": true,
"guaranteedTargetAmount": false,
"providedAmountType": "TARGET",
"paymentOptions": [
{
"disabled": false,
"estimatedDelivery": "2019-04-08T12:30:00Z",
"formattedEstimatedDelivery": "by Apr 8",
"estimatedDeliveryDelays": [],
"fee": {
"transferwise": 3.04,
"payIn": 0,
"discount": 2.27,
"partner": 0,
"total": 0.77
},
"price": {
"priceSetId": 238,
"total": {
"type": "TOTAL",
"label": "Total fees",
"value": {
"amount": 0.77,
"currency": "GBP",
"label:": "0.77 GBP"
}
},
"items": [
{
"type": "FEE",
"label": "fee",
"value": {
"amount": 0,
"currency": "GBP",
"label": "0 GBP"
}
},
{
"type": "TRANSFERWISE",
"label": "Our fee",
"value": {
"amount": 3.04,
"currency": "GBP",
"label": "3.04 GBP"
}
},
{
"type": "DISCOUNT",
"value": {
"amount": -2.27,
"currency": "GBP",
"label": "2.27 GBP"
},
"label": "Discount applied",
"explanation": {
"plainText": "You can have a discount for a number of reasons..."
}
}
]
},
"sourceAmount": 100,
"targetAmount": 129.24,
"sourceCurrency": "GBP",
"targetCurrency": "USD",
"payIn": "BANK_TRANSFER",
"payOut": "BANK_TRANSFER",
"allowedProfileTypes": [
"PERSONAL",
"BUSINESS"
],
"payInProduct": "CHEAP",
"feePercentage": 0.0092
},
{
"disabled": true,
"estimatedDelivery": null,
"formattedEstimatedDelivery": null,
"estimatedDeliveryDelays": [],
"fee": {
"transferwise": 3.04,
"payIn": 0,
"discount": 0,
"partner": 0,
"total": 3.04
},
"price": {
"priceSetId": 238,
"total": {
"type": "TOTAL",
"label": "Total fees",
"value": {
"amount": 3.04,
"currency": "GBP",
"label:": "3.04 GBP"
}
},
"items": [
{
"type": "FEE",
"label": "fee",
"value": {
"amount": 0,
"currency": "GBP",
"label": "0 GBP"
}
},
{
"type": "TRANSFERWISE",
"label": "Our fee",
"value": {
"amount": 3.04,
"currency": "GBP",
"label": "3.04 GBP"
}
}
]
},
"sourceAmount": 85.28,
"targetAmount": 110,
"sourceCurrency": "GBP",
"targetCurrency": "USD",
"payIn": "BALANCE",
"payOut": "BANK_TRANSFER",
"allowedProfileTypes": [
"PERSONAL",
"BUSINESS"
],
"disabledReason": {
"code": "error.payInmethod.disabled",
"message": "Open a multi-currency account and add funds to instantly pay for your transfers."
},
"payInProduct": "BALANCE",
"feePercentage": 0.0135
}
],
"notices": []
}
Request
POST https://api.sandbox.transferwise.tech/v3/quotes/
| Field | Description | Format |
|---|---|---|
| sourceCurrency | Source (sending) currency code | Text |
| targetCurrency | Target (receiving) currency code | Text |
| sourceAmount | Amount in source currency. Either sourceAmount or targetAmount is required, never both. |
Decimal |
| targetAmount | Amount in target currency | Decimal |
Response
See Create quote's response field information.
Recipient Accounts
Create
Example Request (Create GBP recipient):
curl -X POST https://api.sandbox.transferwise.tech/v1/accounts \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"currency": "GBP",
"type": "sort_code",
"profile": <your profile id>,
"ownedByCustomer": true,
"accountHolderName": "Ann Johnson",
"details": {
"legalType": "PRIVATE",
"sortCode": "231470",
"accountNumber": "28821822"
}
}'
Example Response (Create GBP recipient):
{
"id": 13967081,
"business": null,
"profile": <your profile id>,
"accountHolderName": "Ann Johnson",
"currency": "GBP",
"country": "GB",
"type": "sort_code",
"details": {
"address": {
"country": null,
"countryCode": null,
"firstLine": null,
"postCode": null,
"city": null,
"state": null
},
"email": null,
"legalType": "PRIVATE",
"accountNumber": "28821822",
"sortCode": "231470",
"abartn": null,
"accountType": null,
"bankgiroNumber": null,
"ifscCode": null,
"bsbCode": null,
"institutionNumber": null,
"transitNumber": null,
"phoneNumber": null,
"bankCode": null,
"russiaRegion": null,
"routingNumber": null,
"branchCode": null,
"cpf": null,
"cardNumber": null,
"idType": null,
"idNumber": null,
"idCountryIso3": null,
"idValidFrom": null,
"idValidTo": null,
"clabe": null,
"swiftCode": null,
"dateOfBirth": null,
"clearingNumber": null,
"bankName": null,
"branchName": null,
"businessNumber": null,
"province": null,
"city": null,
"rut": null,
"token": null,
"cnpj": null,
"payinReference": null,
"pspReference": null,
"orderId": null,
"idDocumentType": null,
"idDocumentNumber": null,
"targetProfile": null,
"taxId": null,
"iban": null,
"bic": null,
"IBAN": null,
"BIC": null,
"interacAccount": null
},
"user": <your user ID>,
"active": true,
"ownedByCustomer": true
}
Recipient is a person or institution who is the ultimate beneficiary of your payment.
Recipient data includes three data blocks.
1) General Data
- Recipient full name
- Legal type (private/business)
- Currency
- Owned by customer
Owned by customer is an optional boolean to record whether this recipient is the same entity (person or business) as the one sending the funds. I.e. a user sending money to their own bank account in another country/currency. This field can be used to separate these recipients in your UI, however we do not recommend this as it adds unnecessary complexity to the solution. It is safe to ignore this field and display recipients with both true and false values.
2) Bank account data
There are many different variations of bank account details needed depending on recipient target currency. For example:
- GBP — sort code and account number
- BGN CHF, DKK, EUR, GEL, GBP, NOK, PKR, PLN, RON, SEK — IBAN
- USD — routing number, account number, account type
- INR — IFSC code, account number
- ...
3) Address data Recipient address data is required only if target currency is USD, PHP, THB or TRY, or if the source currency is USD or AUD.
- Country
- State (US, Canada, Brazil)
- City
- Address line
- Zip code
When creating recipient, the following general rules should be applied to "accountHolderName" field:
- Full names for personal recipients. They must include more than one name, and both first and last name must have more than one character.
- Business names must be in full, but can be just a single name. The full name cannot be just a single character but can be made up of a set of single characters. e.g. "A" is not permitted but "A 1" or "A1" is permitted.
- Digits are not allowed, except in business names.
- Special characters
_()'*,.are allowed for personal and business names. - Additionally, special characters
[]%#^@&{}"~<>are allowed for business names.
These requirements may vary depending of recipient type.
A GBP example is provided here. You can find other currency examples below.
As you can see many of the fields are null, in order to know which fields are required for which currency we expose the Recipients.Requirements endpoint.
Request
POST https://api.sandbox.transferwise.tech/v1/accounts
| Field | Description | Format | Optional |
|---|---|---|---|
| currency | 3 character currency code | Text | false |
| type | Recipient type | Text | false |
| profile | Personal or business profile id | Integer | false |
| accountHolderName | Recipient full name | Text | false |
| ownedByCustomer | Whether this account is owned by the sending user | Boolean | true |
| details | Currency specific fields | Object | false |
| details.legalType | Recipient legal type: PRIVATE or BUSINESS | Text | false |
| details.sortCode | Recipient bank sort code (GBP example) | Text | false |
| details.accountNumber | Recipient bank account no (GBP example) | Text | false |
Response
Recipient account id is needed for creating transfers in step 3. The profile ID you provided when creating your recipient will appear in the response. However, some older recipients may not have a profile ID specified.
| Field | Description | Format | Nullable |
|---|---|---|---|
| id | accountId | Integer | false |
| profile | Personal or business profile id | Integer | true |
| user | User that created or owns this recipient | Integer | false |
| acccountHolderName | Recipient full name | Text | false |
| currency | 3 character currency code | Text | false |
| country | 2 character country code | Text | false |
| type | Recipient type | Text | false |
| ownedByCustomer | Whether this account is owned by the sending user | Boolean | false |
| details | Currency specific fields | Object | false |
| details.legalType | Recipient legal type | Text | true |
| details.sortCode | Recipient bank sort code (GBP example) | Text | Currency Dependent |
| details.accountNumber | Recipient bank account no (GBP example) | Text | Currency Dependent |
Get By Id
Example Request:
curl -X GET https://api.sandbox.transferwise.tech/v1/accounts/{accountId} \
-H "Authorization: Bearer <your api token>"
Example Response:
{
"id": 13967081,
"profile": <your profile id>,
"accountHolderName": "Ann Johnson",
"type": "sort_code",
"country": "GB",
"currency": "GBP",
"details": {
"address": {
"country": null,
"countryCode": null,
"firstLine": null,
"postCode": null,
"city": null,
"state": null
},
"email": null,
"legalType": "PRIVATE",
"accountNumber": "28821822",
"sortCode": "231470",
"abartn": null,
"accountType": null,
"bankgiroNumber": null,
"ifscCode": null,
"bsbCode": null,
"institutionNumber": null,
"transitNumber": null,
"phoneNumber": null,
"bankCode": null,
"russiaRegion": null,
"routingNumber": null,
"branchCode": null,
"cpf": null,
"cardNumber": null,
"idType": null,
"idNumber": null,
"idCountryIso3": null,
"idValidFrom": null,
"idValidTo": null,
"clabe": null,
"swiftCode": null,
"dateOfBirth": null,
"clearingNumber": null,
"bankName": null,
"branchName": null,
"businessNumber": null,
"province": null,
"city": null,
"rut": null,
"token": null,
"cnpj": null,
"payinReference": null,
"pspReference": null,
"orderId": null,
"idDocumentType": null,
"idDocumentNumber": null,
"targetProfile": null,
"taxId": null,
"iban": null,
"bic": null,
"IBAN": null,
"BIC": null,
"interacAccount": null
},
"user": <your user ID>,
"active": true,
"ownedByCustomer": false
}
Get recipient account info by id.
Request
GET https://api.sandbox.transferwise.tech/v1/accounts/{accountId}
List
Example Request:
curl -X GET https://api.sandbox.transferwise.tech/v1/accounts?profile=<profileId>¤cy=GBP \
-H "Authorization: Bearer <your api token>"
Example Response:
[
{
"id": 13967081,
"profile": <your profile id>,
"accountHolderName": "Ann Johnson",
"type": "sort_code",
"country": "GB",
"currency": "GBP",
"details": {
"address": {
"country": null,
"countryCode": null,
"firstLine": null,
"postCode": null,
"city": null,
"state": null
},
"email": null,
"legalType": "PRIVATE",
"accountNumber": "28821822",
"sortCode": "231470",
"abartn": null,
"accountType": null,
"bankgiroNumber": null,
"ifscCode": null,
"bsbCode": null,
"institutionNumber": null,
"transitNumber": null,
"phoneNumber": null,
"bankCode": null,
"russiaRegion": null,
"routingNumber": null,
"branchCode": null,
"cpf": null,
"cardNumber": null,
"idType": null,
"idNumber": null,
"idCountryIso3": null,
"idValidFrom": null,
"idValidTo": null,
"clabe": null,
"swiftCode": null,
"dateOfBirth": null,
"clearingNumber": null,
"bankName": null,
"branchName": null,
"businessNumber": null,
"province": null,
"city": null,
"rut": null,
"token": null,
"cnpj": null,
"payinReference": null,
"pspReference": null,
"orderId": null,
"idDocumentType": null,
"idDocumentNumber": null,
"targetProfile": null,
"taxId": null,
"iban": null,
"bic": null,
"IBAN": null,
"BIC": null,
"interacAccount": null
},
"user": <your user ID>,
"active": true,
"ownedByCustomer": false
},
{
"id": 31273090,
"profile": <your profile id>,
"accountHolderName": "George Johnson",
"type": "sort_code",
"country": "GB",
"currency": "GBP",
"details": {
"address": {
"country": null,
"countryCode": null,
"firstLine": null,
"postCode": null,
"city": null,
"state": null
},
"email": null,
"legalType": "PRIVATE",
"accountNumber": "29912211",
"sortCode": "231470",
"abartn": null,
"accountType": null,
"bankgiroNumber": null,
"ifscCode": null,
"bsbCode": null,
"institutionNumber": null,
"transitNumber": null,
"phoneNumber": null,
"bankCode": null,
"russiaRegion": null,
"routingNumber": null,
"branchCode": null,
"cpf": null,
"cardNumber": null,
"idType": null,
"idNumber": null,
"idCountryIso3": null,
"idValidFrom": null,
"idValidTo": null,
"clabe": null,
"swiftCode": null,
"dateOfBirth": null,
"clearingNumber": null,
"bankName": null,
"branchName": null,
"businessNumber": null,
"province": null,
"city": null,
"rut": null,
"token": null,
"cnpj": null,
"payinReference": null,
"pspReference": null,
"orderId": null,
"idDocumentType": null,
"idDocumentNumber": null,
"targetProfile": null,
"taxId": null,
"iban": null,
"bic": null,
"IBAN": null,
"BIC": null,
"interacAccount": null
},
"user": <your user ID>,
"active": true,
"ownedByCustomer": true
}
]
Fetch a list of the user's recipient accounts. Use the currency and profile parameters to filter by currency and/or the owning user profile ID.
This list does not currently support pagination, therefore if please filter by currency to ensure a reasonable response time.
Request
GET https://api.sandbox.transferwise.tech/v1/accounts?profile=<profileId>¤cy=<currencyCode>
Both query parameters are optional.
| Field | Description | Format |
|---|---|---|
| profileId | Personal or business profile id | Integer |
| currency | Currency code | Text |
Delete
Example Request:
curl -X DELETE https://api.sandbox.transferwise.tech/v1/accounts/{accountId} \
-H "Authorization: Bearer <your api token>"
Deletes a recipient by changing its status to inactive. Only active recipients can be deleted and a recipient cannot be reactivated, however you can create a new recipient with the same details instead.
Response is empty if delete succeeds.
Requesting to delete recipient that is already inactive will return an http status 403 (forbidden).
Request
DELETE https://api.sandbox.transferwise.tech/v1/accounts/{accountId}
Requirements version 1.1
Example Request:
curl -X GET https://api.sandbox.transferwise.tech/v1/quotes/{quoteId}/account-requirements \
-H "Authorization: Bearer <your api token>"
-H "Accept-Minor-Version: 1"
Example Response:
[
{
"type": "south_korean_paygate",
"title": "PayGate",
"usageInfo": null,
"fields": [
{
"name": "E-mail",
"group": [
{
"key": "email",
"name": "E-mail",
"type": "text",
"refreshRequirementsOnChange": false,
"required": true,
"displayFormat": null,
"example": "example@example.ex",
"minLength": null,
"maxLength": null,
"validationRegexp": "^[^\\s]+@[^\\s]+\\.[^\\s]{2,}$",
"validationAsync": null,
"valuesAllowed": null
}
]
},
{
"name": "Recipient type",
"group": [
{
"key": "legalType",
"name": "Recipient type",
"type": "select",
"refreshRequirementsOnChange": false,
"required": true,
"displayFormat": null,
"example": "",
"minLength": null,
"maxLength": null,
"validationRegexp": null,
"validationAsync": null,
"valuesAllowed": [
{
"key": "PRIVATE",
"name": "Person"
}
]
}
]
},
{
"name": "Full Name",
"group": [
{
"key": "accountHolderName",
"name": "Full Name",
"type": "text",
"refreshRequirementsOnChange": false,
"required": true,
"displayFormat": null,
"example": "",
"minLength": 2,
"maxLength": 140,
"validationRegexp": "^[0-9A-Za-zÀ-ÖØ-öø-ÿ-_()'*,.%#^@{}~<>+$\"\\[\\]\\\\ ]+$",
"validationAsync": null,
"valuesAllowed": null
}
]
},
{
"name": "Recipient's Date of Birth",
"group": [
{
"key": "dateOfBirth",
"name": "Recipient's Date of Birth",
"type": "date",
"refreshRequirementsOnChange": false,
"required": true,
"displayFormat": null,
"example": "",
"minLength": null,
"maxLength": null,
"validationRegexp": "^\\d{4}\\-\\d{2}\\-\\d{2}$",
"validationAsync": null,
"valuesAllowed": null
}
]
},
{
"name": "Recipient Bank Name",
"group": [
{
"key": "bankCode",
"name": "Recipient Bank Name",
"type": "select",
"refreshRequirementsOnChange": false,
"required": true,
"displayFormat": null,
"example": "Choose recipient bank",
"minLength": null,
"maxLength": null,
"validationRegexp": null,
"validationAsync": null,
"valuesAllowed": [
{
"key": "",
"name": "Choose recipient bank"
},
...
]
}
]
},
{
"name": "Account number (KRW accounts only)",
"group": [
{
"key": "accountNumber",
"name": "Account number (KRW accounts only)",
"type": "text",
"refreshRequirementsOnChange": false,
"required": true,
"displayFormat": null,
"example": "1254693521232",
"minLength": 10,
"maxLength": 16,
"validationRegexp": null,
"validationAsync": null,
"valuesAllowed": null
}
]
}
]
},
Request
GET https://api.sandbox.transferwise.tech/v1/quotes/{quoteId}/account-requirements
POST https://api.sandbox.transferwise.tech/v1/quotes/{quoteId}/account-requirements
GET https://api.sandbox.transferwise.tech/v1/account-requirements?source=EUR&target=USD&sourceAmount=1000
You can use the data returned by this API to build a dynamic user interface for recipient creation. The third sample shows how to get account requirements for a specific currency route without referring to a particular quote but with the amount, source and target currencies passed as URL parameters.
The v1.1 version of GET and POST account requirements, enabled using the Accept-Minor-Version header enables you to fetch requirements which include both recipient name and email fields in the dynamic form, simplifying implementation of the form. Name and email address dynamic fields are required to support currencies such as KRW, JPY and RUB, and also simplify the use of dynamic forms by removing the need for manual name validation. Set the request header Accept-Minor-Version to 1 to use this version.
These endpoints support use of both v1 and v2 quotes using long or UUID based IDs.
Requirements
Example Request:
curl -X GET https://api.sandbox.transferwise.tech/v1/quotes/{quoteId}/account-requirements \
-H "Authorization: Bearer <your api token>"
Example Response:
[
{
"type": "aba",
"title": "Local bank account",
"fields": [
{
"name": "Recipient type",
"group": [
{
"key": "legalType",
"name": "Recipient type",
"type": "select",
"refreshRequirementsOnChange": false,
"required": true,
"displayFormat": null,
"example": "",
"minLength": null,
"maxLength": null,
"validationRegexp": null,
"validationAsync": null,
"valuesAllowed": [
{
"key": "PRIVATE",
"name": "Person"
},
{
"key": "BUSINESS",
"name": "Business"
}
]
}
]
},
{
"name": "ACH routing number",
"group": [
{
"key": "abartn",
"name": "ACH routing number",
"type": "text",
"refreshRequirementsOnChange": false,
"required": true,
"displayFormat": null,
"example": "026009593",
"minLength": 9,
"maxLength": 9,
"validationRegexp": "^\\d{9}$",
"validationAsync": null,
"valuesAllowed": null
}
]
},
{
"name": "Account number",
"group": [
{
"key": "accountNumber",
"name": "Account number",
"type": "text",
"refreshRequirementsOnChange": false,
"required": true,
"displayFormat": null,
"example": "12345678",
"minLength": 4,
"maxLength": 17,
"validationRegexp": "^\\d{4,17}$",
"validationAsync": null,
"valuesAllowed": null
}
]
},
{
"name": "Account type",
"group": [
{
"key": "accountType",
"name": "Account type",
"type": "radio",
"refreshRequirementsOnChange": false,
"required": true,
"displayFormat": null,
"example": "CHECKING",
"minLength": null,
"maxLength": null,
"validationRegexp": null,
"validationAsync": null,
"valuesAllowed": [
{
"key": "CHECKING",
"name": "Checking"
},
{
"key": "SAVINGS",
"name": "Savings"
}
]
}
]
},
{
"name": "Country",
"group": [
{
"key": "address.country",
"name": "Country",
"type": "select",
"refreshRequirementsOnChange": true,
"required": true,
"displayFormat": null,
"example": "",
"minLength": null,
"maxLength": null,
"validationRegexp": null,
"validationAsync": null,
"valuesAllowed": [
{
"key": "AF",
"name": "Afghanistan"
},
{
"key": "AL",
"name": "Albania"
},
{
...
}
]
}
]
},
{
"name": "City",
"group": [
{
"key": "address.city",
"name": "City",
"type": "text",
"refreshRequirementsOnChange": false,
"required": true,
"displayFormat": null,
"example": "",
"minLength": null,
"maxLength": null,
"validationRegexp": null,
"validationAsync": null,
"valuesAllowed": null
}
]
},
{
"name": "Address",
"group": [
{
"key": "address.firstLine",
"name": "Address",
"type": "text",
"refreshRequirementsOnChange": false,
"required": true,
"displayFormat": null,
"example": "",
"minLength": null,
"maxLength": null,
"validationRegexp": null,
"validationAsync": null,
"valuesAllowed": null
}
]
},
{
"name": "Post Code",
"group": [
{
"key": "address.postCode",
"name": "Post Code",
"type": "text",
"refreshRequirementsOnChange": false,
"required": true,
"displayFormat": null,
"example": "",
"minLength": null,
"maxLength": null,
"validationRegexp": null,
"validationAsync": null,
"valuesAllowed": null
}
]
}
]
},
Request
GET https://api.sandbox.transferwise.tech/v1/quotes/{quoteId}/account-requirements
POST https://api.sandbox.transferwise.tech/v1/quotes/{quoteId}/account-requirements
GET https://api.sandbox.transferwise.tech/v1/account-requirements?source=EUR&target=USD&sourceAmount=1000
The GET and POST account-requirements endpoints help you to figure out which fields are required to create a valid recipient for different currencies.
You can use these data to build a dynamic user interface on top of these endpoints. The third sample shows how to get account requirements for a specific currency route without referring to a particular quote but with the amount, source and target currencies passed as URL parameters.
This is a step-by-step guide on how these endpoints work.
Using account requirements
1.First create a quote to specify currencies and transfer amounts. See Create.Quote.
2.Call GET /v1/quotes/{quoteId}/account-requirements to get the list of fields you need to fill with values in the "details" section for creating a valid recipient account.
In order to create an "aba" recipient type you need these top level fields:
- legalType (PRIVATE / BUSINESS)
- abartn (ABA routing number)
- accountType (CHECKING / SAVINGS)
- address.country
- address.city
- address.postalCode
- address.firstLine
Some fields require multiple levels of fields in the details request, for example Country followed by State. This should be handled by the client based on the refreshRequirementsOnChange field. In the example above 'address.country' has this field set to true, indicating that there are additional fields required depending on the selected value. To manage this you should create a request with all of the initially requested data and call the POST account-requirements endpoint. You will be returned a response similar the previosuly returned data from GET account-requirements but with additional fields.
3.For example, construct a recipient object with all top level fields and call POST /v1/quotes/{quoteId}/account-requirements with these value to expose sub fields.
For example posting US as country will also add "state" to list of fields.
{
"type": "aba",
"details": {
"legalType": "PRIVATE",
"abartn": "111000025",
"accountNumber": "12345678",
"accountType": "CHECKING",
"address": {
"country": "US"
}
}
}
However, posting GB as country will not add any new fields as GB addresses do not have this extra requirement.
{
"type": "aba",
"details": {
"legalType": "PRIVATE",
"abartn": "111000025",
"accountNumber": "12345678",
"accountType": "CHECKING",
"address": {
"country": "GB"
}
}
}
It is possible that any new fields returned may also have refreshRequirementsOnChange field set to true. Therefore you must keep iterating on the partially created details object until POST account-requirements returns you no new fields that it previously didn't include in the response, you can do this by checking the size of the array returned.
4.Once you have built your full recipient details object you can use it to create a recipient.
For example this is a valid request to create a recipient with address in US Arizona:
POST /v1/accounts:
{
"profile": your-profile-id,
"accountHolderName": "John Smith",
"currency": "USD",
"type": "aba",
"details": {
"legalType": "PRIVATE",
"abartn": "111000025",
"accountNumber": "12345678",
"accountType": "CHECKING",
"address": {
"country": "US",
"state": "AZ"
"city": "New York",
"postCode": "10025",
"firstLine": "45 Sunflower Ave"
}
}
}
We do not require the recipient's address for most receiving currencies and as such do not return these form elements by default. In some cases it may be desirable for you to collect this from users and store it as part of the recipient object in the Wise platform. If you wish to do this you can include the parameter &addressRequired=true in your call to GET /v1/quotes/{quoteId}/account-requirements, if this is present we will return address fields as part of the form.
Building a user interface
Account requirements help us understand how to create a valid account given a certain context. As a tool to help explore this API, please visit Dynamic Forms UI. This app allows specifying different requests and calls our sandbox environment for account requirements. It then displays the response in JSON along with an example of the rendered form from the said response.
When requesting the form data from the account-requirements endpoint, the first level of the response defines different types of recipient you can create, the first thing to do is present the user a choice of which recipient type they wish to create, e.g. to GBP this could be local details or IBAN format. Each recipient type then has multiple fields describing the form elements required to be shown to collect information from the user. Each field will have a type value, these tell you the field type that your front end needs to render to be able to collect the data. A number of field types are permitted, these are:
| type | UI element |
|---|---|
| text | A free text box |
| select | A selection box/dialog |
| radio | A radio button choice between options |
| date | A text box with a date picker |
Example data is also included in each field which should be shown to the user, along with a regex or min and max length constraints that should be applied as field level validations. You can optionally implement the dynamic validation using the validationAsync field, however these checks wil also be done when a completed recipient is submitted to POST /v1/accounts.
Some good recipient currencies to test are:
- CAD - has several fields in a field group.
- USD - the country field has
refreshRequirementsOnChange. - JPY - the bank field has
refreshRequirementsOnChange. - KRW - has a field using a date component type.
Response
| Field | Description | Format |
|---|---|---|
| type | "address" | Text |
| fields[n].name | Field description | Text |
| fields[n].group[n].key | Key is name of the field you should include in the JSON | Text |
| fields[n].group[n].type | Display type of field (e.g. text, select, etc) | Text |
| fields[n].group[n].refreshRequirementsOnChange | Tells you whether you should call POST account-requirements once the field value is set to discover required lower level fields. | Boolean |
| fields[n].group[n].required | Indicates if the field is mandatory or not | Boolean |
| fields[n].group[n].displayFormat | Display format pattern. | Text |
| fields[n].group[n].example | Example value. | Text |
| fields[n].group[n].minLength | Min valid length of field value. | Integer |
| fields[n].group[n].maxLength | Max valid length of field value. | Integer |
| fields[n].group[n].validationRegexp | Regexp validation pattern. | Text |
| fields[n].group[n].validationAsync | Validator URL and parameter name you should use when submitting the value for validation | Text |
| fields[n].group[n].valuesAllowed[n].key | List of allowed values. Value key | Text |
| fields[n].group[n].valuesAllowed[n].name | List of allowed values. Value name. | Text |
Validate Recipient Fields
Example Request (Validate sort code (GBP):
curl -X GET https://api.sandbox.transferwise.tech/v1/validators/sort-code?sortCode=231470
Example Response (Validate sort code (GBP):
{
"validation": "success"
}
or
{
"errors": [
{
"code": "VALIDATION_NOT_SUCCESSFUL",
"message": "sortCode has not passed validation.",
"path": "sortCode",
"arguments": [
"2314701"
]
}
]
}
There are several validation URLs that make creating correct recipient accounts easier. These URLs are also included in fields provided by Recipient Accounts.Requirements endpoint.
GBP
Validate UK bank sort code
https://api.transferwise.com/v1/validators/sort-code?sortCode=231470
Validate UK bank account number
https://api.transferwise.com/v1/validators/sort-code-account-number?accountNumber=10000246
BGN CHF, DKK, EUR, GEL, GBP, NOK, PKR, PLN, RON, SEK
Validate IBAN
https://api.transferwise.com/v1/validators/iban?iban=EE867700771000187087
Validate BIC and IBAN
https://api.transferwise.com/v1/validators/bic?bic=LHVBEE22&iban=EE867700771000187087
USD
Validate ABA routing number
https://api.transferwise.com/v1/validators/abartn?abartn=011103093
Validate ABA bank account number
https://api.transferwise.com/v1/validators/aba-account-number?accountNumber=111000025
INR
Validate IFSC code
https://api.transferwise.com/v1/validators/ifsc-code?ifscCode=YESB0236041
Validate Indian bank account number
https://api.transferwise.com/v1/validators/indian-account-number?accountNumber=678911234567891
AUD
Validate BSB code
https://api.transferwise.com/v1/validators/bsb-code?bsbCode=112879
Validate Australian bank account number
https://api.transferwise.com/v1/validators/australian-account-number?accountNumber=123456789
CAD
Validate Canadian institution number
https://api.transferwise.com/v1/validators/canadian-institution-number?institutionNumber=006
Validate Canadian bank transit number
Validate Canadian bank account number
SEK Validate Bank Giro number
https://api.transferwise.com/v1/validators/bankgiro-number?bankgiroNumber=12345674
HUF
Validate Hungarian bank account number
PLN
Validate Polish bank account number
UAH
Validate Ukrainian bank account number
https://api.transferwise.com/v1/validators/privatbank-account-number?accountNumber=1234
Validate Ukrainian phone number
https://api.transferwise.com/v1/validators/privatbank-phone-number?phoneNumber=123456789
NZD
Validate New Zealand bank account number
AED
Validate United Arab Emirates BIC code
https://api.transferwise.com/v1/validators/emirates-bic?bic=BOMLAEAD&iban=AE070331234567890123456
CNY
Validate Chinese Union Pay card number
https://api.transferwise.com/v1/validators/chinese-card-number?cardNumber=6240008631401148
THB
Validate Thailand bank account number
Banks and Branches
Example Request (Get list of banks for Hong Kong):
curl -X GET https://api.sandbox.transferwise.tech/v1/banks?country=HK \
-H "Authorization: Bearer <your api token>"
Example Response (Get list of banks for Hong Kong):
{
"values": [
{
"code": "003",
"title": "STANDARD CHARTERED BANK (HONG KONG) LIMITED"
},
{
"code": "552",
"title": "AAREAL BANK AG, WIESBADEN, GERMANY"
},
{
"code": "307",
"title": "ABN AMRO BANK N.V."
},
{
"code": "222",
"title": "AGRICULTURAL BANK OF CHINA LIMITED"
},
{
"code": "525",
"title": "ZIBO CITY COMMERCIAL BANK, SHANDONG"
}
]
}
Example Request (Get list of bank branches for a Hong Kong bank with code 003):
curl -X GET https://api.sandbox.transferwise.tech/v1/bank-branches?country=HK&bankCode=003 \
-H "Authorization: Bearer <your api token>"
Example Response (Get list of bank branches for a Hong Kong bank with code 003):
{
"country": "HK",
"values": [
{
"code": "251",
"title": "Quarry Bay Branch [251]",
"parentCode": "003"
},
{
"code": "983",
"title": "Canton Road Branch [983]",
"parentCode": "003"
},
{
"code": "984",
"title": "Tuen Mun Branch [984]",
"parentCode": "003"
},
{
"code": "985",
"title": "Kwun Tong Branch [985]",
"parentCode": "003"
}
]
}
Get list of banks by country code
List of banks is available for these countries: BD, BR, CZ, CL, EG, GH, HK, ID, IL, IN, JP, KE, LK, MA, NG, NP, PE, PH, RU, SG, TH, VN, ZA
GET https://api.sandbox.transferwise.tech/v1/banks?country=HK
Get list of branches by country and bank code
List of bank branches is available for these countries: BD, GH, HK, IL, IN, JP, LK, SG, VN
GET https://api.sandbox.transferwise.tech/v1/bank-branches?country=HK&bankCode=<bankCode>
Countries and States
Example Request (Get list of allowed countries):
curl -X GET https://api.sandbox.transferwise.tech/v1/countries \
-H "Authorization: Bearer <your api token>"
Example Response (Get list of allowed countries):
{
"values": [
{
"code": "AL",
"name": "Albania"
},
{
"code": "DZ",
"name": "Algeria"
},
...
{
"code": "ZW",
"name": "Zimbabwe"
},
{
"code": "AX",
"name": "Åland Islands"
}
]
}
Example Request (Get list of states for a country code US):
curl -X GET https://api.sandbox.transferwise.tech/v1/countries/US/states \
-H "Authorization: Bearer <your api token>"
Example Response (Get list of states for a country code US):
{
"values": [
{
"code": "AL",
"name": "Alabama"
},
{
"code": "AK",
"name": "Alaska"
},
...
{
"code": "PR",
"name": "Puerto Rico"
},
{
"code": "VI",
"name": "Virgin Islands"
}
]
}
Get list of countries
List of allowed countries to be used in recipient or user-profile addresses.
GET https://api.sandbox.transferwise.tech/v1/countries
Get list of states by country code
List of states is available for these countries: US, CA, BR, AU.
GET https://api.sandbox.transferwise.tech/v1/countries/{countryCode}/states
Create AED Recipient
Example Request (AED):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "AED",
"type": "emirates",
"legalType": "PRIVATE",
"details": {
"IBAN": "AE070331234567890123456"
}
}'
Send payments to United Arab Emirates.
Private and business recipients are supported.
Recipient type = 'emirates'
Required details: IBAN
Create ARS Recipient
Example Request (ARS):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "ARS",
"type": "argentina",
"details": {
"legalType": "PRIVATE",
"taxId": "20-34149938-1",
"accountNumber": "0110482420048200036238"
}
}'
Send payments to Argentina.
Private and business recipients are supported.
Recipient type = 'argentina'
Required details:
taxId - Recipient’s CUIT / CUIL (Single Tax Identification/ Single Labor Identification), 11 characters
accountNumber - Recipient’s account CBU, 22 characters (Alias not supported)
Create AUD Recipient
Example Request (AUD australian):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "AUD",
"type": "australian",
"details": {
"address": {
"city": "New York",
"countryCode": "US",
"postCode": "10025",
"state": "NY",
"firstLine": "158 Wall Street"
},
"legalType": "PRIVATE",
"bsbCode": "182512",
"accountNumber": "123456789"
}
}'
Example Request for business recipient
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "AUD",
"type": "australian",
"details": {
"address": {
"city": "New York",
"countryCode": "US",
"postCode": "10025",
"state": "NY",
"firstLine": "158 Wall Street"
},
"legalType": "BUSINESS",
"bsbCode": "182512",
"accountNumber": "123456789"
}
}'
Example Request for BPay recipient
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "AUD",
"legalType":"BUSINESS",
"details":{
"address": {
"city": "New York",
"countryCode": "US",
"postCode": "10025",
"state": "NY",
"firstLine": "158 Wall Street"
},
"billerCode":"12345",
"customerReferenceNumber":"1234567890"
},
"type":"australian_bpay"
}'
Send payments to Australia.
Recipient type = 'australian'
Private and business recipients are supported.
Required details:
bsbCode - 6 digits
accountNumber - 4..9 digits
OR
Recipient type = 'australian_bpay'
Only business recipients are supported.
Required details:
billerCode - 3..10 digits
customerReferenceNumber - 2..20 digits
Create BDT Recipient
Example Request (BDT):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "BDT",
"type": "bangladesh",
"details": {
"legalType": "PRIVATE",
"bankCode": "015",
"branchCode": "015270362",
"accountNumber": "5060011118"
}
}'
Send payments to Bangladesh.
Recipient type = 'iban'
Required details: bankCode, branchCode, accountNumber
Lists of banks and branches can be obtained from Banks and Branches endpoints.
You can also get list of bank and branch codes by using /v1/quotes/{quoteId}/account-requirements endpoint.
Create BGN Recipient
Example Request (BGN):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "BGN",
"type": "iban",
"details": {
"legalType": "PRIVATE",
"IBAN": "BG89370400440532013000"
}
}'
Send payments to Bulgaria.
Private and business recipients are supported.
Recipient type = 'iban'
Required details: IBAN
Create BRL Recipient
Example Request (BRL):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "BRL",
"type": "brazil",
"details": {
"legalType": "PRIVATE",
"bankCode": "218",
"branchCode": "1234",
"accountNumber": "12345678-9",
"accountType": "CHECKING",
"cpf": "123.456.789-12",
"phoneNumber": "+55 21 5555 5555"
}
}'
Send payments to Brazil.
Recipient type = 'brazil'
Required details: bankCode, branchCode, accountNumber, accountType (CHECKING or SAVINGS), cpf (tax reg no), recipient phone number
Lists of banks and branches can be obtained from Banks and Branches endpoints.
You can also get list of bank and branch codes by using /v1/quotes/{quoteId}/account-requirements endpoint.
Create CAD Recipient
Example Request (CAD):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "CAD",
"type": "canadian",
"details": {
"legalType": "PRIVATE",
"institutionNumber": "006",
"transitNumber": "04841",
"accountNumber": "3456712",
"accountType": "Checking",
}
}'
Send payments to Canada.
Private and business recipients are supported.
Recipient type = 'canadian'
Required details: institutionNumber, transitNumber, accountNumber, accountType (Checking or Saving)
Create CAD Interac Recipient
Example Request (CAD):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "CAD",
"type": "interac",
"details": {
"interacAccount": "<recipient email>",
}
}'
Send payments to Canada via Interac.
Private and business recipients are supported. 10,000 CAD max per payment.
Recipient type = 'interac'
Required details: interacAccount
Create CHF Recipient
Example Request (CHF):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "CHF",
"type": "iban",
"details": {
"legalType": "PRIVATE",
"IBAN": "CH89370400440532013000",
"town": "Zürich",
"postCode": 8037
}
}'
Send payments to Switzerland.
Private and business recipients are supported.
Recipient type = 'iban'
Required details: IBAN
Required details: IBAN, town, postcode
Where town and postcode are the recipient's home town and postcode.
If the recpient's country does not use a postcode, then please fill it with 0 (zero).
Create CLP Recipient
Example Request (CLP):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "CLP",
"type": "chile",
"details": {
"legalType": "PRIVATE",
"bankCode": "504",
"accountNumber": "12345678901234567890",
"rut": "760864285",
"accountType": "CHECKING",
"phoneNumber": "+56 33 555 5555"
}
}'
Send payments to Chile.
Private and business recipients are supported.
Recipient type = 'chile'
Required details: bankCode, accountNumber, rut (Rol Único Tributario), accountType (CHECKING, SAVINGS, CUENTA_VISTA), recipient phone number
Lists of banks and branches can be obtained from Banks and Branches endpoints.
You can also get list of bank and branch codes by using /v1/quotes/{quoteId}/account-requirements endpoint.
Create CNY Recipient
Example Request (CNY Alipay id):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": <recipient name>,
"currency": "CNY",
"type": "chinese_alipay",
"details": {
"legalType": "PRIVATE",
"accountNumber": "email@example.com"
}
}'
Example Request (CNY Weixin recipient):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "CNY",
"type": "chinese_wechatpay",
"details": {
"legalType": "PRIVATE",
"accountNumber": "+86-12345678901",
}
}'
Example Request (CNY business recipient):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "CNY",
"type": "chinese_local_business",
"details": {
"legalType": "BUSINESS",
"accountNumber": "373929340923",
"swiftCode": "CHASCNSH",
"address": {
"city": "Shanghai",
"country": "CN",
"firstLine": "No.999 Zhongshan West Road",
"postCode": "200051"
}
}
}'
Recipient type = 'chinese_alipay'
Required details: accountNumber - Chinese mobile number or email
OR
Recipient type = 'chinese_wechatpay'
Required details: accountNumber - Chinese mobile number
OR
Recipient type = 'chinese_local_business'
Required details: accountNumber, swiftCode, address of the recipient
Create CZK Recipient
Example Request (CZK Local):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "CZK",
"type": "czech",
"details": {
"legalType": "PRIVATE",
"prefix": "000000",
"accountNumber": "5060011118",
"bankCode": "5500"
}
}'
Example Request (CZK IBAN):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "CZK",
"type": "iban",
"details": {
"legalType": "PRIVATE",
"IBAN": "CZ89370400440532013000"
}
}'
Send payments to Czech Republic.
Private and business recipients are supported.
Recipient type = 'czech'
Required details: prefix, accountNumber, bankCode
Lists of banks and branches can be obtained from Banks and Branches endpoints.
You can also get list of bank and branch codes by using /v1/quotes/{quoteId}/account-requirements endpoint.
OR
Recipient type = 'iban'
Required details: IBAN
Create DKK Recipient
Example Request (DKK):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "DKK",
"type": "iban",
"details": {
"legalType": "PRIVATE",
"IBAN": "DK89370400440532013000"
}
}'
Send payments to Denmark.
Private and business recipients are supported.
Recipient type = 'iban'
Required details: IBAN
Create EGP Recipient
Example Request (EGP):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "EGP",
"type": "iban",
"details": {
"legalType": "PRIVATE",
"IBAN": "EG380019000500000000263180002"
}
}'
Send payments to Egypt.
Private and business recipients are supported.
Recipient type = 'iban'
Required details: IBAN
Create EUR Recipient
Example Request (EUR):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "EUR",
"type": "iban",
"details": {
"legalType": "PRIVATE",
"IBAN": "DE89370400440532013000"
}
}'
Send payments to Eurozone countries: Austria, Belgium, Cyprus, Estonia, Finland, France, Germany, Greece, Ireland, Italy, Latvia, Lithuania, Luxembourg, Malta, Netherlands, Portugal, Slovakia, Slovenia, Spain.
Private and business recipients are supported.
Recipient type = 'iban'
Required details: IBAN
Create GBP Recipient
Example Request (GBP Sort Code):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "GBP",
"type": "sort_code",
"details": {
"legalType": "PRIVATE",
"sortCode": "40-30-20",
"accountNumber": "12345678"
}
}'
Example Request (GBP IBAN):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "GBP",
"type": "iban",
"details": {
"legalType": "PRIVATE",
"IBAN": "GB89370400440532013000"
}
}'
Send payments to United Kingdom.
Private and business recipients are supported.
Recipient type = 'sort_code'
Required details: sortCode, accountNumber
OR
Recipient type = 'iban'
Required details: IBAN
Create GEL Recipient
Example Request (GEL):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "GEL",
"type": "iban",
"details": {
"legalType": "PRIVATE",
"IBAN": "GE89370400440532013000"
}
}'
Send payments to Georgia.
Private and business recipients are supported.
Recipient type = 'iban'
Required details: IBAN
Create GHS Recipient
Example Request (GHS):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "GHS",
"type": "ghana_local",
"details": {
"legalType": "PRIVATE",
"bankCode": "030100",
"accountNumber": "0011XXXXXXXXXX"
}
}'
Send payments to Ghana.
Private and business recipients are supported.
Recipient type = 'ghana_local'
Required details: bankCode, accountNumber
Lists of banks and branches can be obtained from Banks and Branches endpoints.
You can also get list of bank and branch codes by using /v1/quotes/{quoteId}/account-requirements endpoint.
Create HKD Recipient
Example Request (HKD):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"accountHolderName": "<recipient name>",
"currency": "HKD",
"type": "hongkong",
"details": {
"legalType": "PRIVATE",
"bankCode": "307",
"accountNumber": "005-231289-112"
}
}'
Send payments to Hong Kong.
Private and business recipients are supported.
Recipient type = 'hongkong'
Required details: bankCode, accountNumber
Lists of banks and branches can be obtained from Banks and Branches endpoints.
You can also get list of bank and branch codes by using /v1/quotes/{quoteId}/account-requirements endpoint.
Create HRK Recipient
Example Request:
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "HRK",
"type": "iban",
"details": {
"legalType": "PRIVATE",
"IBAN": "HR89370400440532013000"
}
}'
Send payments to Croatia.
Private and business recipients are supported.
Recipient type = 'iban'
Required details: IBAN
Create HUF Recipient
Example Request (HUF Local):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "HUF",
"type": "hungarian",
"details": {
"legalType": "PRIVATE",
"accountNumber": "12000000-12345678-00000000"
}
}'
Example Request (HUF IBAN):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "HUF",
"type": "iban",
"details": {
"legalType": "PRIVATE",
"IBAN": "HU89370400440532013000"
}
}'
Send payments to Hungary.
Private and business recipients are supported.
Recipient type = 'hungarian'
Required details: accountNumber
OR
Recipient type = 'iban'
Required details: IBAN
Create IDR Recipient
Example Request (IDR):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "IDR",
"type": "indonesian",
"details": {
"legalType": "PRIVATE",
"bankCode": "610306",
"accountNumber": "6789112345678"
}
}'
Send payments to Indonesia.
Private and business recipients are supported.
Recipient type = 'indonesian'
Required details: bankCode, accountNumber
Lists of banks and branches can be obtained from Banks and Branches endpoints.
You can also get list of bank and branch codes by using /v1/quotes/{quoteId}/account-requirements endpoint.
Create ILS Recipient
Example Request (ILS IBAN):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "ILS",
"type": "israeli_local",
"details": {
"legalType": "PRIVATE",
"IBAN": "IL620108000000099999999"
}
}'
Send payments to Israel.
Private and business recipients are supported.
Recipient type = 'israeli_local'
Required details: IBAN
Create INR Recipient
Example Request (INR):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "INR",
"type": "indian",
"details": {
"legalType": "PRIVATE",
"ifscCode": "YESB0236041",
"accountNumber": "678911234567891",
}
}'
Send payments to India.
Private and business recipients are supported.
Recipient type = 'indian'
Required details: ifscCode, accountNumber
Lists of banks and branches can be obtained from Banks and Branches endpoints.
You can also get list of bank and branch codes by using /v1/quotes/{quoteId}/account-requirements endpoint.
Create JPY Recipient
Example Request (JPY):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "JPY",
"type": "japanese",
"details": {
"legalType": "PRIVATE",
"bankCode": "6470",
"branchCode": "100",
"accountType": "CURRENT",
"accountNumber": "1234567"
}
}'
Send payments to Japan.
Private and business recipients are supported.
Recipient type = 'japanese'
Required details: bankCode, branchCode accountNumber, accountType (CURRENT, SAVINGS, CHECKING),
Lists of banks and branches can be obtained from Banks and Branches endpoints.
You can also get list of bank and branch codes by using /v1/quotes/{quoteId}/account-requirements endpoint.
Create KES Recipient
Example Request (KES Bank Account):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "KES",
"type": "kenya_local",
"details": {
"legalType": "PRIVATE",
"bankCode": "35",
"accountNumber": "0023183991919"
}
}'
Example Request (KES Mobile MPESA):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "KES",
"type": "kenya_mobile",
"details": {
"legalType": "PRIVATE",
"accountNumber": "2547XXXXXXXX"
}
}'
Send payments to Kenya.
Private and business recipients are supported. However please note that only individuals can hold MPESA accounts.
Recipient type = 'kenya_local'
Required details: bankCode, accountNumber
Lists of banks and branches can be obtained from Banks and Branches endpoints.
You can also get list of bank and branch codes by using /v1/quotes/{quoteId}/account-requirements endpoint.
OR
Recipient type = 'kenya_mobile'
Required details: accountNumber - mobile number
Create KRW Recipient
Example Request (KRW PayGate):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipients name>",
"currency": "KRW",
"type": "south_korean_paygate",
"details": {
"legalType": "PRIVATE",
"bankCode": "BUSAN_032",
"accountNumber": "1254693521232",
"dateOfBirth" : "yyyy-mm-dd",
"email": "<recipients email>"
}
}'
Example Request (KRW PayGate to Business):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient business name>",
"currency": "KRW",
"type": "south_korean_paygate_business",
"details": {
"legalType": "BUSINESS",
"bankCode" : "BUSAN_032",
"accountNumber": "1254693521232"
}
}'
Send payments to South Korea.
Private and business recipients are supported.
Recipient type = 'south_korean_paygate'
Required details: bankCode, accountNumber, dateOfBirth, email
Lists of banks and branches can be obtained from Banks and Branches endpoints.
You can also get list of bank and branch codes by using /v1/quotes/{quoteId}/account-requirements endpoint.
OR
Recipient type = 'south_korean_paygate_business'
Required details: bankCode, accountNumber
Create LKR Recipient
Example Request (LKR):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "LKR",
"type": "srilanka",
"details": {
"legalType": "PRIVATE",
"bankCode": "7214",
"branchCode": "100",
"accountNumber": "5060011118"
}
}'
Send payments to Sri Lanka.
Private and business recipients are supported.
Recipient type = 'srilanka'
Required details: bankCode, branchCode, accountNumber
Lists of banks and branches can be obtained from Banks and Branches endpoints.
You can also get list of bank and branch codes by using /v1/quotes/{quoteId}/account-requirements endpoint.
Create MAD Recipient
Example Request (MAD):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "MAD",
"type": "morocco",
"details": {
"legalType": "PRIVATE",
"bankCode": "BCMAMAMC",
"accountNumber": "123456789012345678901234"
}
}'
Send payments to Morocco.
Private and business recipients are supported. 260,000 MAD per transaction
Recipient type = 'morocco'
Required details: bankCode, accountNumber
Lists of banks and branches can be obtained from Banks and Branches endpoints.
You can also get list of bank and branch codes by using /v1/quotes/{quoteId}/account-requirements endpoint.
Create MXN Recipient
Example Request (MXN):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "MXN",
"type": "mexican",
"details": {
"legalType": "PRIVATE",
"clabe": "032180000118359719"
}
}'
Send payments to Mexico.
Private and business recipients are supported.
Recipient type = 'mexican'
Required details: clabe
Create MYR Recipient
Example Request (MYR):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "MYR",
"type": "malaysian",
"details": {
"legalType": "PRIVATE",
"swiftCode": "ABNAMYKL",
"accountNumber": "159012938613"
}
}'
Send payments to Malaysia.
Private and business recipients are supported. Maximum amount is 10,000,000 MYR per payment.
Recipient type = 'malaysian'
Required details: swiftCode, accountNumber
Create NGN Recipient
Example Request (NGN):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "NGN",
"type": "nigeria",
"details": {
"legalType": "PRIVATE",
"bankCode": "044",
"accountNumber": "0584412903"
}
}'
Send payments to Nigeria.
Private and business recipients are supported. Maximum amount is 2,000,000 NGN per payment.
Recipient type = 'nigeria'
Required details: bankCode, accountNumber
Lists of banks and branches can be obtained from Banks and Branches endpoints.
You can also get list of bank and branch codes by using /v1/quotes/{quoteId}/account-requirements endpoint.
Create NOK Recipient
Example Request (NOK):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "NOK",
"type": "iban",
"details": {
"legalType": "PRIVATE",
"IBAN": "DE89370400440532013000"
}
}'
Send payments to Norway.
Private and business recipients are supported.
Recipient type = 'iban'
Required details: IBAN
Create NPR Recipient
Example Request (NPR):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "NPR",
"type": "nepal",
"legalType": "PRIVATE",
"details": {
"bankCode": "977056",
"accountNumber": "1234567890"
}
}'
Send payments to Nepal.
Private recipients are supported. 1mln NPR per transaction / per month for individual account.
Recipient type = 'nepal'
Required details: bankCode, accountNumber
Lists of banks and branches can be obtained from Banks and Branches endpoints.
You can also get list of bank and branch codes by using /v1/quotes/{quoteId}/account-requirements endpoint.
Create NZD Recipient
Example Request (NZD):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "NZD",
"type": "newzealand",
"details": {
"legalType": "PRIVATE",
"accountNumber": "03-1587-0050000-00"
}
}'
Send payments to New Zealand.
Recipient type = 'newzealand'
Required details: accountNumber
Create PHP Recipient
Example Request (PHP):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "PHP",
"type": "philippines",
"details": {
"legalType": "PRIVATE",
"bankCode": "AMA",
"accountNumber": "0044XXXXXXXX",
"address" : {
"country": "GB",
"city": "London",
"postCode": "10025",
"firstLine": "50 Branson Ave"
}
}
}'
Send payments to Philippines.
Private and business recipients are supported. 480,000 PHP per payment.
Recipient type = 'philippines'
Required details: bankCode, accountNumber, recipient address
Lists of banks and branches can be obtained from Banks and Branches endpoints.
You can also get list of bank and branch codes by using /v1/quotes/{quoteId}/account-requirements endpoint.
Create PKR Recipient
Example Request (PKR):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "PKR",
"type": "iban",
"details": {
"legalType": "PRIVATE",
"IBAN": "PK89370400440532013000"
}
}'
Send payments to Pakistan. Max 1 million PKR per payment.
Recipient type = 'iban'
Required details: IBAN
Create PLN Recipient
Example Request (PLN IBAN):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "PLN",
"type": "iban",
"details": {
"legalType": "PRIVATE",
"IBAN": "PL89370400440532013000"
}
}'
Example Request (PLN Local):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "PLN",
"type": "polish",
"details": {
"legalType": "PRIVATE",
"accountNumber": "109010140000071219812874"
}
}'
Send payments to Poland.
Private and business recipients are supported.
Recipient type = 'iban'
Required details: IBAN
OR
Recipient type = 'polish'
Required details: accountNumber
Create RON Recipient
Example Request (RON):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "RON",
"type": "iban",
"details": {
"legalType": "PRIVATE",
"IBAN": "RO89370400440532013000"
}
}'
Send payments to Romania.
Private and business recipients are supported.
Recipient type = 'iban'
Required details: IBAN
Create RUB Recipient
Example Request (RUB):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "RUB",
"type": "russiarapida",
"details": {
"legalType": "PRIVATE",
"bankCode": "044525290",
"accountNumber": "40820810999999999999",
"russiaRegion": "ALTAIKRAI",
"address" : {
"country": "GB",
"city": "London",
"postCode": "10025",
"firstLine": "50 Branson Ave"
}
}
}'
Send payments to Russia.
Recipient type = 'russiarapida'
Required details: bankCode, accountNumber, region, recipient address.
You have to provide first, last and patronymic names in Cyrillic, in order for your transfer to be accepted by the recipient bank. (unless the recipient is registered at the bank with no patronymic)
You can get list of bank, region and country codes by using /v1/quotes/{quoteId}/account-requirements endpoint.
Lists of banks and branches can be obtained from Banks and Branches endpoints.
Create SEK Recipient
Example Request (SEK IBAN):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "SEK",
"type": "iban",
"details": {
"legalType": "PRIVATE",
"IBAN": "SE89370400440532013000"
}
}'
Example Request (SEK Local):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "SEK",
"type": "sweden_local",
"details": {
"legalType": "PRIVATE",
"clearingNumber": "1234",
"accountNumber": "1234567"
}
}'
Example Request (SEK BankGiro):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "SEK",
"type": "bankgiro",
"details": {
"legalType": "PRIVATE",
"bankgiroNumber": "1234-5678"
}
}'
Send payments to Sweden.
Private and business recipients are supported.
Recipient type = 'iban'
Required details: IBAN
OR
Recipient type = 'sweden_local'
Required details: clearingNumber, accountNumber
OR
Recipient type = 'bankgiro'
Required details: bankgiroNumber
Create SGD Recipient
Example Request (SGD):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "SGD",
"type": "singapore",
"details": {
"legalType": "PRIVATE",
"bankCode": "7418",
"accountNumber": "1238827822"
}
}'
Send payments to Singapore.
Private and business recipients are supported.
Recipient type = 'singapore'
Required details: bankCode, accountNumber
Lists of banks and branches can be obtained from Banks and Branches endpoints.
You can also get list of bank and branch codes by using /v1/quotes/{quoteId}/account-requirements endpoint.
Create THB Recipient
Example Request (THB):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "THB",
"type": "thailand",
"details": {
"legalType": "PRIVATE",
"bankCode": "002",
"accountNumber": "9517384260"
"address" : {
"country": "GB",
"city": "London",
"postCode": "10025",
"firstLine": "50 Branson Ave"
}
}
}'
Send payments to Thailand. Max 2 mln THB per payment.
Private and business recipients are supported.
Recipient type = 'thailand'
Required details: bankCode, accountNumber
Lists of banks and branches can be obtained from Banks and Branches endpoints.
You can also get list of bank and branch codes by using /v1/quotes/{quoteId}/account-requirements endpoint.
Create TRY Recipient
Example Request (TRY):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "TRY",
"type": "turkish_earthport",
"details": {
"legalType": "PRIVATE",
"IBAN": "TR330006100519786457841326"
}
}'
Send payments to Turkey.
Private and business recipients are supported. 1 000 000 TRY per payment.
Recipient type = 'turkish_earthport'
Required details: IBAN
Create UAH Recipient
Example Request (UAH):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": {{profileId}},
"accountHolderName": "<recipient name>",
"currency": "UAH",
"type": "privatbank",
"details": {
"legalType": "PRIVATE",
"phoneNumber": "777210012",
"accountNumber": "2662",
"address": {
"firstLine": "1 A ROAD",
"country": "UA",
"city": "Lviv",
"postCode": 79007
}
}
}'
Send payments to Ukraine. Maximum 1,2m UAH per payment.
Recipient type = 'privatbank'
Required details:
- phoneNumber = Use phone number registered in Privat Bank
- accountNumber = Last 4 digits of UAH PrivatBank card
Create USD Recipient
Example Request (USD):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "USD",
"type": "aba",
"details": {
"legalType": "PRIVATE",
"abartn": "111000025",
"accountNumber": "12345678",
"accountType": "CHECKING",
"address" : {
"country": "GB",
"city": "London",
"postCode": "10025",
"firstLine": "50 Branson Ave"
}
}
}'
Send payments to USA.
Private and business recipients are supported. Max 1 Million USD per payment.
Recipient type = 'aba'
Required details:
- abartn = ACH Routing number
- accountNumber = Recipient bank account number
- accountType = CHECKING or SAVINGS
- address = Recipient address
Create VND Recipient
Example Request (VND):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "VND",
"type": "vietname_earthport",
"details": {
"legalType": "PRIVATE",
"swiftCode": "ABBKVNVX",
"branchCode": "001",
"accountNumber": "1234567890"
}
}'
Send payments to Vietnam.
Private and business recipients are supported.
Recipient type = 'vietname_earthport'
Required details: swiftCode, branchCode, accountNumber
Lists of banks and branches can be obtained from Banks and Branches endpoints.
You can also get list of bank and branch codes by using /v1/quotes/{quoteId}/account-requirements endpoint.
Create ZAR Recipient
Example Request (ZAR):
curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "<recipient name>",
"currency": "ZAR",
"type": "southafrica",
"details": {
"legalType": "PRIVATE",
"swiftCode": "ALBRZAJJ",
"accountNumber": "0000000052312891"
}
}'
Send payments to South African Republic.
Private and business recipients are supported.
Recipient type = 'southafrica'
Required details: swiftCode, accountNumber
You can get list of bank codes by using /v1/quotes/{quoteId}/account-requirements endpoint.
Lists of banks and branches can be obtained from Banks and Branches endpoints.
Create Email Recipient
Example Request (Create email recipient):
curl -X POST https://api.sandbox.transferwise.tech/v1/accounts \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"profile": <your profile id>,
"accountHolderName": "Ann Johnson",
"currency": "EUR",
"type": "email",
"details": {
"email": "ann.johnson@gmail.com"
}
}'
Example Response (Lookup email recipient):
{
"id": 13967196,
"business": null,
"profile": <your profile id>,
"accountHolderName": "Ann Johnson",
"currency": "EUR",
"country": null,
"type": "email",
"details": {
"address": {
"country": null,
"countryCode": null,
"firstLine": null,
"postCode": null,
"city": null,
"state": null
},
"email": "ann.johnson@gmail.com",
"legalType": "PRIVATE",
"accountNumber": null,
"sortCode": null,
"abartn": null,
"accountType": null,
"bankgiroNumber": null,
"ifscCode": null,
"bsbCode": null,
"institutionNumber": null,
"transitNumber": null,
"phoneNumber": null,
"bankCode": null,
"russiaRegion": null,
"routingNumber": null,
"branchCode": null,
"cpf": null,
"cardNumber": null,
"idType": null,
"idNumber": null,
"idCountryIso3": null,
"idValidFrom": null,
"idValidTo": null,
"clabe": null,
"swiftCode": null,
"dateOfBirth": null,
"clearingNumber": null,
"bankName": null,
"branchName": null,
"businessNumber": null,
"province": null,
"city": null,
"rut": null,
"token": null,
"cnpj": null,
"payinReference": null,
"pspReference": null,
"orderId": null,
"idDocumentType": null,
"idDocumentNumber": null,
"targetProfile": null,
"taxId": null,
"iban": null,
"bic": null,
"IBAN": null,
"BIC": null,
"interacAccount": null
},
"user": <your user id>,
"active": true,
"ownedByCustomer": false
}
If you don't know recipient bank account details you can set up email recipient so that Wise will collect bank details directly from the recipient.
Wise will email your recipient with a link to collect their bank account details. Once your recipient provides bank account details securely to Wise we are able to complete your transfer.
https://wise.com/help/articles/2932105/can-i-send-money-to-someone-with-only-their-email-address
Transfers
Create
Example Request:
curl -X POST https://api.sandbox.transferwise.tech/v1/transfers \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"sourceAccount": <refund recipient account id>,
"targetAccount": <recipient account id>,
"quoteUuid": <v2 quote id>,
"customerTransactionId": "<the unique identifier you generated for the transfer attempt>",
"details" : {
"reference" : "to my friend",
"transferPurpose": "verification.transfers.purpose.pay.bills",
"transferPurposeSubTransferPurpose": "verification.sub.transfers.purpose.pay.interpretation.service"
"sourceOfFunds": "verification.source.of.funds.other"
}
}'
Example Response:
{
"id": 468956,
"user": <your user id>,
"targetAccount": <recipient account id>,
"sourceAccount": null,
"quote": null,
"quoteUuid": <v2 quote id>,
"status": "incoming_payment_waiting",
"reference": "to my friend",
"rate": 0.9065,
"created": "2018-08-28 07:43:55",
"business": <your business profile id>,
"transferRequest": null,
"details": {
"reference": "to my friend"
},
"hasActiveIssues": false,
"sourceCurrency": "EUR",
"sourceValue": 661.89,
"targetCurrency": "GBP",
"targetValue": 600,
"customerTransactionId": "bd244a95-dcf8-4c31-aac8-bf5e2f3e54c0"
}
A transfer is a payment order to recipient account based on a quote. Once created, a transfer needs to be funded within the next five working days. Otherwise, it will be automatically canceled.
Request
POST https://api.sandbox.transferwise.tech/v1/transfers
| Field | Description | Format |
|---|---|---|
| sourceAccount (optional) | Refund recipient account id. | Integer |
| targetAccount | Recipient account id. You can create multiple transfers to same recipient account. | Integer |
| quoteUuid | V2 quote id. You can only create one transfer per one quote. You cannot use same quote ID to create multiple transfers. |
Text |
| customerTransactionId | This is required to perform idempotency check to avoid duplicate transfers in case of network failures or timeouts. | UUID |
| details.reference (optional) | Recipient will see this reference text in their bank statement. Maximum allowed characters depends on the currency route. Business Payments Tips article has a full list. | Text |
| details.transferPurpose (conditionally required) | For example when target currency is THB. See more about conditions at Transfers.Requirements | Text |
| details.transferPurposeSubTransferPurpose (conditionally required) | For example when target currency is CNY. See more about conditions at Transfers.Requirements | Text |
| details.sourceOfFunds (conditionally required) | For example when target currency is USD and transfer amount exceeds 80k. See more about conditions at Transfers.Requirements | Text |
There are two options to deal with conditionally required fields:
- Always call `transfer-requirements` endpoint and submit values only if indicated so.
- Always provide values for these fields based on a hard coded list. It is possible these fields change over time so hard coding the options does create some risk of issues.
Response
You need to save the transfer id for tracking its status later via webhooks.
| Field | Description | Format |
|---|---|---|
| id | Transfer id | Integer |
| user | Your user id | Integer |
| targetAccount | Recipient account id | Integer |
| sourceAccount | Refund recipient account id | Integer |
| quote | v1 quote id (where applicable) | Integer |
| quoteUuid | v2 quote id | Text |
| status | Transfer current status | Text |
| reference | Deprecated, use details.reference instead | Text |
| rate | Exchange rate value | Decimal |
| created | Timestamp when transfer was created | Timestamp |
| business | Your business profile id | |
| transferRequest | Not used | Integer |
| details.reference | Payment reference text | Text |
| hasActiveIssues | Are there any pending issues which stop executing the transfer? | Boolean |
| sourceCurrency | Source currency code | Text |
| sourceValue | Transfer amount in source currency | Decimal |
| targetCurrency | Target currency code | Text |
| targetValue | Transfer amount in target currency | Decimal |
| customerTransactionId | Unique identifier randomly generated per transfer request by the calling client | UUID |
Avoiding duplicate transfers
We use customerTransactionId field to avoid duplicate transfer requests. If your initial call to create a transfer fails (error or timeout) then you should retry the call using the same value in the customerTransactionId field that you used in the original call. This way we can treat subsequent retry messages as repeat messages and will not create duplicate transfers to your account should one have succeeded before. You should not retry indefinitely but use a sensible limit, perhaps with a back-off approach.
Fund
Example Request:
curl -X POST https://api.sandbox.transferwise.tech/v3/profiles/{profileId}/transfers/{transferId}/payments \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"type": "BALANCE"
}'
Example Response:
{
"type": "BALANCE",
"status": "COMPLETED",
"errorCode": null
}
This API call is the final step for executing payouts. Upon calling the endpoint Wise will start processing your transfer and fund the transfer immediately if possible.
When using the BALANCE option, Wise will debit funds from your multi-currency account and start processing your transfer. If your multi-currency account does not have the required funds to complete the action then this call will fail with an "insufficient funds" error.
When using the TRUSTED_PRE_FUND_BULK option, Wise will count the transfer amount towards your held collateral. If there are not enough collateral funds to cover the amount of the transfer, the call will still succeed but be placed in a queue and funded when sufficient collateral is restored. For more information on this, please speak to our team.
This endpoint is not required if you fund transfers using the following methods:
- BANK_TRANSFER - where you send the funds directly to Wise's bank account.
- Another option unique to your integration.
If you are unsure if you need this please contact your Wise implementation team to clarify.
Request
POST https://api.sandbox.transferwise.tech/v3/profiles/{profileId}/transfers/{transferId}/payments
Use transfer id that you obtained in previous step.
| Field | Description | Format |
|---|---|---|
| type | "BALANCE". This indicates that your transfer will be funded from your multi-currency account. |
Text |
Response
You need to save transfer id for tracking its status later.
| Field | Description | Format |
|---|---|---|
| type | "BALANCE" | Text |
| status | "COMPLETED" or "REJECTED" | Text |
| errorCode | Failure reason. For example "balance.payment-option-unavailable" | Text |
Cancel
Example Request:
curl -X PUT https://api.sandbox.transferwise.tech/v1/transfers/{transferId}/cancel \
-H "Authorization: Bearer <your api token>"
Example Response:
{
"id": 16521632,
"user": 4342275,
"targetAccount": 8692237,
"sourceAccount": null,
"quote": 657171,
"status": "cancelled",
"reference": "reference text",
"rate": 0.89,
"created": "2017-11-24 10:47:49",
"business": null,
"transferRequest": null,
"details": {
"reference": "Testing"
},
"hasActiveIssues": false,
"sourceCurrency": "EUR",
"sourceValue": 0,
"targetCurrency": "GBP",
"targetValue": 150,
"customerTransactionId": "54a6bc09-cef9-49a8-9041-f1f0c654cd88"
}
Only transfers which are not funded can be cancelled. Cancellation is final - it can not be undone.
Request
PUT https://api.sandbox.transferwise.tech/v1/transfers/{transferId}/cancel
Use transfer id that you obtained when creating a transfer.
Response
| Field | Description | Format |
|---|---|---|
| id | Transfer id | Integer |
| user | Your user id | Integer |
| targetAccount | Recipient account id | Integer |
| sourceAccount | Refund recipient account id | Integer |
| quote | Quote id | Integer |
| status | Transfer current status | Text |
| reference | Deprecated, use details.reference instead | Text |
| rate | Exchange rate value | Decimal |
| created | Timestamp when transfer was created | Timestamp |
| business | Your business profile id | |
| transferRequest | Not used | Integer |
| details.reference | Payment reference text | Text |
| hasActiveIssues | Are there any pending issues which stop executing the transfer? | Boolean |
| sourceCurrency | Source currency code | Text |
| sourceValue | Transfer amount in source currency | Decimal |
| targetCurrency | Target currency code | Text |
| targetValue | Transfer amount in target currency | Decimal |
| customerTransactionId | Unique identifier randomly generated per transfer request by the calling client | UUID |
Get by Id
Example Request:
curl -X GET https://api.sandbox.transferwise.tech/v1/transfers/{transferId} \
-H "Authorization: Bearer <your api token>"
Example Response:
{
"id": 15574445,
"user": 294205,
"targetAccount": 7993919,
"sourceAccount": null,
"quote": 113379,
"status": "incoming_payment_waiting",
"reference": "good times",
"rate": 1.2151,
"created": "2017-03-14 15:25:51",
"business": null,
"transferRequest": null,
"details": {
"reference": "good times"
},
"hasActiveIssues": false,
"sourceValue": 1000,
"sourceCurrency": "EUR",
"targetValue": 895.32,
"targetCurrency": "GPB",
"customerTransactionId": "6D9188CF-FA59-44C3-87A2-4506CE9C1EA3"
}
Get transfer info by id. Since we don't have push notifications yet, you can poll this endpoint to track your transfer status.
Request
GET https://api.sandbox.transferwise.tech/v1/transfers/{transferId}
Response
| Field | Description | Format |
|---|---|---|
| id | Transfer id | Integer |
| user | Your user id | Integer |
| targetAccount | Recipient account id | Integer |
| sourceAccount | Refund recipient account id | Integer |
| quote | Quote id | Integer |
| status | Transfer current status | Text |
| reference | Deprecated, use details.reference instead | Text |
| rate | Exchange rate value | Decimal |
| created | Timestamp when transfer was created | Timestamp |
| business | Your business profile id | |
| transferRequest | Not used | Integer |
| details.reference | Payment reference text | Text |
| hasActiveIssues | Are there any pending issues which stop executing the transfer? | Boolean |
| sourceCurrency | Source currency code | Text |
| sourceValue | Transfer amount in source currency | Decimal |
| targetCurrency | Target currency code | Text |
| targetValue | Transfer amount in target currency | Decimal |
| customerTransactionId | Unique identifier randomly generated per transfer request by the calling client | UUID |
Get Delivery Estimate
Example Request:
curl -X GET https://api.sandbox.transferwise.tech/v1/delivery-estimates/{transferId} \
-H "Authorization: Bearer <your api token>"
Example Response:
{
"estimatedDeliveryDate" : "2018-01-10T12:15:00.000+0000"
}
Get the live delivery estimate for a transfer by the transfer ID.
The delivery estimate is the time at which we currently expect the transfer to arrive in the beneficiary's bank account.
This is not a guaranteed time but we are working hard to make these estimates as accurate as possible.
Request
GET https://api.sandbox.transferwise.tech/v1/delivery-estimates/{transferId}
Response
| Field | Description | Format |
|---|---|---|
| estimatedDeliveryDate | Estimated time when funds will arrive to recipient's bank account | Timestamp |
Get Receipt PDF
Example Request:
curl -X GET https://api.sandbox.transferwise.tech/v1/transfers/{transferId}/receipt.pdf \
-H "Authorization: Bearer <your api token>"
Example Response:
Receipt presented as application/pdf content-type
Download transfer confirmation receipt in PDF format for transfers that are in status outgoing_payment_sent.
Request
GET https://api.sandbox.transferwise.tech/v1/transfers/{transferId}/receipt.pdf
Response
Transfer confirmation receipt in PDF format.
List
Example Request:
curl -X GET https://api.sandbox.transferwise.tech/v1/transfers?offset=0&limit=100&profile=<your profile id>&status=funds_refunded&createdDateStart=2018-12-15&createdDateEnd=2018-12-30 \
-H "Authorization: Bearer <your api token>"
Example Response:
[
{
"id": 15574445,
"user": 294205,
"targetAccount": 7993919,
"sourceAccount": null,
"quote": 113379,
"status": "funds_refunded",
"reference": "good times",
"rate": 1.1179,
"created": "2018-12-16 15:25:51",
"business": null,
"transferRequest": null,
"details": {
"reference": "good times"
},
"hasActiveIssues": false,
"sourceValue": 1000,
"sourceCurrency": "EUR",
"targetValue": 895.32,
"targetCurrency": "GPB",
"customerTransactionId": "6D9188CF-FA59-44C3-87A2-4506CE9C1EA3"
},
{
"id": 14759252,
"user": 294205,
"targetAccount": 5570192,
"sourceAccount": null,
"quote": 113371,
"status": "funds_refunded",
"reference": "",
"rate": 1.1179,
"created": "2018-12-26 15:25:51",
"business": null,
"transferRequest": null,
"details": {
"reference": ""
},
"hasActiveIssues": false,
"sourceValue": 1000,
"sourceCurrency": "EUR",
"targetValue": 895.32,
"targetCurrency": "GPB",
"customerTransactionId": "785C67AD-7E29-4DBC-9D4A-4C45D4D5333A"
}
]
Get the list of transfers for given user's profile (defaults to user's personal profile).
You can add query parameters to specify user's profile (personal or business), time period and/or payment status.
For example you can query:
- all failed payments created since last week
- all completed payments created since yesterday
Request
GET https://api.sandbox.transferwise.tech/v1/transfers/?offset=0&limit=100&profile=<your profile id>&status=funds_refunded&sourceCurrency=EUR&createdDateStart=2018-12-15T01:30:00.000Z&createdDateEnd=2018-12-30T01:30:00.000Z
| Field | Description | Format |
|---|---|---|
| profile | User profile id. If parameter is omitted, defaults to user's personal profile | Integer |
| status | Status code or codes list (as comma separated value list) to filter returned transfers with. See Track transfer status for complete list of statuses. | Text |
| sourceCurrency | Source currency code | Text |
| targetCurrency | Target currency code | Text |
| createdDateStart | Starting date to filter transfers, inclusive of the provided date. | yyyy-MM-dd'T'HH:mm:ss.SSS'Z' |
| createdDateEnd | Ending date to filter transfers, inclusive of the provided date. | yyyy-MM-dd'T'HH:mm:ss.SSS'Z' |
| limit | Maximum number of records to be returned in response | Integer |
| offset | Starting record number | Integer |
Response
| Field | Description | Format |
|---|---|---|
| id | Transfer id | Integer |
| user | Your user id | Integer |
| targetAccount | Recipient account id | Integer |
| sourceAccount | Refund recipient account id | Integer |
| quote | Quote id | Integer |
| status | Transfer current status | Text |
| reference | Deprecated, use details.reference instead | Text |
| rate | Exchange rate value | Decimal |
| created | Timestamp when transfer was created | Timestamp |
| business | Your business profile id | |
| transferRequest | Not used | Integer |
| details.reference | Payment reference text | Text |
| hasActiveIssues | Are there any pending issues which stop executing the transfer? | Boolean |
| sourceCurrency | Source currency code | Text |
| sourceValue | Transfer amount in source currency | Decimal |
| targetCurrency | Target currency code | Text |
| targetValue | Transfer amount in target currency | Decimal |
| customerTransactionId | Unique identifier assigned by customer. Used for idempotency check purposes. | UUID |
Requirements
Example Request:
curl -X POST https://api.sandbox.transferwise.tech/v1/transfer-requirements \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"targetAccount": <recipient account id>,
"quoteUuid": <quote uuid>,
"details": {
"reference": "good times",
"sourceOfFunds": "verification.source.of.funds.other",
"sourceOfFundsOther": "Trust funds"
},
"customerTransactionId": "6D9188CF-FA59-44C3-87A2-4506CE9C1EA3"
}'
Example Response:
[
{
"type": "transfer",
"fields": [
{
"name": "Transfer reference",
"group": [
{
"key": "reference",
"name": "Transfer reference",
"type": "text",
"refreshRequirementsOnChange": false,
"required": false,
"displayFormat": null,
"example": null,
"minLength": null,
"maxLength": 10,
"validationRegexp": null,
"validationAsync": null,
"valuesAllowed": null
}
]
},
{
"name": "Transfer purpose",
"group": [
{
"key": "transferPurpose",
"name": "Transfer purpose",
"type": "select",
"refreshRequirementsOnChange": true,
"required": true,
"displayFormat": null,
"example": null,
"minLength": null,
"maxLength": null,
"validationRegexp": null,
"validationAsync": null,
"valuesAllowed": [
{
"key": "verification.transfers.purpose.purchase.property",
"name": "Buying property abroad"
},
{
"key": "verification.transfers.purpose.pay.bills",
"name": "Rent or other property expenses"
},
{
"key": "verification.transfers.purpose.mortgage",
"name": "Mortgage payment"
},
{
"key": "verification.transfers.purpose.pay.tuition",
"name": "Tuition fees or studying expenses"
},
{
"key": "verification.transfers.purpose.send.to.family",
"name": "Sending money home to family"
},
{
"key": "verification.transfers.purpose.living.expenses",
"name": "General monthly living expenses"
},
{
"key": "verification.transfers.purpose.other",
"name": "Other"
}
]
},
{
"key": "transferPurposeSubTransferPurpose",
"name": "Please select a specific reason for your transfer",
"type": "select",
"refreshRequirementsOnChange": true,
"required": true,
"displayFormat": null,
"example": null,
"minLength": null,
"maxLength": null,
"validationRegexp": null,
"validationAsync": null,
"valuesAllowed": [
{
"key": "INTERPRETATION_SERVICE",
"name": "Interpretation service"
},
{
"key": "TRANSLATION_SERVICE",
"name": "Translation service"
},
{
"key": "HUMAN_RESOURCE_SERVICE",
"name": "Human resource service"
},
{
"key": "ESTATE_AGENCY_SERVICE",
"name": "Estate agency service"
},
{
"key": "SOFTWARE_DEVELOPMENT_SERVICE",
"name": "Software development service"
},
{
"key": "WEB_DESIGN_OR_DEVELOPMENT_SERVICE",
"name": "Web design or development service"
},
{
"key": "DRAFTING_LEGAL_SERVICE",
"name": "Drafting legal service"
},
{
"key": "LEGAL_RELATED_CERTIFICATION_SERVICE",
"name": "Legal related certification service"
},
{
"key": "ACCOUNTING_SERVICE",
"name": "Accounting service"
},
{
"key": "TAX_SERVICE",
"name": "Tax service"
},
{
"key": "ARCHITECTURAL_DECORATION_DESIGN_SERVICE",
"name": "Architectural decoration design service"
},
{
"key": "ADVERTISING_SERVICE",
"name": "Advertising service"
},
{
"key": "MARKET_RESEARCH_SERVICE",
"name": "Market research service"
},
{
"key": "EXHIBITION_BOOTH_SERVICE",
"name": "Exhibition booth service"
}
]
}
]
},
{
"name": "Source of funds",
"group": [
{
"key": "sourceOfFunds",
"name": "Source of funds",
"type": "select",
"refreshRequirementsOnChange": true,
"required": true,
"displayFormat": null,
"example": null,
"minLength": null,
"maxLength": null,
"validationRegexp": null,
"validationAsync": null,
"valuesAllowed": [
{
"key": "verification.source.of.funds.salary",
"name": "Salary"
},
{
"key": "verification.source.of.funds.investment",
"name": "Investments (stocks, properties, etc.)"
},
{
"key": "verification.source.of.funds.inheritance",
"name": "Inheritance"
},
{
"key": "verification.source.of.funds.loan",
"name": "Loan"
},
{
"key": "verification.source.of.funds.other",
"name": "Other"
}
]
}
]
}
]
}
]
Almost every region has its own specific nuances when it comes to the nitty gritty details of domestic payment systems and money transfer regulations. The maximum allowed length of reference text is a good example. The US payment system, ACH, supports 10 characters only, but transfers within Mexico allow up to 100 characters, and so on.
The same is true for requirements arising from Anti Money Laundering regulations adopted in different countries. Depending on the chosen currencies and the amount to be transferred, either in one go or cumulatively over time, Wise may require more details about the customer's source of funds or transfer purpose, for example.
The endpoint /transfer-requirements exposes all these specific requirements based on the sender, the specific quote and selected target recipient account.
To make sure that processing of your customer's transfers does not get delayed because of missing details, we highly recommend to verify the transfer requirements before submitting any transfer and collecting the data we request from the user using the returned dynamic form.
Request
POST https://api.sandbox.transferwise.tech/v1/transfer-requirements
1.Prepare the request body to create transfer object first.
Now post this request body to the transfer-requirements endpoint to figure out if there are any other required fields.
2.Analyze the returned list of fields. Our example includes reference, sourceOfFunds and transferPurpose fields. Field 'reference' is optional. Fields 'sourceOfFunds' and 'transferPurpose' are required and both have refreshRequirementsOnChange=true which indicates that there could be additional fields required depending on the selected value.
In our example you will have to POST request to/v1/transfer-requirements` second time as well with values set for 'transferPurpose' and 'sourceOfFunds'. So in case you set sourceOfFunds = 'verification.source.of.funds.other' then another text field called "sourceOfFundsOther" is also required where you need to specify the details in free format.
3.Once you get to the point where you have provided values for all fields which have refreshRequirementsOnChange=true then you have complete set of fields to compose a valid request to create a transfer object.
For example this is a valid request to create a transfer.
POST /v1/transfers:
{
"targetAccount":
"quote": ,
"details": {
"reference": "good times",
"sourceOfFunds": "verification.source.of.funds.other",
"sourceOfFundsOther": "Trust funds"
},
"customerTransactionId": "6D9188CF-FA59-44C3-87A2-4506CE9C1EA3"
}
Response
| Field | Description | Format |
|---|---|---|
| type | "transfer" | Text |
| fields[n].name | Field description | Text |
| fields[n].group[n].key | Key is name of the field you should include in the JSON | Text |
| fields[n].group[n].name | Field description | Text |
| fields[n].group[n].type | Display type of field (e.g. text, select, etc) | Text |
| fields[n].group[n].refreshRequirementsOnChange | Tells you whether you should call POST transfer-requirements once the field value is set to discover required lower level fields. | Boolean |
| fields[n].group[n].required | Indicates if the field is mandatory or not | Boolean |
| fields[n].group[n].displayFormat | Display format pattern. | Text |
| fields[n].group[n].example | Example value. | Text |
| fields[n].group[n].minLength | Min valid length of field value. | Integer |
| fields[n].group[n].maxLength | Max valid length of field value. | Integer |
| fields[n].group[n].validationRegexp | Regexp validation pattern. | Text |
| fields[n].group[n].validationAsync | Validator URL and parameter name you should use when submitting the value for validation | Text |
| fields[n].group[n].valuesAllowed[n].key | List of allowed values. Value key | Text |
| fields[n].group[n].valuesAllowed[n].name | List of allowed values. Value name. | Text |
Profile Webhooks
Profile webhook subscription is a mechanism that will allow you to receive notifications to your servers whenever various events happen in relation to different resources created under a specific profile.
Before proceeding, make sure the endpoint where you intend to receive webhooks satisfies the following requirements:
- Has a valid domain name (IPs are disallowed)
- Listens to HTTPS requests on port
443 - Has a valid HTTPS certificate signed by a trusted Certificate Authority - CA (self-signed or expired certificates are not accepted)
- Does not include any query arguments in the URL
https://webhooks.example.com/balance-change is a valid URL; http://webhooks.example.com:8080/hook.php?type=balance is not.
You can have multiple subscriptions per event type though be mindful you will receive duplicate callbacks, one for each subscription. Find out more about webhook events here.
If you will be dealing with multiple profiles in your integration, check out application webhooks. You will have to subscribe only once and you will receive updates concerning all resources that were created in your application.
There are two ways you can manage profile webhooks:
- via API (read more below)
- via user interface (go to your settings page)
Create
Create a profile subscription.
URL validation
Our system will validate the requested delivery URL before creating a subscription.
A test notification will be sent to the URL and if a 2xx-series HTTP response is not received then the creation
request will be rejected with error code INVALID_CALLBACK_URL.
Your notification endpoint must be ready to respond to the test notification. Test notifications can be distinguished by the presence of an HTTP request header. See the section Event HTTP requests for more information on request headers.
Example Request:
curl -X POST "https://api.transferwise.com/v3/profiles/{profileId}/subscriptions" \
-H "Authorization: Bearer <your user token>" \
-H "Content-Type: application/json" \
-d '{
"name": "Webhook Subscription #1",
"trigger_on": "transfers#state-change",
"delivery": {
"version": "2.0.0",
"url": "https://your.webhook.url/12345"
}
}'
Example Response:
{
"id": "72195556-e5cb-495e-a010-b37a4f2a3043",
"name": "Webhook Subscription #1",
"delivery": {
"version": "2.0.0",
"url": "https://your.webhook.url/12345"
},
"trigger_on": "transfers#state-change",
"scope": {
"domain": "profile",
"id": "<profile ID>"
},
"created_by": {
"type": "user",
"id": "<your user ID>"
},
"created_at": "2008-09-15T15:53:00Z"
}
Request
POST https://api.transferwise.com/v3/profiles/{profileId}/subscriptions
profileId - ID of the profile you are subscribing to.
All fields listed below are required for creating a webhook subscription.
| Field | Description | Format |
|---|---|---|
| name | A custom name for your webhook to ease with identification | Text |
| trigger_on | Choose from a list of available events | Text |
| delivery.version | The event representation semantic | Text |
| delivery.url | Required. The URL where your server will be listening for events. | Text |
Response
| Field | Description | Format |
|---|---|---|
| id | UUID that uniquely identifies the subscription | Text |
| name | A custom name for your webhook to ease with identification | Text |
| trigger_on | transfers#state-change, transfers#active-cases or balances#credit |
Text |
| delivery.version | The event representation semantic | Text |
| delivery.url | Required. The URL where your server will be listening for events. | Text |
| scope.domain | Scope of this subscription, always "profile" in this case | Text |
| scope.id | Profile ID used to create this subscription | Text |
| created_by.type | Creator type. Always user in this case | Text |
| created_by.id | User id of the creator | Text |
| created_at | Timestamp of when the subscription was created | Text |
Delete
Deletes a subscription by its identifier.
Example Request:
curl -X DELETE "https://api.transferwise.com/v3/profiles/{profileId}/subscriptions/{id}" \
-H "Authorization: Bearer <your user token>"
Example Response:
Request
DELETE https://api.transferwise.com/v3/profiles/{profileId}/subscriptions/{id}
Get by ID
Retrieves a subscription by its identifier.
Example Request:
curl -X GET "https://api.transferwise.com/v3/profiles/{profileId}/subscriptions/{id}" \
-H "Authorization: Bearer <your user token>"
Example Response:
{
"id": "f215f353-35fd-405b-b27f-4fd603c905ed",
"name": "Webhook Subscription #1",
"delivery": {
"version": "2.0.0",
"url": "https://your.webhook.url/12345"
},
"trigger_on": "balances#credit",
"scope": {
"domain": "profile",
"id": "<profile ID>"
},
"created_by": {
"type": "user",
"id": "<your user ID>"
},
"created_at": "2008-09-15T15:53:00Z"
}
Request
GET https://api.transferwise.com/v3/profiles/{profileId}/subscriptions/{id}
List
List all your subscriptions
Example Request:
curl -X GET "https://api.transferwise.com/v3/profiles/{profileId}/subscriptions" \
-H "Authorization: Bearer <your user token>"
Example Response:
[
{
"id": "e889e085-3677-4110-be26-3e9160ac9f25",
"name": "#1 subscription",
"delivery": {
"version": "2.0.0",
"url": "https://your.webhook.url/12345"
},
"trigger_on": "transfers#state-change",
"created_by": {
"type": "user",
"id": "<your user ID>"
},
"scope": {
"domain": "profile",
"id": "<profile ID>"
}
},
{
"id": "eabeb3f5-c134-4a1c-99e2-86a1163daf1b",
"name": "#2 subscription",
"delivery": {
"version": "2.0.0",
"url": "https://your.webhook.url/12345"
},
"trigger_on": "transfers#state-change",
"created_by": {
"type": "user",
"id": "<your user ID>"
},
"scope": {
"domain": "profile",
"id": "<profile ID>"
}
}
]
Request
GET https://api.transferwise.com/v3/profiles/{profileId}/subscriptions
Webhook events
Webhook events are messages that describe certain business events that occur within Wise's system. For example, an event may describe a change in the status of a transfer you have made.
Events that are related to your Wise resources can be sent to your server as HTTP POST requests.
You can start receiving events by creating webhook subscriptions using the Wise Platform API or website interface.
Subscriptions specify what type of event should be sent, and what server location the event should be sent to.
Events will not contain any personally identifiable information.
Webhook handlers
To receive events, you must set up a publicly accessible HTTPS endpoint and create a subscription that uses this endpoint. Our system will send HTTP POST requests to this endpoint with events encoded using JSON.
Your system must respond with a 2xx-series HTTP status code within 5 seconds of receiving a request to
acknowledge successful delivery of a webhook notification.
If this "success" response is not received by us within this time period, we will consider the delivery attempt as
having failed and will later try to resend the message.
We will attempt to redeliver messages at increasing intervals over a two week period.
We will try at most 25 times to do this.
A recommended strategy for handling notifications is to do some basic validation and then store the notification for processing by a separate server process. This will avoid our delivery system from considering delivery attempts to have failed if your handler does not respond in time due to a long handling process. Basic validation could include signature verification (see below).
Event HTTP requests
Event HTTP request bodies have a type-specific structure. Events using version 2 of our type schema will contain a common base structure with additional event-specific details. Each event type is described in detail later in this section.
Event HTTP requests also contain the following custom headers:
Signature header X-Signature-SHA256
Wise's public webhook signing key for the production environment:
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvO8vXV+JksBzZAY6GhSO
XdoTCfhXaaiZ+qAbtaDBiu2AGkGVpmEygFmWP4Li9m5+Ni85BhVvZOodM9epgW3F
bA5Q1SexvAF1PPjX4JpMstak/QhAgl1qMSqEevL8cmUeTgcMuVWCJmlge9h7B1CS
D4rtlimGZozG39rUBDg6Qt2K+P4wBfLblL0k4C4YUdLnpGYEDIth+i8XsRpFlogx
CAFyH9+knYsDbR43UJ9shtc42Ybd40Afihj8KnYKXzchyQ42aC8aZ/h5hyZ28yVy
Oj3Vos0VdBIs/gAyJ/4yyQFCXYte64I7ssrlbGRaco4nKF3HmaNhxwyKyJafz19e
HwIDAQAB
-----END PUBLIC KEY-----
Wise's public webhook signing key for the sandbox environment:
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwpb91cEYuyJNQepZAVfP
ZIlPZfNUefH+n6w9SW3fykqKu938cR7WadQv87oF2VuT+fDt7kqeRziTmPSUhqPU
ys/V2Q1rlfJuXbE+Gga37t7zwd0egQ+KyOEHQOpcTwKmtZ81ieGHynAQzsn1We3j
wt760MsCPJ7GMT141ByQM+yW1Bx+4SG3IGjXWyqOWrcXsxAvIXkpUD/jK/L958Cg
nZEgz0BSEh0QxYLITnW1lLokSx/dTianWPFEhMC9BgijempgNXHNfcVirg1lPSyg
z7KqoKUN0oHqWLr2U1A+7kqrl6O2nx3CKs1bj1hToT1+p4kcMoHXA7kA+VBLUpEs
VwIDAQAB
-----END PUBLIC KEY-----
Each outgoing webhook request is signed. You should verify that any request you handle was sent by Wise and has not been forged or tampered with. You should not process any requests with signatures that fail verification.
Signatures are generated using an RSA key and SHA256 digest of the message body.
They are transmitted using the X-Signature-SHA256 request header and are Base64 encoded.
In this repository, you can see some reference implementations in Java, Node and Ruby.
Delivery ID header X-Delivery-Id
Each outgoing notification is assigned a unique delivery UUID.
Test notification header X-Test-Notification
This header is present with the value true if the notification is a test message.
Test messages can be sent to verify callback URLs when subscriptions are being set up.
Event payload
All event notification payloads have the same high-level structure.
Top-level properties are common to all events.
The data property is an object that can contain various properties.
The exact properties that the data object contains depends on the event type and schema version of the event.
Basic event payload:
{
"data": {},
"subscription_id": "01234567-89ab-cdef-0123-456789abcdef",
"event_type": "event#type",
"schema_version": "2.0.0",
"sent_at": "2020-01-01T12:34:56Z"
}
Common properties
| Field | Description | Format |
|---|---|---|
| data | Event type- and schema version-specific details | Object |
| subscription_id | ID of the webhook subscription that triggered the event notification | Text |
| event_type | Event type (what event happened in our system) | String |
| schema_version | Schema version (what notification structure is being used to model the event) | String |
| sent_at | When the event notification was sent from our system | Datetime |
Event types
The follow event types are available. Please note that some event types are restricted to certain types of webhook subscription.
| Event type | Profile subscriptions | Application subscriptions |
|---|---|---|
| transfers#state-change | supported | supported |
| transfers#active-cases | supported | not supported |
| balances#credit | supported | not supported |
| profiles#verification-state-change | not supported | supported |
| transfers#payout-failure | not supported | supported |
| swift-in#credit | supported | not supported |
| cards#transaction-state-change | not supported | supported |
Transfer status change event
Event type: transfers#state-change
This event will be triggered every time a transfer's status is updated. Each event contains a timestamp.
As we do not guarantee the order of events, please use data.occurred_at to reconcile the order.
If you would like to subscribe to transfer state change events, please use transfers#state-change
when creating your subscription.
Example v2.0.0
transfers#state-changeevent:
{
"data": {
"resource": {
"type": "transfer",
"id": 111,
"profile_id": 222,
"account_id": 333
},
"current_state": "processing",
"previous_state": "incoming_payment_waiting",
"occurred_at": "2020-01-01T12:34:56Z"
},
"subscription_id": "01234567-89ab-cdef-0123-456789abcdef",
"event_type": "transfers#state-change",
"schema_version": "2.0.0",
"sent_at": "2020-01-01T12:34:56Z"
}
Schema version 2.0.0 (latest)
| Field | Description | Format |
|---|---|---|
| data.resource.type | Transfer resource type (always transfer) |
String |
| data.resource.id | ID of the transfer | Integer |
| data.resource.profile_id | ID of the profile that owns the transfer | Integer |
| data.resource.account_id | ID of transfer's recipient account | Integer |
| data.current_state | Current transfer state (see transfer statuses) | String |
| data.previous_state | Previous transfer state (see transfer statuses) | String |
| data.occurred_at | When the state change occurred | Datetime |
Transfer active cases event
Event type: transfers#active-cases
This event will be triggered every time a transfer's list of active cases is updated. Active cases indicate potential problems with transfer processing.
If you would like to subscribe to transfer active cases events, please use transfers#active-cases when creating
your subscription.
Example v2.0.0
transfers#active-casesevent:
{
"data": {
"resource": {
"type": "transfer",
"id": 111,
"profile_id": 222,
"account_id": 333
},
"active_cases": ["deposit_amount_less_invoice"]
},
"subscription_id": "01234567-89ab-cdef-0123-456789abcdef",
"event_type": "transfers#active-cases",
"schema_version": "2.0.0",
"sent_at": "2020-01-01T12:34:56Z"
}
Schema version 2.0.0 (latest)
| Field | Description | Format |
|---|---|---|
| data.resource.type | Transfer resource type (always transfer) |
String |
| data.resource.id | ID of the transfer | Integer |
| data.resource.profile_id | ID of the profile that owns the transfer | Integer |
| data.resource.account_id | ID of transfer's recipient account | Integer |
| data.active_cases | Ongoing issues related to the transfer | List of strings |
Balance credit event
Event type: balances#credit
This event will be triggered every time a multi-currency account is credited.
If you would like to subscribe to balance credit events, please use balances#credit when creating your subscription.
Please note: This event is not currently delivered to application subscriptions.
Example v2.0.0
balances#creditevent:
{
"data": {
"resource": {
"type": "balance-account",
"id": 111,
"profile_id": 222
},
"transaction_type": "credit",
"amount": 1.23,
"currency": "EUR",
"post_transaction_balance_amount": 2.34,
"occurred_at": "2020-01-01T12:34:56Z"
},
"subscription_id": "01234567-89ab-cdef-0123-456789abcdef",
"event_type": "balances#credit",
"schema_version": "2.0.0",
"sent_at": "2020-01-01T12:34:56Z"
}
Schema version 2.0.0 (latest)
| Field | Description | Format |
|---|---|---|
| data.resource.type | Resource type (always balance-account) |
String |
| data.resource.id | ID of the account | Integer |
| data.resource.profile_id | ID of the profile that owns the account | Integer |
| data.transaction_type | Always credit |
String |
| data.amount | Deposited amount | Decimal |
| data.currency | Currency code | String |
| data.post_transaction_balance_amount | Balance after the credit was applied | Decimal |
| data.occurred_at | When the credit occurred | Datetime |
Verification state change event
Event type: profiles#verification-state-change
This event will be triggered when the verification state of a connected profile changes.
A profile's verification state can be verified or not_verified.
If the state is verified, then the user is ready to make payments using Wise.
If the state is not_verified, then we advise not to initiate any transfers with the user's access token as the
payments will not be processed until the verification is completed.
There is a more in-depth discussion of verification state in our Connected Apps Integration Guide.
Please note: This event is currently delivered only to application subscriptions.
If you would like to subscribe to verification state change events, please use profiles#verification-state-change
when creating your subscription.
Example v2.0.0
profiles#verification-state-changeevent:
{
"data": {
"resource": {
"type": "profile",
"id": 111
},
"current_state": "verified",
"occurred_at": "2020-01-01T12:34:56Z"
},
"subscription_id": "01234567-89ab-cdef-0123-456789abcdef",
"event_type": "profiles#verification-state-change",
"schema_version": "2.0.0",
"sent_at": "2020-01-01T12:34:56Z"
}
Schema version 2.0.0 (latest)
| Field | Description | Format |
|---|---|---|
| data.resource.type | Profile resource type (always profile) |
String |
| data.resource.id | ID of the profile | Integer |
| data.current_state | Current verification state of the profile (see discussion above) | String |
| data.occurred_at | When the verification state change occurred | Datetime |
Batch Payment Initiations state change event
Event type: batch-payment-initiations#state-change
This event will be triggered when the payment initiation state of a batch group payment changes.
The expected state of a batch payment initiation can be one of: NEW, PROCESSING, COMPLETED, FAILED, CHARGED_BACK.
If you would like to subscribe to batch payment initiation state change events, please use batch-payment-initiations#state-change
when creating your subscription.
Example v2.0.0
batch-payment-initiations#state-changeevent:
{
"data": {
"resource": {
"id": 12345,
"batchGroupId": "068e186d-9632-4937-b753-af3e53f4d0b0",
"profileId": 2
},
"previousStatus": "NEW",
"newStatus": "PROCESSING",
"occurredAt": "2021-04-13T19:51:41.423404Z" ,
"returnCode": "200"
},
"subscription_id": "01234567-89ab-cdef-0123-456789abcdef",
"event_type": "batch-payment-initiations#state-change",
"schema_version": "2.0.0",
"sent_at": "2020-01-01T12:34:56Z"
}
Schema version 2.0.0 (latest)
| Field | Description | Format |
|---|---|---|
| data.resource.id | Payment initiation ID | Number |
| data.resource.batchGroupId | Batch group ID | Text |
| data.resource.profileId | The ID of the profile this payment belongs to | Number |
| data.previousStatus | Previous payment initiation state | Text |
| data.currentStatus | Current payment initiation state | Text |
| data.occurredAt | When the payment initiation state change occurred | Timestamp |
| data.returnCode | Return code of the underlying payment system | Text |
Payout failure events
Event type: transfers#payout-failure
This event will be triggered every time a payout fails. The event can be used to get further information about a failed payment.
transfers#state-change event provides high level information about the state of transfers. But it doesn't provide details about payout failures.
While the transfers#state-change event is in outgoing_payment_sent state, the payout could fail for certain reasons listed below.
Using this event, you can understand the reason behind the failure and even ask your customers to fix the problem by themselves. If the failure reason code is WRONG_ACCOUNT_NUMBER for example.
Please note that not every payout failure will trigger a transfers#state-change. For example a payout might fail with MANDATE_NOT_FILLED_IN code but the corresponding transfer might stay in the same state.
We recommend to process both event types(transfers#payout-failure and transfers#state-change) separate from each other.
If you would like to subscribe to payout failure events, please use transfers#payout-failure
when creating your subscription.
Example v2.0.0
transfers#payout-failureevent:
{
"data": {
"transfer_id": 111,
"failure_reason_code": "WRONG_ID_NUMBER",
"failure_description": "Invalid recipient's ID document number",
"occurred_at": "2020-01-01T12:34:56Z"
},
"subscription_id": "01234567-89ab-cdef-0123-456789abcdef",
"event_type": "transfers#payout-failure",
"schema_version": "2.0.0",
"occured_at": "2020-01-01T12:34:56Z"
}
Schema version 2.0.0 (latest)
| Field | Description | Format |
|---|---|---|
| data.transfer_id | ID of the transfer | Integer |
| data.failure_reason_code | Code of the failure error | String |
| data.failure_description | Description of the failure code | String |
| data.occurred_at | When the state change occurred | Datetime |
Table of available failure reason codes and descriptions
| Code | Description |
|---|---|
| ACCOUNT_CLOSED | The recipient details are correct, but beneficiary account is closed |
| ACCOUNT_FROZEN | The recipient details are correct, but beneficiary account is frozen |
| ACCOUNT_BLOCKED | The recipient details are correct, but beneficiary account is blocked |
| ACCOUNT_LIMIT_REACHED | The recipient details are correct, but beneficiary account has a limit that can be unblocked by the recipient |
| WRONG_ACCOUNT_NUMBER | Invalid account number |
| WRONG_CARD_NUMBER | Invalid card number |
| WRONG_ACCOUNT_DETAILS | Invalid account number AND/OR invalid bank code |
| WRONG_ACCOUNT_TYPE | Incorrect account type |
| WRONG_BANK_CODE | Invalid sort/BIC/routing/etc number |
| WRONG_BRANCH_CODE | Invalid branch code |
| WRONG_NAME | Account number matches, but the name is not 100% correct |
| WRONG_PHONE_NUMBER | Recipient phone number is incorrect |
| WRONG_ID_NUMBER | Invalid recipient's ID document number |
| WRONG_RUT_NUMBER | Invalid recipient's RUT (Rol Único Tributario) number |
| TAX_ID_NOT_MATCHING | Tax ID doesn't match recipient's name |
| TAX_ID_SUSPENDED | Tax ID is suspended |
| WRONG_REFERENCE | Invalid payment reference |
| WRONG_PAYMENT_PURPOSE | Invalid or not accepted payment purpose |
| ACCOUNT_DOES_NOT_EXIST | Format is correct but this account does not exist in recipient bank |
| WRONG_CURRENCY | Recipient account is in different currency |
| WRONG_CARD_TYPE | Recipient account doesn't support payments to this card type |
| CANNOT_ACCEPT_FROM_3RD_PARTY | Recipient bank can't accept the payments from 3rd party |
| CREDITING_ACCOUNT_FORBIDDEN | Terms and Conditions of Account do not permit crediting of these funds |
| DUPLICATE_ENTRY | Recipient bank informs that there has been another payment in the same amount |
| FUNDS_NOT_EXPECTED_RETURNED | Beneficiary not expecting funds/instructed return |
| MANDATE_NOT_FILLED_IN | Recipient didn't fill out the mandate form on time or the email address is incorrect |
| BUSINESS_PAYMENTS_FORBIDDEN | Payment to business accounts are not allowed |
| DUPLICATE_ENTRY | Recipient bank informs that there has been another payment in the same amount |
| REASON_NOT_SPECIFIED | Reason not specified |
Wise could add new failure codes to this list and your system should be able to handle the events even if the failure reason code is not recognised.
SWIFT Receive Events
Event type: swift-in#credit
This event will be triggered every time a SWIFT message is received and deposited into a balance account.
Please note: It is recommended that you do not subscribe to balances#credit or transfers#state-change on the same profile to avoid duplication of webhook details.
Example
swift-in#creditevent:
{
"data": {
"action": {
"type": "credit",
"id": 12345,
"profile_id": 222,
"account_id": 333
},
"resource": {
"id": "55555",
"type": "103",
"message": "
{1:F21TRWIGB22AXXX123456789}{4:{177:0123456789}{451:0}}{1:F01TRWIGB22AXXX12345678}{2:O1030727211112LHVBEE22AXXX15007123456789912345WN}{3:{108:ASW86540/12112FA}{119:STP}{111:001}{121:f875814b-7d44-4d1b-a499-123456789abcde}}{4:
:20:ASW86540/123456
:23B:CRED
:26T:K90
:32A:211112EUR3,54
:33B:EUR3,54
:50F:/EE947700771111111111
1/SMITH#JOHN
2/EVERGREEN STREET, 10
3/BE/BRUSSELS
4/12345678
:52A:ZYABEE20
:57A:AGRNMD2XXXX
:59F:/BE1234567891234
1/SMITH#JOHN
2/EVERGREEN AVE, 6
3/BE/BRUSSELS
:70:/RFB/BET072
:70:/INV/abc/SDF-96//1234-234///ROC/98I
U87
:70:/TSU/00000089963-0820-01/ABC-15/256
214,
:71A:SHA
-}
"
}
"occurred_at": "2020-01-01T12:34:56Z"
},
"subscription_id": "01234567-89ab-cdef-0123-456789abcdef",
"event_type": "swift-in#credit",
"schema_version": "2.0.0",
"sent_at": "2020-01-01T12:34:56Z"
}
Schema version 2.0.0 (latest)
| Field | Description | Format |
|---|---|---|
| data.action.type | Type of action (always credit) |
String |
| data.action.id | TransferID of the credit | Integer |
| data.action.profile_id | ProfileID for the transfer | Integer |
| data.action.account_id | AccountID for the transfer | Integer |
| data.resource.type | SWIFT message type | String |
| data.resource.id | ID of webhook | Integer |
| data.resource.message | Complete SWIFT Message as received | String |
| data.occurred_at | When the credit occurred | Datetime |
Card transaction state change events
Event type: cards#transaction-state-change
This event will be triggered every time a new card transaction is made or the transaction state changes.
Example
cards#transaction-state-changeevent:
{
"data": {
"resource": {
"profile_id": 14545089,
"client_id": "tw-test-connected-apps",
"card_token": "2e800c06-4ff2-409e-a4ad-e8f923bdb247",
"type": "card"
},
"transaction_id": 304672,
"transaction_type": "CASH_WITHDRAWAL",
"decline_reason": null,
"transaction_state": "IN_PROGRESS",
"transaction_amount": {
"value": 100.00,
"currency": "EUR"
},
"fees": [{
"amount": 1.00,
"currency": "EUR",
"fee_type": "ATM_WITHDRAWAL"
}],
"transaction_amount_with_fees": {
"value": 101.00,
"currency": "EUR"
},
"authorisation_method": "CHIP_AND_PIN",
"balance_transaction_id": 3069830,
"occurred_at": "2022-08-15T11:10:41Z"
},
"subscription_id": "191034cc-ed08-4510-970b-920970a3cf88",
"event_type": "cards#transaction-state-change",
"schema_version": "2.0.0",
"sent_at": "2022-08-22T07:59:50Z"
}
Schema version 2.0.0 (latest)
| Field | Description | Format |
|---|---|---|
| data.resource.profile_id | ID of the profile that owns the card | Integer |
| data.resource.client_id | Your api_client_id | String |
| data.resource.card_token | Unique identifier of the card | String |
| data.resource.type | Resource type (always card) |
String |
| data.transaction_id | ID of the transaction | Integer |
| data.transaction_type | Type of the transaction | String |
| data.decline_reason | Code of the decline reason if applicable | String |
| data.transaction_state | The current state of the transaction | String |
| data.transaction_amount.value | Transaction amount | Decimal |
| data.transaction_amount.currency | Currency code | String |
| data.fees[0].amount | Fee amount | Decimal |
| data.fees[0].currency | Currency code | String |
| data.fees[0].fee_type | Fee type | String |
| data.transaction_amount_with_fees.value | Transaction amount including fees | Decimal |
| data.transaction_amount_with_fees.currency | Currency code | String |
| data.authorisation_method | Authorisation method | String |
| balance_transaction_id | Balance transaction ID | Integer |
| data.occurred_at | When transaction or transaction state change occurred | Datetime |
Table of available transaction state and descriptions
| Code | Description |
|---|---|
| IN_PROGRESS | The transaction is still in progress |
| COMPLETED | The transaction is completed |
| DECLINED | The transaction has been declined |
| UNKNOWN | Default fallback status |
Table of available fee type and descriptions
| Code | Description |
|---|---|
| ATM_WITHDRAWAL | Fee charged by Wise |
| ATM_MACHINE | Fee charged by the ATM owner |
Balance Account
Balance accounts are included as part of the Wise Multi-Currency Account. Please refer to our multi-currency account guide for more information on the general use of the endpoints included below.
Balance account object
Example Balance Account:
{
"id": 22656,
"currency": "EUR",
"type": "STANDARD",
"name": null,
"icon": null,
"investmentState": "NOT_INVESTED",
"amount": {
"value": 0,
"currency": "EUR"
},
"reservedAmount": {
"value": 0,
"currency": "EUR"
},
"cashAmount": {
"value": 0,
"currency": "EUR"
},
"totalWorth": {
"value": 0,
"currency": "EUR"
},
"creationTime": "2020-05-20T14:43:16.658Z",
"modificationTime": "2020-05-20T14:43:16.658Z",
"visible": true,
}
| Field | Description | Format |
|---|---|---|
| id | balance id | integer |
| currency | balance currency (ISO 4217 Alphabetic Code) | text |
| type | balance type (STANDARD, SAVINGS) |
text |
| name | balance name | text |
| icon | emoji string | text |
| investmentState | Investment state of balance (NOT_INVESTED, INVESTED, DIVESTING, UNKNOWN) |
text |
| amount.value | Available balance value that can be used to fund transfers | decimal |
| amount.currency | balance currency (ISO 4217 Alphabetic Code) | text |
| reservedAmount.value | Amount reserved for transactions | decimal |
| reservedAmount.currency | balance currency (ISO 4217 Alphabetic Code) | text |
| cashAmount.value | Cash amount in the account | decimal |
| cashAmount.currency | balance currency (ISO 4217 Alphabetic Code) | text |
| totalWorth.value | Current total worth | decimal |
| totalWorth.currency | balance currency (ISO 4217 Alphabetic Code) | text |
| creationTime | date when the balance was created | timestamp |
| modificationTime | date when the balance was last modified | timestamp |
| visible | if balance is visible for the user or not | boolean |
Create balance account
Example Request:
curl -L -X POST 'https://api.sandbox.transferwise.tech/v3/profiles/{{profileId}}/balances' \
-H 'Authorization: Bearer <your api token>' \
-H 'Content-Type: application/json' \
-H 'X-idempotence-uuid: <uuid>' \
--data-raw '{
"currency": "EUR",
"type": "STANDARD"
}'
Example Response:
{
"id": 22656,
"currency": "EUR",
"type": "STANDARD",
"name": null,
"icon": null,
"investmentState": "NOT_INVESTED",
"amount": {
"value": 0,
"currency": "EUR"
},
"reservedAmount": {
"value": 0,
"currency": "EUR"
},
"cashAmount": {
"value": 0,
"currency": "EUR"
},
"totalWorth": {
"value": 0,
"currency": "EUR"
},
"creationTime": "2020-05-20T14:43:16.658Z",
"modificationTime": "2020-05-20T14:43:16.658Z",
"visible": true,
}
Purpose
This endpoint opens a balance within the specified profile, in the currency and type specified in the request.
For STANDARD balances, only one can be created for a currency. For SAVINGS balances, multiples in the same currency can be opened.
When sending the request, the currency and type are required. If creating a SAVINGS type balance, a name is also required.
Request
| Field | Description | Format |
|---|---|---|
| currency | balance currency (ISO 4217 Alphabetic Code) | text |
| type | Type of Balance. Accepts STANDARD or SAVINGS |
text |
| name | balance name | text |
List balance accounts
Example Request:
curl -X GET https://api.sandbox.transferwise.tech/v4/profiles/{{profileId}}/balances?types=STANDARD \
-H "Authorization: Bearer <your api token>"
Example Response:
[
{
"id": 22656,
"currency": "EUR",
"type": "STANDARD",
"name": null,
"icon": null,
"investmentState": "NOT_INVESTED",
"amount": {
"value": 0,
"currency": "EUR"
},
"reservedAmount": {
"value": 0,
"currency": "EUR"
},
"cashAmount": {
"value": 0,
"currency": "EUR"
},
"totalWorth": {
"value": 0,
"currency": "EUR"
},
"creationTime": "2020-05-20T14:43:16.658Z",
"modificationTime": "2020-05-20T14:43:16.658Z",
"visible": true,
},
...
]
Purpose
Retrieve the user's multi-currency account balance accounts. It returns all balance accounts the profile has in the types specified.
Parameters
A parameter of type must be passed and include at least a single type. To return more than one type, comma separate the values. Acceptable values are STANDARD and SAVINGS.
Get balance account by ID
Example Request:
curl -X GET https://api.sandbox.transferwise.tech/v4/profiles/{{profileId}}/balances/{{balanceId}} \
-H "Authorization: Bearer <your api token>"
Example Response:
{
"id": 22656,
"currency": "EUR",
"type": "STANDARD",
"name": null,
"icon": null,
"investmentState": "NOT_INVESTED",
"amount": {
"value": 0,
"currency": "EUR"
},
"reservedAmount": {
"value": 0,
"currency": "EUR"
},
"cashAmount": {
"value": 0,
"currency": "EUR"
},
"totalWorth": {
"value": 0,
"currency": "EUR"
},
"creationTime": "2020-05-20T14:43:16.658Z",
"modificationTime": "2020-05-20T14:43:16.658Z",
"visible": true,
}
Purpose
This endpoint returns a balance based on the specified balance ID.
Delete a balance
Example Request:
curl -X DELETE https://api.sandbox.transferwise.tech/v3/profiles/{{profileId}}/balances/{{balanceId}} \
-H "Authorization: Bearer {{access-token}}"
Example Response:
{
"id": 22656,
"currency": "EUR",
"type": "STANDARD",
"name": null,
"icon": null,
"amount": {
"value": 0.00,
"currency": "EUR"
},
"reservedAmount": {
"value": 0.00,
"currency": "EUR"
},
"creationTime": "2020-05-20T14:43:16.658Z",
"modificationTime": "2020-05-20T14:43:16.658Z",
"visible": true,
}
Purpose
Close a balance account for the users profile. Balance accounts must have a zero balance in order for it to be closed. Bank account details for a balance account will also be deactivated and may not be restored in the future.
Get balance account statement
Example Request:
curl -X GET https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/balance-statements/{balanceId}/statement.json?
intervalStart=2018-03-01T00:00:00.000Z&intervalEnd=2018-03-15T23:59:59.999Z&type=COMPACT \
-H "Authorization: Bearer <your api token>"
Example Response:
{
"accountHolder": {
"type": "PERSONAL",
"address": {
"addressFirstLine": "Veerenni 24",
"city": "Tallinn",
"postCode": "12112",
"stateCode": "",
"countryName": "Estonia"
},
"firstName": "Oliver",
"lastName": "Wilson"
},
"issuer": {
"name": "TransferWise Ltd.",
"firstLine": "56 Shoreditch High Street",
"city": "London",
"postCode": "E1 6JJ",
"stateCode": "",
"country": "United Kingdom"
},
"bankDetails": null,
"transactions": [
{
"type": "DEBIT",
"date": "2018-04-30T08:47:05.832Z",
"amount": {
"value": -7.76,
"currency": "EUR"
},
"totalFees": {
"value": 0.04,
"currency": "EUR"
},
"details": {
"type": "CARD",
"description": "Card transaction of 6.80 GBP issued by Tfl.gov.uk/cp TFL TRAVEL CH",
"amount": {
"value": 6.8,
"currency": "GBP"
},
"category": "Transportation Suburban and Loca",
"merchant": {
"name": "Tfl.gov.uk/cp",
"firstLine": null,
"postCode": "SW1H 0TL ",
"city": "TFL TRAVEL CH",
"state": " ",
"country": "GB",
"category": "Transportation Suburban and Loca"
}
},
"exchangeDetails": {
"forAmount": {
"value": 6.8,
"currency": "GBP"
},
"rate": null
},
"runningBalance": {
"value": 16.01,
"currency": "EUR"
},
"referenceNumber": "CARD-249281"
},
{
"type": "CREDIT",
"date": "2018-04-17T07:47:00.227Z",
"amount": {
"value": 200,
"currency": "EUR"
},
"totalFees": {
"value": 0,
"currency": "EUR"
},
"details": {
"type": "DEPOSIT",
"description": "Received money from HEIN LAURI with reference SVWZ+topup card",
"senderName": "HEIN LAURI",
"senderAccount": "EE76 1700 0170 0049 6704 ",
"paymentReference": "SVWZ+topup card"
},
"exchangeDetails": null,
"runningBalance": {
"value": 207.69,
"currency": "EUR"
},
"referenceNumber": "TRANSFER-34188888"
},
{
"type": "CREDIT",
"date": "2018-04-10T05:58:34.681Z",
"amount": {
"value": 9.94,
"currency": "EUR"
},
"totalFees": {
"value": 0,
"currency": "EUR"
},
"details": {
"type": "CONVERSION",
"description": "Converted 8.69 GBP to 9.94 EUR",
"sourceAmount": {
"value": 8.69,
"currency": "GBP"
},
"targetAmount": {
"value": 9.94,
"currency": "EUR"
},
"fee": {
"value": 0.03,
"currency": "GBP"
},
"rate": 1.147806
},
"exchangeDetails": null,
"runningBalance": {
"value": 9.94,
"currency": "EUR"
},
"referenceNumber": "CONVERSION-1511237"
}
],
"endOfStatementBalance": {
"value": 9.94,
"currency": "EUR"
},
"query": {
"intervalStart": "2018-03-01T00:00:00Z",
"intervalEnd": "2018-04-30T23:59:59.999Z",
"currency": "EUR",
"accountId": 64
}
}
Purpose
This endpoint allows for statements to be generated for the provided balanceId, with the response in JSON. To generate in CSV or PDF, replace statement.json with statement.csv or statement.pdf respectively in the above URL. Note that the PDF includes Wise branding.
The period between intervalStart and intervalEnd cannot exceed 469 days (around 1 year 3 months).
Request
GET https://api.sandbox.transferwise.tech/v1/profiles/{{profileId}}/balance-statements/{{balanceId}}/statement.json?
currency=EUR&intervalStart=2018-03-01T00:00:00.000Z&intervalEnd=2018-03-15T23:59:59.999Z&type=COMPACT
| Field | Description | Format |
|---|---|---|
| intervalStart | Statement start time in UTC time | Timestamp. |
| intervalEnd | Statement start time in UTC time | Timestamp. |
| type | COMPACT for a single statement line per transaction. FLAT for accounting statements where transaction fees are on a separate line. | Text |
Response
| Field | Description | Format |
|---|---|---|
| accountHolder.type | Account holder type: PERSONAL or BUSINESS | Text |
| accountHolder.address.addressFirstLine | Account holder address street | Text |
| accountHolder.address.city | Account holder address city | Text |
| accountHolder.address.postCode | Account holder address zipc ode | Text |
| accountHolder.address.stateCode | Account holder address state | Text |
| accountHolder.address.countryName | Account holder address country | Text |
| accountHolder.firstName | Account holder first name | Text |
| accountHolder.lastName | Account holder last name | Text |
| issuer.name | Account issuer name | Text |
| issuer.firstLine | Account issuer address street | Text |
| issuer.city | Account issuer address city | Text |
| issuer.postCode | Account issuer address zip code | Text |
| issuer.stateCode | Account issuer address state | Text |
| issuer.country | Account issuer address country | Text |
| bankDetails | Your local bank details | Group |
| transactions[n].type | DEBIT or CREDIT | Text |
| transactions[n].date | Time of transaction | Zulu time |
| transactions[n].amount.value | Transaction amount | Decimal |
| transactions[n].amount.currency | Transaction currency code | Text |
| transactions[n].totalFees.value | Transaction fee amount | Decimal |
| transactions[n].totalFees.currency | Transaction fee currency code | Text |
| transactions[n].details.type | CARD, CONVERSION, DEPOSIT, TRANSFER, MONEY_ADDED | Text |
| transactions[n].details.description | Human readable explanation about the transaction | Text |
| transactions[n].details.amount.value | Amount in original currency (card transactions abroad) | Decimal |
| transactions[n].details.amount.currency | Original currency code | Text |
| transactions[n].details.sourceAmount.value | Amount in source currency (conversions) | Decimal |
| transactions[n].details.sourceAmount.currency | Source currency code | Text |
| transactions[n].details.targetAmount.value | Amount in target currency (conversions) | Decimal |
| transactions[n].details.targetAmount.currency | Target currency code | Text |
| transactions[n].details.fee.value | Conversion fee amount | Decimal |
| transactions[n].details.fee.currency | Conversion fee currency code | Text |
| transactions[n].details.rate | Conversion exchange rate | Decimal |
| transactions[n].details.senderName | Deposit sender name | Text |
| transactions[n].details.senderAccount | Deposit sender bank account details | Text |
| transactions[n].details.paymentReference | Deposit payment reference text | Text |
| transactions[n].details.category | Card transaction category | Text |
| transactions[n].details.merchant.name | Card transaction merchant name | Text |
| transactions[n].details.merchant.firstLine | Merchant address street | Text |
| transactions[n].details.merchant.postCode | Merchant address zipcode | Text |
| transactions[n].details.merchant.city | Merchant address city | Text |
| transactions[n].details.merchant.state | Merchant address state | Text |
| transactions[n].details.merchant.country | Merchant address country | Text |
| transactions[n].details.merchant.category | Merchant category | Text |
| transactions[n].exchangeDetails.forAmount.value | Currency exchange amount | Decimal |
| transactions[n].exchangeDetails.forAmount.currency | Currency code | Text |
| transactions[n].exchangeDetails.rate | Exchange rate | Decimal |
| transactions[n].runningBalance.value | Running balance after the transaction | Decimal |
| transactions[n].runningBalance.currency | Running balance currency code | Text |
| transactions[n].referenceNumber | Wise assigned unique transaction reference number | Text |
| endOfStatementBalance.value | Closing balance for specified time period | Decimal |
| endOfStatementBalance.currency | Closing balance currency code | Text |
| query.intervalStart | Query parameter repeated | Zulu time |
| query.intervalEnd | Query parameter repeated | Zulu time |
| query.currency | Query parameter repeated | Text |
| query.accountId | Query parameter repeated | Integer |
Convert across balance accounts
Example Request:
curl -X POST https://api.sandbox.transferwise.tech/v2/profiles/{profileId}/balance-movements \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-H "X-idempotence-uuid: <your generated uuid> \
-d '{
"quoteId": <conversion quote id>
}'
Example Response:
{
"id": <conversion transaction id>,
"type": "CONVERSION",
"state": "COMPLETED",
"balancesAfter": [
{
"id": 1,
"value": 10000594.71,
"currency": "GBP"
},
{
"id": 2,
"value": 9998887.01,
"currency": "EUR"
}
],
"creationTime": "2017-11-21T09:55:49.275Z",
"steps": [
{
"id": 369588,
"type": "CONVERSION",
"creationTime": "2017-11-21T09:55:49.276Z",
"balancesAfter": [
{
"value": 9998887.01,
"currency": "EUR"
},
{
"value": 10000594.71,
"currency": "GBP"
}
],
"channelName": null,
"channelReferenceId": null,
"tracingReferenceCode": null,
"sourceAmount": {
"value": 113.48,
"currency": "EUR"
},
"targetAmount": {
"value": 100,
"currency": "GBP"
},
"fee": {
"value": 0.56,
"currency": "EUR"
},
"rate": 0.88558
}
],
"sourceAmount": {
"value": 113.48,
"currency": "EUR"
},
"targetAmount": {
"value": 100,
"currency": "GBP"
},
"rate": 0.88558,
"feeAmounts": [
{
"value": 0.56,
"currency": "EUR"
}
]
}
This endpoint allows the conversion of funds between two STANDARD balance accounts in different currencies. You first must generate a quote with "payOut": "BALANCE".
Interested in moving money in/out of Jar? Check Move money between balances
Request
POST https://api.sandbox.transferwise.tech/v2/profiles/{profileId}/balance-movements
Please also note that this call needs an extra field in the header called "X-idempotence-uuid". This should be generated and used for any subsequent retry call in the case that the initial POST fails.
| Field | Description | Format |
|---|---|---|
| profileId | Authenticated profile id. | Integer |
| quoteId | Quote id, quote must be created with "payOut": "BALANCE". |
UUID |
| X-idempotence-uuid | Unique identifier assigned by you. Used for idempotency check purposes. Should your call fail for technical reasons then you can use the same value again for making retry call. | UUID |
Move money between balances
Example Request:
curl -X POST https://api.sandbox.transferwise.tech/v2/profiles/{profileId}/balance-movements \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-H "X-idempotence-uuid: <your generated uuid> \
-d '{
"amount": {
value: <decimal>,
currency: <currency>
}
"sourceBalanceId": <source id>,
"targetBalanceId": <target balance id>,
"quoteId": <conversion quote id>
}'
Example Response:
{
"id": <conversion transaction id>,
"type": "CONVERSION",
"state": "COMPLETED",
"balancesAfter": [
{
"id": 1,
"value": 10000594.71,
"currency": "GBP"
},
{
"id": 2,
"value": 9998887.01,
"currency": "EUR"
}
],
"creationTime": "2017-11-21T09:55:49.275Z",
"steps": [
{
"id": 369588,
"type": "CONVERSION",
"creationTime": "2017-11-21T09:55:49.276Z",
"balancesAfter": [
{
"value": 9998887.01,
"currency": "EUR"
},
{
"value": 10000594.71,
"currency": "GBP"
}
],
"channelName": null,
"channelReferenceId": null,
"tracingReferenceCode": null,
"sourceAmount": {
"value": 113.48,
"currency": "EUR"
},
"targetAmount": {
"value": 100,
"currency": "GBP"
},
"fee": {
"value": 0.56,
"currency": "EUR"
},
"rate": 0.88558
}
],
"sourceAmount": {
"value": 113.48,
"currency": "EUR"
},
"targetAmount": {
"value": 100,
"currency": "GBP"
},
"rate": 0.88558,
"feeAmounts": [
{
"value": 0.56,
"currency": "EUR"
}
]
}
This endpoint allows the following money movements:
- Add money to same-currency Jar (i.e move money from
STANDARDtoSAVINGSbalance without conversion,amountis provided as request parameter); - Add money to another-currency Jar (i.e. convert money,
amountis determined by providedquoteId); - Withdraw money from Jar (i.e move money from
SAVINGStoSTANDARDbalance without conversion,amountis provided as request parameter).
Note that this call needs an extra field in header called "X-idempotence-uuid".
Interested in converting money from one balance to another? Check Convert across balance accounts
Request
POST https://api.sandbox.transferwise.tech/v2/profiles/{profileId}/balance-movements
| Field | Description | Format |
|---|---|---|
| profileId | Authenticated profile id. | Integer |
| sourceBalanceId | Source balance id. If present, targetBalanceId is required. |
Integer |
| targetBalanceId | Target balance id. If present, sourceBalanceId is required. |
Integer |
| quoteId | Quote id, quote must be created with "payOut": "BALANCE". Required for cross-currency movements. |
UUID |
| amount | Either amount or quoteId are required. |
Money |
| X-idempotence-uuid | Unique identifier assigned by you. Used for idempotency check purposes. Should your call fail for technical reasons then you can use the same value again for making retry call. | UUID |
Deprecated
Get Account Balance
Example Request:
curl -X GET https://api.sandbox.transferwise.tech/v1/borderless-accounts?profileId={profileId} \
-H "Authorization: Bearer <your api token>"
Example Response:
[
{
"id": 64,
"profileId": <your profile id>,
"recipientId": 13828530,
"creationTime": "2018-03-14T12:31:15.678Z",
"modificationTime": "2018-03-19T15:19:42.111Z",
"active": true,
"eligible": true,
"balances": [
{
"balanceType": "AVAILABLE",
"currency": "GBP",
"amount": {
"value": 10999859,
"currency": "GBP"
},
"reservedAmount": {
"value": 0,
"currency": "GBP"
},
"bankDetails": null
},
{
"balanceType": "AVAILABLE",
"currency": "EUR",
"amount": {
"value": 9945236.2,
"currency": "EUR"
},
"reservedAmount": {
"value": 0,
"currency": "EUR"
},
"bankDetails": {
"id": 90,
"currency": "EUR",
"bankCode": "DEKTDE7GXXX",
"accountNumber": "DE51 7001 1110 6050 1008 91",
"swift": "DEKTDE7GXXX",
"iban": "DE51 7001 1110 6050 0008 91",
"bankName": "Handelsbank",
"accountHolderName": "Oliver Wilson",
"bankAddress": {
"addressFirstLine": "Elsenheimer Str. 41",
"postCode": "80687",
"city": "München",
"country": "Germany",
"stateCode": null
}
}
}
]
}
]
Get available balances for all activated currencies in your multi-currency account.
Request
GET https://api.sandbox.transferwise.tech/v1/borderless-accounts?profileId={profileId}
Use profile id obtained earlier to make this call.
Response
| Field | Description | Format |
|---|---|---|
| id | Multi-currency account id | Integer |
| profileId | Personal or business profile id | Integer |
| recipientId | Recipient id you can use for a multi-currency account deposit | Integer |
| creationTime | Date when multi-currency account was opened | Timestamp |
| modificationTime | Date when multi-currency account setup was modified. | Timestamp |
| active | Is multi-currency account active or inactive | Boolean |
| eligible | Ignore | Boolean |
| balances[n].balanceType | AVAILABLE | Text |
| balances[n].currency | Currency code | Text |
| balances[n].amount.value | Available balance in specified currency | Decimal |
| balances[n].amount.currency | Currency code | Text |
| balances[n].reservedAmount.value | Reserved amount from your balance | Decimal |
| balances[n].reservedAmount.currency | Reserved amount currency code | Text |
| balances[n].bankDetails | Bank account details assigned to your multi-currency account. Available for EUR, GBP, USD, AUD, NZD | Group |
| balances[n].bankDetails.id | Bank account details id | Integer |
| balances[n].bankDetails.currency | Bank account currency | Text |
| balances[n].bankDetails.bankCode | Bank account code | Text |
| balances[n].bankDetails.accountNumber | Bank account number | Text |
| balances[n].bankDetails.swift | Bank account swift code | Text |
| balances[n].bankDetails.iban | Bank account iban | Text |
| balances[n].bankDetails.bankName | Bank name | |
| balances[n].bankDetails.accountHolderName | Bank account holder name | Text |
| balances[n].bankDetails.bankAddress.addressFirstLine | Bank address street and house | Text |
| balances[n].bankDetails.bankAddress.postCode | Bank address zip code | Text |
| balances[n].bankDetails.bankAddress.city | Bank address city | Text |
| balances[n].bankDetails.bankAddress.country | Bank address country | Text |
| balances[n].bankDetails.bankAddress.stateCode | Bank address state code | Text |
Get Account Statement
Example Request:
curl -X GET https://api.sandbox.transferwise.tech/v3/profiles/{profileId}/borderless-accounts/{borderlessAccountId}/statement.json?
currency=EUR&intervalStart=2018-03-01T00:00:00.000Z&intervalEnd=2018-03-15T23:59:59.999Z&type=COMPACT \
-H "Authorization: Bearer <your api token>"
Example Response:
{
"accountHolder": {
"type": "PERSONAL",
"address": {
"addressFirstLine": "Veerenni 24",
"city": "Tallinn",
"postCode": "12112",
"stateCode": "",
"countryName": "Estonia"
},
"firstName": "Oliver",
"lastName": "Wilson"
},
"issuer": {
"name": "TransferWise Ltd.",
"firstLine": "56 Shoreditch High Street",
"city": "London",
"postCode": "E1 6JJ",
"stateCode": "",
"country": "United Kingdom"
},
"bankDetails": null,
"transactions": [
{
"type": "DEBIT",
"date": "2018-04-30T08:47:05.832Z",
"amount": {
"value": -7.76,
"currency": "EUR"
},
"totalFees": {
"value": 0.04,
"currency": "EUR"
},
"details": {
"type": "CARD",
"description": "Card transaction of 6.80 GBP issued by Tfl.gov.uk/cp TFL TRAVEL CH",
"amount": {
"value": 6.8,
"currency": "GBP"
},
"category": "Transportation Suburban and Loca",
"merchant": {
"name": "Tfl.gov.uk/cp",
"firstLine": null,
"postCode": "SW1H 0TL ",
"city": "TFL TRAVEL CH",
"state": " ",
"country": "GB",
"category": "Transportation Suburban and Loca"
}
},
"exchangeDetails": {
"forAmount": {
"value": 6.8,
"currency": "GBP"
},
"rate": null
},
"runningBalance": {
"value": 16.01,
"currency": "EUR"
},
"referenceNumber": "CARD-249281"
},
{
"type": "CREDIT",
"date": "2018-04-17T07:47:00.227Z",
"amount": {
"value": 200,
"currency": "EUR"
},
"totalFees": {
"value": 0,
"currency": "EUR"
},
"details": {
"type": "DEPOSIT",
"description": "Received money from HEIN LAURI with reference SVWZ+topup card",
"senderName": "HEIN LAURI",
"senderAccount": "EE76 1700 0170 0049 6704 ",
"paymentReference": "SVWZ+topup card"
},
"exchangeDetails": null,
"runningBalance": {
"value": 207.69,
"currency": "EUR"
},
"referenceNumber": "TRANSFER-34188888"
},
{
"type": "CREDIT",
"date": "2018-04-10T05:58:34.681Z",
"amount": {
"value": 9.94,
"currency": "EUR"
},
"totalFees": {
"value": 0,
"currency": "EUR"
},
"details": {
"type": "CONVERSION",
"description": "Converted 8.69 GBP to 9.94 EUR",
"sourceAmount": {
"value": 8.69,
"currency": "GBP"
},
"targetAmount": {
"value": 9.94,
"currency": "EUR"
},
"fee": {
"value": 0.03,
"currency": "GBP"
},
"rate": 1.147806
},
"exchangeDetails": null,
"runningBalance": {
"value": 9.94,
"currency": "EUR"
},
"referenceNumber": "CONVERSION-1511237"
}
],
"endOfStatementBalance": {
"value": 9.94,
"currency": "EUR"
},
"query": {
"intervalStart": "2018-03-01T00:00:00Z",
"intervalEnd": "2018-04-30T23:59:59.999Z",
"currency": "EUR",
"accountId": 64
}
}
Get multi-currency account statement for one currency and for specified time range. The period between intervalStart and intervalEnd cannot exceed 455 days (around 1 year 3 month).
Request
GET https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/balance-statements/{balanceId}/statement.json? currency=EUR&intervalStart=2018-03-01T00:00:00.000Z&intervalEnd=2018-03-15T23:59:59.999Z&type=COMPACT
| Field | Description | Format |
|---|---|---|
| borderlessAccountId | This is included in the Get Account Balance response "id" field. | Integer |
| currency | Currency code | Text |
| intervalStart | Statement start time in UTC time | Zulu time. Don't forget the 'Z' at the end. |
| intervalEnd | Statement start time in UTC time | Zulu time. Don't forget the 'Z' at the end. |
| type (optional) | COMPACT (default) for a single statement line per transaction. FLAT for accounting statements where transaction fees are on a separate line. | Text |
Note that you can also download statements in PDF and CSV formats if you replace statement.json with statement.csv or statement.pdf respectively in the above URL.
Response
| Field | Description | Format |
|---|---|---|
| accountHolder.type | Account holder type: PERSONAL or BUSINESS | Text |
| accountHolder.address.addressFirstLine | Account holder address street | Text |
| accountHolder.address.city | Account holder address city | Text |
| accountHolder.address.postCode | Account holder address zipc ode | Text |
| accountHolder.address.stateCode | Account holder address state | Text |
| accountHolder.address.countryName | Account holder address country | Text |
| accountHolder.firstName | Account holder first name | Text |
| accountHolder.lastName | Account holder last name | Text |
| issuer.name | Account issuer name | Text |
| issuer.firstLine | Account issuer address street | Text |
| issuer.city | Account issuer address city | Text |
| issuer.postCode | Account issuer address zip code | Text |
| issuer.stateCode | Account issuer address state | Text |
| issuer.country | Account issuer address country | Text |
| bankDetails | Your local bank details | Group |
| transactions[n].type | DEBIT or CREDIT | Text |
| transactions[n].date | Time of transaction | Zulu time |
| transactions[n].amount.value | Transaction amount | Decimal |
| transactions[n].amount.currency | Transaction currency code | Text |
| transactions[n].totalFees.value | Transaction fee amount | Decimal |
| transactions[n].totalFees.currency | Transaction fee currency code | Text |
| transactions[n].details.type | CARD, CONVERSION, DEPOSIT, TRANSFER, MONEY_ADDED | Text |
| transactions[n].details.description | Human readable explanation about the transaction | Text |
| transactions[n].details.amount.value | Amount in original currency (card transactions abroad) | Decimal |
| transactions[n].details.amount.currency | Original currency code | Text |
| transactions[n].details.sourceAmount.value | Amount in source currency (conversions) | Decimal |
| transactions[n].details.sourceAmount.currency | Source currency code | Text |
| transactions[n].details.targetAmount.value | Amount in target currency (conversions) | Decimal |
| transactions[n].details.targetAmount.currency | Target currency code | Text |
| transactions[n].details.fee.value | Conversion fee amount | Decimal |
| transactions[n].details.fee.currency | Conversion fee currency code | Text |
| transactions[n].details.rate | Conversion exchange rate | Decimal |
| transactions[n].details.senderName | Deposit sender name | Text |
| transactions[n].details.senderAccount | Deposit sender bank account details | Text |
| transactions[n].details.paymentReference | Deposit payment reference text | Text |
| transactions[n].details.category | Card transaction category | Text |
| transactions[n].details.merchant.name | Card transaction merchant name | Text |
| transactions[n].details.merchant.firstLine | Merchant address street | Text |
| transactions[n].details.merchant.postCode | Merchant address zipcode | Text |
| transactions[n].details.merchant.city | Merchant address city | Text |
| transactions[n].details.merchant.state | Merchant address state | Text |
| transactions[n].details.merchant.country | Merchant address country | Text |
| transactions[n].details.merchant.category | Merchant category | Text |
| transactions[n].exchangeDetails.forAmount.value | Currency exchange amount | Decimal |
| transactions[n].exchangeDetails.forAmount.currency | Currency code | Text |
| transactions[n].exchangeDetails.rate | Exchange rate | Decimal |
| transactions[n].runningBalance.value | Running balance after the transaction | Decimal |
| transactions[n].runningBalance.currency | Running balance currency code | Text |
| transactions[n].referenceNumber | Wise assigned unique transaction reference number | Text |
| endOfStatementBalance.value | Closing balance for specified time period | Decimal |
| endOfStatementBalance.currency | Closing balance currency code | Text |
| query.intervalStart | Query parameter repeated | Zulu time |
| query.intervalEnd | Query parameter repeated | Zulu time |
| query.currency | Query parameter repeated | Text |
| query.accountId | Query parameter repeated | Integer |
Convert Currencies
Example Request:
curl -X POST https://api.sandbox.transferwise.tech/v1/borderless-accounts/{borderlessAccountId}/conversions \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-H "X-idempotence-uuid: <your generated uuid> \
-d '{
"quoteId": <conversion quote id>
}'
Example Response:
{
"id": <conversion transaction id>,
"type": "CONVERSION",
"state": "COMPLETED",
"balancesAfter": [
{
"value": 10000594.71,
"currency": "GBP"
},
{
"value": 9998887.01,
"currency": "EUR"
}
],
"creationTime": "2017-11-21T09:55:49.275Z",
"steps": [
{
"id": 369588,
"type": "CONVERSION",
"creationTime": "2017-11-21T09:55:49.276Z",
"balancesAfter": [
{
"value": 9998887.01,
"currency": "EUR"
},
{
"value": 10000594.71,
"currency": "GBP"
}
],
"channelName": null,
"channelReferenceId": null,
"tracingReferenceCode": null,
"sourceAmount": {
"value": 113.48,
"currency": "EUR"
},
"targetAmount": {
"value": 100,
"currency": "GBP"
},
"fee": {
"value": 0.56,
"currency": "EUR"
},
"rate": 0.88558
}
],
"sourceAmount": {
"value": 113.48,
"currency": "EUR"
},
"targetAmount": {
"value": 100,
"currency": "GBP"
},
"rate": 0.88558,
"feeAmounts": [
{
"value": 0.56,
"currency": "EUR"
}
]
}
Convert funds between your multi-currency account currencies.
Quote which is used in this call must be created with "payOut": "BALANCE".
Note that this call needs an extra field in header called "X-idempotence-uuid".
Request
POST https://api.sandbox.transferwise.tech/v1/borderless-accounts/{borderlessAccountId}/conversions
| Field | Description | Format |
|---|---|---|
| profileId | This is included in the Get Account Balance response "id" field. | Integer |
| X-idempotence-uuid | Unique identifier assinged by you. Used for idempotency check purposes. Should your call fail for technical reasons then you can use the same value again for making retry call. | UUID |
Errors
HTTP Status Codes
We use common HTTP status codes included in the response header to indicate success or failure.
| Code | Description |
|---|---|
| 200 | OK. Successful request. |
| 201 | OK. Resource created. |
| 400 | Bad request. Request message data did not pass validation. |
| 401 | Unauthorised. Not authorised to access requested data. |
| 403 | Forbidden. Access to requested data is forbidden. |
| 404 | Not Found. Requested resource does not exist. |
| 408 | Timeout. Operation timed out. |
| 422 | Unprocessable entity. Request message data did not pass validation. |
| 500 | Server error. |
Validation Errors
Example Validation Error:
{
"errors": [
{
"code": "error.route.not.supported",
"message": "This route is not supported",
"arguments": [
"CNY-EUR"
]
}
]
}
Data validation or violation of business rules related errors. Response could contain multiple errors.
Authentication Errors
Example Authentication Error:
{
"error": "unauthorized",
"error_description": "Full authentication is required to access this resource"
}
Security related errors.
System Errors
Example System Error:
{
"timestamp": "2017-02-02T13:07:39.644+0000",
"status": 500,
"error": "Internal Server Error",
"exception": "java.lang.NullPointerException",
"message": "No message available",
"path": "/v1/quotes/0b63b0cb-2041-4bc4-b3fc-1e51a1454a1b/account-requirements"
}
Something went wrong in our side.