Wise for Banks API

Welcome to the Wise for Banks API documentation.

Base URL Sandbox

https://api.sandbox.transferwise.tech

Base URL LIVE

https://api.transferwise.com

What is it?

Building a bank integration with Wise allows a bank to offer Wise transfers directly to their users through their online banking or mobile apps.

What are the benefits for my bank?

• Provide your customers access to some of the fastest and cheapest cross-border payments available to consumers and businesses today.
• Offer competitive, fair, and transparent pricing to customers at the mid-market exchange rate.
• Reduce your operational costs of cross-border payments.
• Stop losing out on cross-border revenues because your customers are finding better alternatives.

How does it work?

• Transparent and fair pricing - Your customers will get the same price no matter if they make transfers via your bank integration or directly via Wise.
• Same great Wise service - Your customers get access to our 24/7 customer support.
• Custom solution - We’ll work together to find and build a solution that works for your bank. There’s no one-size-fits-all approach. Together we’ll decide:
  • How do we set up flow of funds?
  • How do we handle customer support?
  • How do we harmonise customer onboarding and AML processes?

See what some of our bank partners have to say

• Monzo and Wise in United Kingdom
• N26 and Wise in Germany and Europe
• EQ and Wise in Canada
• Novo and Wise in the USA

An example native user experience based on the Wise Platform API

Please also see our Design Guide for more examples and information on how we recommend to design your integration. This resource is useful to see how the flow should work from a user point of view, along with "dos" and "don'ts" for each screen in the flow.

Please visit our Postman collection for more details and examples of how to use our API, including how to implement payment initiation, user linking, creation and others.

Please contact banks@wise.com to get started.

Wise for Banks API Integration Guide

This guide describes in detail the technical implementation of a Wise integration for a bank. If you need any help please reach out to the Wise team here.

Please visit our Postman collection for more details and examples of how to use our API, including how to implement payment initiation, user linking, creation and others.

API access

Wise uses standard OAuth 2.0 protocol for authentication and authorization.

Once our partnership begins, we’ll send you API access credentials for the sandbox environment consisting of a Client ID and a Client Secret. The credentials are needed to either create users over API or complete the authorization_code OAuth 2.0 grant type through which the customer will allow your application access to their account.

The Client secret is a very sensitive piece of data as it could be used to impersonate your institution on the Wise Platform API. It should be handled and stored with the upmost care, seen by as few people as possible and stored in a secure secret storage solution, preferably away from any other Wise data such as user API access tokens.

We also need redirect_url from your technical team which is used to forward users to after successfully granting your application access to their Wise account. Specifying this explicitly makes the integration more secure. This article about OAuth 2.0 framework is a great way to refresh your knowledge about the protocol itself.

SANDBOX and LIVE environments

• Sandbox API is located at https://api.sandbox.transferwise.tech
• LIVE API is located at https://api.transferwise.com

Integration architecture

You will build your Wise user experience directly into your mobile and desktop applications, and will build a backend service to support the features it offers. Your user interface should never directly call any authenticated Wise endpoint which requires an API token, this should always be done by your backend system.

Depending on the features and settlement model you will build, there are some different components you will need to build. Please ask your Wise implementation team for advice based on the requirements of your integration.

User experience

There are different ways to build your user experience, especially when it comes to the sequence of steps in the payment flow, but we have a recommended order that is described in our Integration Design Guide. We strongly recommend you follow this flow as it has been tuned by the Wise team to be the simplest to understand for the customer and the easiest to build using the APIs defined below.

We are happy to help you to design and build a great experience for your customers using our experience so please don't hesitate to get in touch if you need advice, especially if you want to deviate from the recommended flow.

Building your backend

You should expose an API internally for your web and mobile clients to call to provide the required Wise features. Your backend system will manage both communication to the Wise Platform API and internal operations such as querying user KYC data to send to Wise, checking a user has sufficient funds to make the requested transfer and triggering the payment of funds to Wise when a user confirms a transfer.

You should also store a copy of certain data relating to Wise to decrease latency and increase resiliency when users review previous transfers they have made or recipients they sent funds to. The extent of what you store will depend on your integration, but we recommend mend to store at a minimum:

• Quotes that have been used to create transfers
• Transfer records including ID and status
• Recipient IDs, names and account summary data

The goal is to store locally in your platform all the data you need to drive your UI, such that calling our API is not required when reviewing historic data.

You should subscribe to our webhooks to keep this data up to date.

We have a dedicated team focusing on bank partnerships who will help you along the way, sharing knowledge and experience from previous integrations to help you build a robust and highly available system.

Your Wise user experience

There are two main user flows that must be built in order to integrate with Wise.

The user onboarding flow

There are two ways to access the Wise Platform API depending on if you customer already has a Wise account or not. You should handle both cases in your integration.

This flowchart describes the different scenarios you will encounter and how you should handle them.

You need to go through this flow only once for each customer before they can set up their first transfer.

• Gain access to a Wise user:
  • by creating a new account over API
  • OR
  • by linking to an existing account
• Create personal user profile
• Create business user profile - this is an optional step only to be used if your bank is providing business customers access to Wise.

Upon linking to an existing Wise account you need to ensure that you have connected to an account that represents the same natural person or business of the bank account in your platform. To do this for personal profiles please check the date of birth of the connected Wise profile matched the date of birth you hold for that customer in your platform. For businesses the comparison required changes with the region you are servicing, please discuss the best approach with your implementation team.

The transfer flow

To create transfers on behalf of users you need these building blocks:

• Refresh user's access token
• Create quote
• Create recipient account
• Create transfer
• Fund transfer

Create a new Wise account over API

If a user doesn't already have a Wise account then you can create one for them. The signup with registration code feature lets you create new users directly via an API call. You will send via API all of the data Wise needs to serve these users in your region, meaning users have their accounts created without ever leaving your banking app, making a very streamlined flow.

You will define a registration_code for the user that act similarly to a password, although is limited in scope to be used only by your integration over the API. You exchange this value for user tokens, as described in the detailed documentation above. This code can be used to regenerate tokens should they become invalid so you should save it in your database to allow this. Due to the password-like nature of this data we recommend to store it encrypted at rest for security.

We can provide this option to banks where we can create a trusted reliance or outsourcing model on your KYC processes.

Below is a sequence diagram showing this flow.

If you attempt to create a user that already has a Wise account they will always need to be redirected to the account linking flow, you can detect this at the point you attempt to create the user based on the API response of 409 conflict. See the detailed guide under the endpoint documentation for more details.

Note that these new users have to accept the Wise Terms and Conditions as part of their sign up process, which should be available for them to read as a link to our website or using the endpoint Terms and conditions..

Linking to an existing Wise account

At a high level there are two steps to gaining access to an existing Wise account.

1. Obtain an authorization code
2. Exchange the authorization code for API tokens

There are two possible ways to get an authorization code — by opening the Wise website, having the user login and agree to connect accounts and then redirect back to your app, or by us sending an email to the end user with a link to login to Wise and the user then manually typing a code in to your app. The redirection flow is always preferred as it requires no manual user actions. In some cases it is not possible to securely open the Wise website within your app, in which case the email flow can be used. Before using the email flow please discuss the implications with your implementation teams.

Redirecting to the Wise website

The standard website redirection flow is as follows:

1. Your app redirects the user to Wise authorization web page.
2. The user logs in to Wise.
3. The user agrees to provide access and the Wise authorization page then redirects user back to your pre-configured redirect_url, including an authorization code you can use to generate user tokens. e.g.

   https://www.yourbank.com/transferwise-link-page/?code=[CODE]&profileID=123

These steps are explained in more detail below.

1. Your banking app redirects user to Wise authorization web page

Your website or app opens the following url in the user's browser.

Sandbox:
https://sandbox.transferwise.tech/oauth/authorize/?client_id={clientId}&redirect_uri={redirectUri}

Production:
https://wise.com/oauth/authorize/?client_id={clientId}&redirect_uri={redirectUri}

List of available parameters:

On mobiles apps you should not use legacy WebView components to show the authorization page to the users because they are not secure and will not allow users to log in to Wise with Google, which is an option used by many of our users. Your app should instead open the device's full browser app or use the newer iOS and Android features to show isolated web pages within apps in a secure way, namely a SafariViewController or a ChromeCustomTab, respectively.

Please also note that provided [CODE] expires within 30 minutes and is one time use only.

2. The user logs in to Wise

Our usual log in screens are presented to the user if they are not already logged in on the browser being used. If enabled for a user they will also be prompted to go through our two-factor authentication procedure.

3. The user agrees to grant access and we forward them to your redirect_url

Once a user gives your banking app authorization to connect to Wise and access their data, the user is redirected back to your redirect_url with a generated code query string value. For example

https://www.yourbank.com/transferwise-link-page/?code=[CODE]&profileID=123

Your website or service can then use this code to obtain the access token to act on behalf of the user account described in the Exchange an authorization code for API tokens section below.

If you are building your Wise integration as a native mobile phone app then the redirect URL should be able to handle returning the user to the correct place in the app, using a "deep link" based on a custom URL scheme defined by your mobile app.

Wise sends an email to the customer to give them an authorization code

If the website based flow is not possible for you then you can request for Wise to email the customer with a link for them to get an authorization code. This enables the user linking flow but avoids having to redirect the user to an external website. The flow is more cumbersome for a user so should only be used as a last resort. To enable this flow, you must send the sendAuthorizationCodeAsEmail parameter as true when calling the POST /v2/users endpoint. Where this is true, and a user already exists for the email you try to create, then we will send the user an email with a link to access the Wise authorization page, which will show them the authorization code. The user would then type this code in to your app, rather than you receive it via a redirect.

In the event of a 409 response the flow should be as follows:

1. Wise emails the customer a link to log in and generate an authorization code.
2. The user opens their email app and clicks the link in the email. They login to their Wise account, grant access, and are presented the code.
3. The user can then enter the authorization code in to your app.
4. Your backend exchanges the authorization code for access tokens.

These steps are explained in more detail below.

1. Wise emails the customer a link to log in and generate an authorization code

Once triggered, your UI should instruct the user to find the email and follow the flow.

You should also give the user a text field to type in the authorization code, it will be six characters, alphanumeric.

As an example, below are examples of the links that will be included in the email to the user. Note the forwardingMode=showCode parameter included in the URL. This ensures the

Sandbox:
https://sandbox.transferwise.tech/oauth/authorize/?client_id={clientId}&redirect_uri={redirectUri}&forwardingMode=showCode

Production:
https://wise.com/oauth/authorize/?client_id={clientId}&redirect_uri={redirectUri}&forwardingMode=showCode

2. The user opens their email app and clicks the link in the email. They login and view the code.

Our usual log in screens are presented to the user if they are not already logged in on the browser being used. If enabled for a user they will also be prompted to go through our two-factor authentication procedure.

The user will then be shown the authorization screen, where they will see your logo and a list of permissions they are granting to your application. They will be asked to approve.

Once approved, the user will then be presented with the six character authorization code, with instructions that they must type in the code to your app directly above the code.

Please also note that provided code expires within 30 minutes and is one time use only.

3. The user enters the authorization code in to your app.

The user then manually types the code in to your app, and submit it to your backend platform, which can then use this code to obtain the access token to act on behalf of the user account, as described in the next section.

Example Request:

curl \
-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' \
'https://api.sandbox.transferwise.tech/oauth/token' 

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

Exchange an authorization code for API tokens

The final step is to use the authorization code and exchange it for customer tokens.

See the example request to the right to exchange an access code for API tokens.

Actions after linking an account

Upon linking to an existing Wise account you need to ensure that you have connected to an account that represents the same natural person or business of the bank account in your platform. To do this for personal profiles please check the date of birth of the connected wise profile matched the date of birth you hold for that customer in your platform. For businesses the comparison required changes with the region you are servicing, please discuss the best approach with your implementation team.

Using tokens

When calling API endpoints you need to provide the user's access_token in the request's HTTP header in the format Authorization: Bearer <access_token>. Access tokens are short lived for security reasons, they are only valid for 12 hours by default. When they expire you need to use the refresh_token to generate a new access_token.

This means you have to securely store the user's refresh_token in order to generate a new access_token each time they use your Wise integration. We recommend storing all tokens encrypted when at rest in tour database, to reduce the impact of any data breach.

Use the refresh token to generate a new access token using the following API call.

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.

Response

Below is an end-to-end sequence diagram for connecting to an existing Wise user.

Refresh a user access token

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",
    "created_at": "2022-08-11T19:07:46.421141182Z"
  }

Access tokens are designed to expire after a shot period of time, representing a login session to the Wise Platform API. This increases security of the user's account 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.

Response

Token Expiry

It is also possible that a user's refresh token will become invalid. This could happen for a number of reasons, for example:

• The refresh token's validity period expires (usually set at at three months or more)
• The user revokes the access of your application to their account.
• The user enables enhanced security on their Wise account.
• Wise revoke a token due to a suspected security breach of the token or your client secret.

Due to this possibility your application should handle the scenario where tou fail to generate a new access token from the refresh token. Correctly handling this depends on how you originally gained access to the user.

1. An existing user granted your application access to the account

If you were granted access by an existing user then you should send the user through the same flow as you initially did to generate tokens described in linking to an existing Wise account. You will then have new access and refresh tokens generated which you can now store and use as before.

2. Your application created the user

In the case you created the user using the user creation over API flow then the mechanism for regenerating tokens is dependent on whether the user you created has "reclaimed" their Wise account and used our website or apps directly, which they may have done by following a secure process on our website or apps.

If the user has not reclaimed their account then the original registration_code you generated should still be able to generate new tokens for the user. Because of this you should store this code alongside the created user ID in your database at the point of user generation, encrypted for security purposes.

If the previously stored token fails with an error code 400 and error:

{
  "error": "invalid_grant",
  "error_description": "Invalid user credentials."
}

then you can assume the user has reclaimed the account and push them through the linking to an existing Wise account flow.

Create personal user profile

The next step is to ensure Wise is sent the user's profile data, which identifies that person or business based on data such as name, date of birth, business registration number, etc.

When you first get access to a user's Wise account you cannot predict if they already have submitted their profile data to Wise or not.

The User Profiles.List endpoint will give you data for both personal and business profiles, if they exist. This makes it easy to figure out if a user has already set up this data with Wise or not. If the user already has a personal profile set up, then you can skip this creation step.

If you created the user over API then you always need to create a personal profile for the user, however it is possible you will also need to do it when getting access to an existing user account should we have incomplete data, as noted above.

There are several steps to creating a new personal user profile:

1. Create personal user profile – general data. This includes customer name, date of birth, and phone number.

2. Create personal user profile – upload verification ID data. If required for your integration (dependent on jurisdiction) then send ID document information for your user. The Wise integration team will work on this with you to decide if it is required.

3. Open update window. Open the update window for the profile updates.

4. Create personal user profile – address data. Add address information to the personal user profile.

5. Close update window. Close the update window for the profile updates.

Create business user profile

A personal profile has to be created first. You can’t create a business user profile without a personal profile.

Creating a business profile is similar to how you created a personal profile. There are six steps:

1. Create business user profile – general data. This includes business name, type and other information.

2. Open update window. Open the update window for the profile updates.

3. Create business user profile – address data. Add address information to the business user profile.

4. Create business user profile - director data. Add business director information to the business user profile.

5. Create business user profile - UBO data. Add ultimate business owner information to the business user profile.

6. Close update window. Close the update window for the profile updates.

Profile extensions

Some regions demand more profile data due to local regulations, in order to be compliant the extra data has to be provided. This is required based on jurisdiction of operation and customer demographics of your bank or other financial institution, please discuss with your implementation team to see if it is necessary to include the following behaviour. To collect this data please use our User Profile Extensions dynamic form endpoint.

Transfer Flow

Once you have access to a user and their profile is set up, you can then allow them to continue to the transfer flow in order to start making international transfers.

The next time the user comes to use Wise, you do not need to go through the user onboarding flow again. You can use the refresh tokens you have stored in your database in order to generate an access token and allow the user to access the transfer flow immediately.

Create quote

A quote represents how much money a user wants to send, plus the real exchange rate and fees offered to them by Wise.

Please look at Create quote under Full API Reference.

You must include the profile ID when creating the quote using the profile parameter.

Create or select recipient account

The next thing is to choose who will receive the funds, either by selecting an existing recipient bank account the user previously created by or the user entering data to create a new one.

Please look at Create recipient account under Full API Reference for information on the calls to create recipients, using our dynamic from solution. Currently we return an email recipient type for all currencies but this is not appropriate for the bank/FI use case, please filter it out in your client to remove it.

Use the GET accounts endpoint to load the user's previously used recipients and allow them to select from them in your user interface. This allows them to only have to create a recipient once and then re-use it in future, plus it allows existing Wise users to use their familiar recipients from our platform.

You should store a cached copy of the recipients that are used by users of your app such that you can load that data again quickly to show in your UI, for example a transfer tracking screen might show recipient data. You could either store the entire data or just the name and accountSummary of the recipient.

Please note, when creating a new transfer always reload the full list of recipients over our API rather than use the ones you have saved because you cannot be certain the recipients that you store a copy of have not been deleted on Wise in the meantime.

Update quote with selected recipient

Now that a recipient has been selected you need to update the quote with that recipient in order for us to calculate if the price has changed based on that selection. For example the fees and delivery estimate are different in the case of sending USD to a country other than the USA - we call this Global USD.

You need to do this in order to show the customer the correct final price and delivery estimate time before they commit to creating and funding the transfer.

Please look at Update quote under the full API Reference to learn how to do this.

Create transfer

The final API step is to create the transfer, using the quote and selected recipient account ID

Please look at Create transfer under the full API Reference for information on creating a transfer using your quote and recipient.

Fund transfer

There are several settlement mechanisms offered by Wise. The most simple is to trigger a bank transfer or wire directly from the customer's account to our bank account in your currency. We also offer bulk settlement models, which are documented separately. Below describes the direct transfer by transfer funding mechanism.

Once you have successfully created a transfer via the Wise Platform API you should debit the exact source amount from your customer's bank account and send the funds to Wise’s local bank account via a domestic payment. You should send the amount provided in the final quote object after any recipient updates for global currencies using PATCH quote. The details of this bank account will be shared with you by the Wise team helping your integration.

In order for us to link this incoming domestic payment with a corresponding transfer order, we need you to use specific text in the "payment reference" field. Get the transfer id for the transfer you're trying to fund and append the letter T as a prefix. So for a hypothetical transfer with id 80106743, the correct "payment reference" would be T80106743. Include this string in the reference when sending the funds to Wise's bank account.

Alternatively, we offer a "prefunded" model to some banks who want to speed up transfers for their customers in regions where the domestic payment networks are slow. If you are interested in this model please get in touch with the Wise team to discuss the option and for technical documentation on how it works.

Transfer flow sequence

Below is a sequence diagram to show the full transfer flow.

Track transfer status

You should use a subscription to application webhooks to keep the statuses of your local transfer data storage up to date. The transfers will move through the following statuses in the happy path.

Incoming Payment Waiting ⇒ Processing ⇒ Funds Converted ⇒ Outgoing Payment Sent

Outgoing Payment Sent is the final state of the normal flow. If the payment fails, the following problematic flow will occur. An example would be if the recipient bank account doesn’t exist or the data is entered incorrectly and the payment is returned to Wise. The problematic state flow of transfers is:

Outgoing Payment Sent ⇒ Bounced Back ⇒ Processing ⇒ Cancelled ⇒ Funds Refunded

Most bounce backs occur within 2-3 business days, however this could happen up to several weeks after a transfer is sent.

Transfer state flow

NB: Transfers support rollback transitions, it allows return transfer back to one of previous states.

See below for the full list of transfer statuses and what they mean in the order of occurrence:

• incoming_payment_waiting – The transfer has been submitted and it’s waiting for the funds to arrive with Wise.

• incoming_payment_initiated - The funding has been initiated but the money has not yet arrived to Wise's account.

• processing – We have received the funds and are processing the transfer. Processing is a generic term and means we’re doing behind-the-scene activities before the money gets sent to the recipient, such as AML, compliance and fraud checks.

• funds_converted – All compliance checks have been completed for the transfer and funds have been converted from the source currency to the target currency.

• outgoing_payment_sent – Wise has paid out funds to the recipient. This is the final state of the transfer, assuming funds will not be returned. When a transfer has this state, it doesn’t mean the money has arrived in the recipient’s bank account, just that we have sent it from ours. Note: Payment systems in different countries operate in different speeds and frequency. For example, in the UK, the payment will reach the recipient bank account within few minutes after we send the outgoing payment. However, in the US it usually takes a day until funds are received.

• cancelled – This status is used when the transfer was never funded and therefore never processed. This is a final state of the transfer.

• funds_refunded – Transfer has been refunded. This is a final state of the transfer.

• bounced_back – Transfer has bounced back but has not been cancelled nor refunded yet. This is not a final transfer state, it means the transfer will either be delivered with delay or it will turn to funds_refunded state.

• charged_back - This status is used when we have problem to debit payer's account or payer requested money back. Chargeback can happen from any other state.

• unknown - This status is used when we don’t have enough information to move the transfer into a final state. We send out an email for more information. e.g. Sender account details to refund money back.

Keep in mind the transfer statuses in our API have different names than what you’ll see on our website or app. That’s because we use more consumer friendly language in the front end of our products. For example "Completed" on our website means outgoing_payment_sent in the API.

You should use the following descriptions in your website or app for the potential statuses we return:

Sandbox limitations

We don't send out email notifications to customers about payment status changes in sandbox.

We don't process payments in sandbox, which means that created payments remain in their first state. You can use Simulation endpoints to change transfer statuses in sandbox.

Get updated transfer delivery time

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’re working hard to make these estimates as accurate as possible.

Request

GET https://api.sandbox.transferwise.tech/v1/delivery-estimates/{transferId}

Response

You need to save the transfer id to track its status later.

Updating profiles

We require yearly updates on the personal or business profiles, which can be sent when a user accesses the Wise integration and you generate an access token. If any user data has changed within the previous year then the profile information at Wise must be updated, or you must let us know nothing has changed. Change of address, name change due to marriage, etc. are some common scenarios when this data may change. If easier, you can send this data with every transfer rather than yearly.

The way this needs to be implemented is the following:

Personal profiles

1. Open update window. Open the update window for profile updates.

2. Update personal profile - general data. Update the personal profile data.

3. Update personal profile - address data. Update address information of the personal profile.

4. Close update window. Close the update window for profile updates.

Business profiles

1. Open update window. Open the update window for profile updates.

2. Update business profile - general data. Update the business profile data.

3. Update business profile - address data. Update address information of the business profile.

4. Update business profile - directors data. Update directors information in the business user profile.

5. Update business profile - UBO data. Update ultimate business owners information in the business user profile.

6. Close update window. Close the update window for profile updates.

How to implement

There are several valid approaches on how to implement this from the bank side.

We recommend storing the most recent date that you updated the data for each personal/business profile and each time you get an access token for that user you can check against this date whether it's been more than one year since the profile was last updated. If it has been over a year, you should open the update window, perform the update profile steps and then close the update window.

Do keep in mind that we require the update window to be opened and closed even if there were no changes to the profiles. This will essentially let us know that nothing has changed for the profile and that the information is up to date.

Edge case handling

This section discusses some edge cases that you should test and handle before going live with your integration.

Email address considerations

Due to how getting access to user accounts works the Wise platform relies on user email addresses matching between the bank and ourselves. At the point the bank attempts to create a user we check and see if an account already exists for that email address, if so we return a 409 response and the client application forwards the user to login to Wise to do the OAuth grant flow.

This works well when the email addresses match in the first place and aren't updated on either side after the link is established. Of course, this is not always going to be the case so we must consider what happens in either eventuality.

Non-matching email addresses

If a user already has a Wise account and you create a user for the same person under a different email address they could end up with a duplicate user account under the second email address. Currently we monitor this behaviour for abuse but we are working on a more robust user creation solution to prevent this from occurring.

Email Change

It is possible to change a user’s email address both at Wise and potentially also on the bank platform. These flows can cause complications with the integration.

Email changed at Wise

If a user changes their email address, all tokens to the user account are revoked. In this case the bank will receive a 400 when attempting to generate an access_token and as such should follow the same process as described in the token expiry section above and start the sign up flow from the beginning.

In this case, if the user has changed their email address at Wise, it is possible the user will end up with a new Wise account using their old email address still held by the bank, or they might link their bank account to a different already existing Wise account under the old email address.

Email changed at the bank

In this case the tokens will remain valid for the Wise account, however, depending on how the user originally linked the account, different things can happen when/if that token expires.

If the bank created the account originally, they will be unable to generate tokens using the registration_code they have, as the endpoint requires the email address which will now no longer match. To mitigate this it is recommended that the bank store the email that was originally used for signup alongside the registration code and use this rather than the most up to date email address they store for the user.

If the token expires for a user not created by the bank and the user has a new email address at the bank then they can be pushed through the signup flow with this new email address and either have a new account created or link an existing against the new email, as described in token expiry.

The result of many of these flows is that the user may end up with more than one Wise account, which is undesirable. Currently we monitor this behaviour for abuse but we are working on a more robust user creation scenario to prevent this from occurring.

Email change mitigation

The result of these eventualities are that over time a user of the bank could be linked to more than one Wise account and so therefore you will need to be defensive when requesting older user data as the request may fail because we forbid one user to access other user's data. We recommend to keep a local copy of your user's transfer data and update it asynchronously such that older transfers remain accessible to the user in the case where it can no longer be accessed. You should also make sure to handle these failing calls gracefully and continue to process transfers that can be accessed over the API.

In the event a user is not happy at losing access to their older data or having two accounts is confusing then we can manually update the email addresses to match for the two accounts they want.

Going live checklist

1. Make your integration bulletproof

• Implement basic retry mechanism to handle potential failures or network interruptions
• Implement duplicate prevention mechanism to avoid duplicate payments. Verify that UUID is uniquely generated for each individual payment and its value is kept same in case of retrying.
• Implement basic logging to help out in debugging and problem solving, if needed.
• Check that you can handle all possible transfer states during polling of transfer info.
• Handle the potential issues described in edge case handling.
• Required data fields for recipients and transfers vary for different currencies. Please explore Recipient Accounts.Requirements Transfers.Requirements.
• 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.

2. Set up security for LIVE environment

• Make sure you have received and successfully decrypted Live API credentials, storing them securely.
• Ensure access tokens and refresh tokens are also stored securely and only exposed to authorized persons.
• Make sure your server has TLS version 1.2 or higher.
• Implement a mechanism to obtain new access token upon expiration.

3. Do some testing in LIVE

• Launch LIVE integration to a limited set of your customers and test all currency routes you will offer end-to-end.
• We recommend launching a limited set of currencies initially to limit the scope of potential issues, please seek guidance from the Wise team.
• Test successful flow and bounce back flow (where funds cannot be delivered).
• All set. Switch it on.

4. Signup for API status notifications

• You can always track our API status here.
• Also you can signup for API status notifications.

Global Currencies

Global Currencies is a Wise product that allows customers to send currencies to countries other than the one they are domestic to. For example, sending US dollars to a person or business in Hong Kong, rather than the USA.

It is quite common, especially for businesses, to operate in USD, GBP or EUR despite being based outside of the respective country of these currencies. In some countries, these bank accounts do not use the standard local account details format that a domestic account would, for example an account number and sort code in UK for GBP. Instead, these accounts are more likely to be addressed using an IBAN or an account number plus a BIC/SWIFT code.

The Wise Platform API supports this product in version two (v2) of the quotes API. The key difference this API provides against version one is the ability to update a quote with a recipient before a transfer is created, using the update quote endpoint. If you set the quote's targetAccount to be the ID of, for example, a USD recipient with an account number and SWIFT code (i.e. an account with "type": "swift_code") then the returned quote will be updated to represent the fact we will not be sending these funds domestically in the USA and as such charge different fees for the transfer. You should highlight this change in fees from the original quote to your user, after calling the update quote endpoint.

In addition to USD, EUR also has a swift_code recipient type, labelled "Outside Europe". This recipient type allows customers to send EUR to recipients with an account number and BIC/SWIFT code, however it is also possible to send EUR outside of the eurozone using the iban recipient type by entering a non-SEPA IBAN.

If you do not wish to offer these recipient types to your customers please discuss with your implementation team the best way to prevent them appearing.

Global currency warning message

In addition, if you offer this product, you must be sure to display a message to customers that there are potentially additional extra fees for this type of transfer. For example:

To send this transfer, we need to use the SWIFT network, which is more expensive and slower than normal transfers. There may also be extra fess taken from the money by intermediary banks. We cannot guarantee the exact amount that will be received by your recipient.

There are three cases you need to cover where we will use the SWIFT network and the message needs to be displayed:

1. A recipient of type swift_code, to any currency (currently only USD and EUR).
2. A GBP recipient of type iban where the IBAN does not start with GB
3. A EUR recipient of type iban where the IBAN does not start with one of the SEPA country codes (i.e. the transfer is to a non-SEPA country).

Example: Creating a global currency USD currency transfer

The process is as follows:

1. Create a quote for the currencies you wish to send between, e.g. GBP to USD.

2. Create a swift_code recipient for using the create account endpoint, based on the requirements set out in account requirements.

3. Update the quote created in step 1 with the ID of the recipient created in step two.

4. You will now see the payOut field of the quote to have updated to be of type SWIFT, and the paymentOptions array to have all options updated to also have a payOut of type SWIFT and different fees. The payOut field informs you which paymentOption to select, in this case you should show the user the fees to pay using the option that has a pay out of SWIFT. You should use the payIn option that has previously been agreed up, by default this is BANK_TRANSFER unless you are using a prefunded or bulk settlement model.

Versioning

The Wise Platform API is continuously evolving as we offer new features and coverage to our API customers. Here we explain how our API versioning is maintained so you know what to expect.

It's important to us that third-party integrations are not adversely affected by changes and we endeavor to uphold these standards as part of making convenience and transparency part of our company's mission. We are regularly reviewing our policies to make sure we're delivering the best possible API developer experience.

These policies apply to both our REST API and our webhooks (push-based event API).

Breaking changes

A breaking change refers to any change that would require a client to update their application in order to continue working with the API as originally intended. If an API field or resource is removed or renamed, then a breaking change has taken place. In this case we will increment the version of the affected API endpoints to prevent breaking existing customer integrations.

Under our current policy API endpoints are not all versioned together, if API endpoint compatibility has changed in the new version as a result of a breaking change we will provide clear instructions in our documentation on which API calls must be used together.

Continuity (non-breaking) changes

Wise reserves the right to make additive changes to our API without incrementing the version number or notifying clients. We may add new resources, fields, and relationships to an existing version of the API and these will not be considered breaking changes.

For example, if we add a new relationship to the Transfer resource for a “parent_order”, we will neither bump the API version nor notify our customers before releasing the update. We will, however, update our API documentation explaining the purpose of the changes.

As such, clients should design their applications to be flexible enough to not break when new fields are added to resources.

Removal of existing API endpoints

It is not standard policy for Wise to remove or disable API versions, and we will not take this action lightly. However in some cases it may be necessary; for example if the affected API does not meet new regulatory requirements and there is no alternative to making a breaking change and disabling an old API.

In the extremely rare case that this is necessary we will not remove API endpoints without notice to clients who may be affected, and formal warning of at least 6 months as long as this complies with our regulatory obligations.

Contact Us

Having issues while calling our API endpoints?
Check our API status at https://status.transferwise.com/ If you would like to receive status change notifications, feel free to signup here.

Have a technical question about API?
Send email to api@wise.com

Have a question about how Wise works?
Search Wise Help Centre. https://wise.com/help

Talk to the bank integrations team
Please get in touch with our team at banks@wise.com

Design Guide

Tips and advice for designing the international payments experience with the Wise API

We've created a Bank Integrations Design Guide to help you design a great experience for your customers that's similar to what we offer on our own website and apps. These guidelines go into detail to explain the user journey, the purpose of each screen, why we suggest you include a certain screen or feature and the customer interaction on each screen.

For technical documentation for building the integration, and more information about how our API works, see our Bank Integrations Technical Guide.

Getting started

Before getting started with designing your international payments experience using the Wise API, it's important to know that there are multiple ways to do it, depending on your users' needs. This documentation should be used as a reference to decide the best approach.

Things to consider before designing your integration

It's important to think about your users and Wise, there are three possible types:

1. Users that don't have a Wise account

These users will need to create a Wise account in order to use the international payments integration. You can create a Wise account for them behind the scenes automatically, without any user interaction.

2. Users that have a Wise account, but haven't connected it to your platform

These users will need to connect their existing Wise account to your platform. They will be prompted and guided through how to do it and be taken to Wise to log in and grant you access to allow the connection.

3. Users that have used Wise through your platform before**

These users formerly were of type one or two, but are now returning users. They are already set up to make international payments using Wise from your platform and do not have to go through the account creation or connecting flows again.

What the user sees

This is a step-by-step view of the different screens a user may see throughout their journey. We've detailed each step further down the page.

Breaking down the steps

These are examples of screens to include in your flow. Each example includes a design and information about the screen's purpose. We also included tips for what to do and not do when designing each screen.

Step 1: Customer chooses to send an international payment

This screen will be what your user first sees when they want to send a payment using your app or platform. The screen should have an option for them to make an international payment. It should be accessible from your app's payment or account screen.

Step 2: Selects a currency, enters an amount to send, and gets a quote for the exchange rate and cost

After the customer chooses to make an international payment, they will first see a screen that lets them choose their currency. Once they make that choice, they will be taken to a screen that displays what we call the calculator.

The calculator allows a user to enter an amount they want to send in their currency, which reveals a quote from our API — the quote includes the amount the recipient will receive in their currency based on the live mid-market exchange rate, the included sending fee and the estimated delivery time.

Additionally, the calculator should allow the user to type in a specific amount for the recipient to receive, the Wise quote API will return the calculation of the exact amount to send.

The screen also is an easy way for a user to switch between different currencies to see different exchange rates and costs.

Entering an amount and getting a quote

Selecting a currency

Step 3: Creates or connects a Wise account

Jump to Step 5 if the user already connected their Wise account

This screen is to check to see if the user has an existing Wise account. You should use the email address stored on the user's bank profile to determine if they have an existing Wise account using an endpoint provided by our API.

There are two screens that need to be designed — one for customers that do have a Wise account, and one those that do not.

If they don't have a Wise account with the same email as their bank account

If they do have a Wise account with the same email as their bank account

This will be what the user sees on our platform when they choose to connect their accounts.

Step 4: Selects currency, enters amount, and gets a final quote

This step looks identical to step 2, except now the user is logged in to Wise. All details previously entered in step 2 will be pulled through from the logged out to the logged in state. The screen's main purpose is to confirm with the user what they entered in step 2.

Step 5: Selects or creates a recipient

The data for this screen comes from the Wise API. It will be available once the customer creates or signs in to their Wise account. It should only show recipients for the currency that the user has selected in the previous step. The API supports this filtering.

Selecting a recipient

Adding a recipient

Step 6: Enters more details about the payment, if needed

Sometimes we need extra information about the transfer from your customer. This form is built dynamically based on how Wise defines the information that you need. Your system discovers this using the transfer-requirements feature of the API. This screen often isn't needed, but should be dynamically added to the flow when it is.

Step 7: Confirms payment details

This is the screen that lets the user review and confirm their transfer details, and press send. It should always include the amount being sent and to whom they are sending it to.

Step 8: The payment is sent

Additional screens

Activity and payment details

Once the transfer has been made, the user should be able to see confirmation. The user should also be able to easily access and review the details of the transfer.

Activity

Payment details

Get By Id

Example Request:

curl -X GET https://api.sandbox.transferwise.tech/v1/users/{userId} \
     -H "Authorization: Bearer <your api token>" 

Example Response:

{
  "id": 101,
  "name": "Example Person",
  "email": "person@example.com",
  "active": true,
  "details": {
    "firstName": "Example",
    "lastName": "Person",
    "phoneNumber": "+37111111111",
    "occupation": "",
    "address": {
      "city": "Tallinn",
      "countryCode": "EE",
      "postCode": "11111",
      "state": "",
      "firstLine": "Road 123"
    },
    "dateOfBirth": "1977-01-01",
    "avatar": "https://lh6.googleusercontent.com/photo.jpg",
    "primaryAddress": 111
  }
}

Get authenticated user details by user id. Response includes also personal user profile info.

Request

GET https://api.sandbox.transferwise.tech/v1/users/{userId}

Response

Get the currently logged in user

Example Request:

curl -X GET https://api.sandbox.transferwise.tech/v1/me \
     -H "Authorization: Bearer <your api token>" 

Example Response:

{
  "id": 101,
  "name": "Example Person",
  "email": "person@example.com",
  "active": true,
  "details": {
    "firstName": "Example",
    "lastName": "Person",
    "phoneNumber": "+37111111111",
    "occupation": "",
    "address": {
      "city": "Tallinn",
      "countryCode": "EE",
      "postCode": "11111",
      "state": "",
      "firstLine": "Road 123"
    },
    "dateOfBirth": "1977-01-01",
    "avatar": "https://lh6.googleusercontent.com/photo.jpg",
    "primaryAddress": 111
  }
}

Get authenticated user details for the user's token submitted in the Authorization header. Response includes also personal user profile info.

Request

GET https://api.sandbox.transferwise.tech/v1/me

Response

Sign Up with Registration Code

1. Example Request: Get Client Credentials Token

curl -X "POST" "https://api.sandbox.transferwise.tech/oauth/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -H "Authorization: Basic <base64 encoded clientId:clientSecret>" \
     --data-urlencode "grant_type=client_credentials"

1. Example Response: Get Client Credentials Token

  {
    "access_token":"ba8k1234-00f2-475a-60d8-6g45377b4062",
    "token_type":"bearer",
    "expires_in": 43199,
    "scope":"transfers"
  }

2. Example Request: Create User

curl -X POST https://api.sandbox.transferwise.tech/v2/users \
     -H "Authorization: Bearer <your client credentials token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "email": <user email>,
          "registrationCode": <registration code>,
          "sendAuthorizationCodeAsEmail":false,
          "language":"PT"
        }'

2. Example Response: Create User (Success (200) user created successfully)

      {
        "id": 12345,
        "name": null,
        "email": "new.user@domain.com",
        "active": true,
        "details": null
      }

2. Example Response: Create User (Failure (409): User already exists)

      {
        "errors": [
          {
            "code": "NOT_UNIQUE",
            "message": "You’re already a member. Please login",
            "path": "email",
            "arguments": [
              "email",
              "class com.transferwise.fx.api.ApiRegisterCommand",
              "existing.user@domain.com"
            ]
          }
        ]
      }

3. Example Request: Get User Tokens

curl --location --request POST 'https://api.sandbox.transferwise.tech/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--user '[your-api-client-id]:[your-api-client-secret]' \
--data-urlencode 'grant_type=registration_code' \
--data-urlencode 'client_id=[your-api-client-id]' \
--data-urlencode 'email=<user email>' \
--data-urlencode 'registration_code=<registration code used to create user>'

3. Example Response: Get User Tokens (Success: 200)

    {
      "access_token": "01234567-89ab-cdef-0123-456789abcdef",
      "token_type": "bearer",
      "refresh_token": "01234567-89ab-cdef-0123-456789abcdef",
      "expires_in": 43199,
      "scope": "transfers"
    }

3. Example Response: Get User Tokens (Failure: 400 - User reclaimed the account or invalid registration code used)

    {
      "error": "invalid_grant",
      "error_description": "Invalid user credentials."
    }

These endpoints enable onboarding new users to Wise via backend API calls only.

To get authorization from existing Wise users, you need to redirect them to our authorization webpage or have the user manually input and authorization code.

There are 3 steps you need to go through:

1) Get Client Credentials Token

Obtain your application level access_token based on your API client credentials.

Request

POST https://api.sandbox.transferwise.tech/oauth/token

Use Basic Authentication with your client id and client secret as the username/password basic auth.

NOTE: The body of the request must be sent as x-www-form-urlencoded.

Response

2) Create User

Call this API to create the user on Wise. We use the email address as unique identifier for users.

If email is new (there is no active user already) then new user will be created.

When you are submitting an email which already exists amongst our users then you will get HTTP 409 response. If the user already exists, then you need to revert to the linking an existing Wise account flow, choosing one of the two options to link the account - a redirect to our website or en email based flow with the user manually typing in the authorization code.

Request

POST https://api.sandbox.transferwise.tech/v2/users/

Use access_token obtained in first step as authentication header.

Response

3) Get User Tokens

You can now use registration code to obtain user access token and refresh token.

This step can be repeated as long as user does not "reclaim" their Wise account, by coming to Wise and securely setting their own password on the account in order to access it directly.

If user has reclaimed the account, which can be detected by this API call failing with an authentication error code 400 then revert to the linking an existing Wise account flow should be used instead.

Refresh user access token works same way for this flow as well.

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.

Response

Check User Exists

Request

POST https://api.sandbox.transferwise.tech/v2/users/exists

Note that this uses a client-credentials-token and not a user access_token for authentication.

Response

Example Request

curl -X POST https://api.sandbox.transferwise.tech/v2/users/exists \
     -H "Authorization: Bearer <your client credentials token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "email": <user email>,
        }'

Example Response

      {
        "exists": true
      }

Create (Personal)

Example Request:

curl -X POST https://api.sandbox.transferwise.tech/v1/profiles \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "type": "personal",
          "details": {
            "firstName": "Oliver",
            "lastName": "Wilson",
            "dateOfBirth": "1977-07-01",
            "phoneNumber": "+3725064992",
            "firstNameInKana": null,
            "lastNameInKana": null
           }
        }'

Example Response (Personal):

{
  "id": <your personal profile id>,
  "type": "personal",
  "details": {
    "firstName": "Oliver",
    "lastName": "Wilson",
    "dateOfBirth": "1977-07-01",
    "phoneNumber": "+3725064992",
    "avatar": "",
    "occupation": "",
    "occupations": null,
    "primaryAddress": null,
    "firstNameInKana": null,
    "lastNameInKana": null
  }
}

Create personal user profile. One person cannot have multiple active duplicate user profiles, creating multiple profiles with the same details will fail.

Request

POST https://api.sandbox.transferwise.tech/v1/profiles

If a customer you are creating a profile for has first or last names that exceed 30 characters (e.g. they have many middle names) then you should truncate the names at length 30 characters and submit that value.

Response

Create (Business)

Example Request:

curl -X POST https://api.sandbox.transferwise.tech/v1/profiles \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "type": "business",
          "details": {
            "name": "ABC Logistics Ltd",
            "registrationNumber": "12144939",
            "acn": null,
            "abn": null,
            "arbn": null,
            "companyType": "LIMITED",
            "companyRole": "OWNER",
            "webpage": "https://abc-logistics.com",
            "businessCategory":"CONSULTING_IT_BUSINESS_SERVICES",
            "businessSubCategory":"DESIGN"
          }
        }'

Example Response (Business):

{
  "id": <your business profile id>,
  "type": "business",
  "details": {
    "name": "ABC Logistics Ltd",
    "registrationNumber": "12144939",
    "acn": null,
    "abn": null,
    "arbn": null,
    "companyType": "LIMITED",
    "companyRole": "OWNER",
    "descriptionOfBusiness": "Information and communication",
    "webpage": "https://abc-logistics.com",
    "primaryAddress": 123456, //ID of placeholder
    "businessCategory": "CONSULTING_IT_BUSINESS_SERVICES",
    "businessSubCategory": "DESIGN"
   }
}

Create business user profile. You must always create a personal profile first, business profiles cannot be created without personal profile.

Request (Business)

POST https://api.sandbox.transferwise.tech/v1/profiles

Business Category

Ensure when submitting a business profile that you submit a category and associated sub-category from the list below. You should map from the information you have about the business to one of our categories and sub-categories. If this is problematic please get in touch with us to discuss alternate solutions.

The categories and their sub-categories are as follows:

• CHARITY_NON_PROFIT
• CHARITY_ALL_ACTIVITIES
• CONSULTING_IT_BUSINESS_SERVICES
• ADVERTISING_AND_MARKETING
• ARCHITECTURE
• COMPANY_ESTABLISHMENT_FORMATION_SERVICES
• DESIGN
• FINANCIAL_CONSULTING_ACCOUNTING_TAXATION_AUDITING
• IT_DEVELOPMENT
• IT_HOSTING_SERVICES
• IT_CONSULTING_AND_SERVICES
• LEGAL_SERVICES
• MANAGEMENT_CONSULTING
• SCIENTIFIC_AND_TECHNICAL_CONSULTING
• SOFTWARE_AS_A_SERVICE
• TRANSLATION_AND_LANGUAGE_SERVICES
• CONSULTING_OTHER
• SERVICES_OTHER
• FREELANCE_PLATFORMS
• RECRUITMENT_SERVICES
• MAINTENANCE_SERVICES
• FREELANCE_PLATFORMS
• DESIGN_MARKETING_COMMUNICATIONS
• ADVERTISING_AND_MARKETING
• ARCHITECTURE
• AUDIO_AND_VIDEO
• DESIGN
• PHOTOGRAPHY
• PRINT_AND_ONLINE_MEDIA
• TELECOMMUNICATIONS_SERVICES
• TRANSLATION_AND_LANGUAGE_SERVICES
• MEDIA_COMMUNICATION_ENTERTAINMENT
• ADULT_CONTENT
• AUDIO_AND_VIDEO
• FINE_ARTS
• ARTS_OTHER
• EVENTS_AND_ENTERTAINMENT
• GAMBLING_BETTING_AND_ONLINE_GAMING
• NEWSPAPERS_MAGAZINES_AND_BOOKS
• PERFORMING_ARTS
• PHOTOGRAPHY
• TELECOMMUNICATIONS_SERVICES
• VIDEO_GAMING
• EDUCATION_LEARNING
• SCHOOLS_AND_UNIVERSITIES,
• TEACHING_AND_TUTORING
• ONLINE_LEARNING
• FINANCIAL_SERVICES_PRODUCTS_HOLDING_COMPANIES
• CROWDFUNDING
• CRYPTOCURRENCY_FINANCIAL_SERVICES
• FINANCIAL_CONSULTING_ACCOUNTING_TAXATION_AUDITING
• HOLDING_COMPANIES
• INSURANCE
• INVESTMENTS
• MONEY_SERVICE_BUSINESSES
• FINANCIAL_SERVICES_OTHER
• FOOD_BEVERAGES_TOBACCO
• ALCOHOL
• FOOD_MANUFACTURING_RETAIL
• RESTAURANTS_AND_CATERING
• SOFT_DRINKS
• TOBACCO
• VITAMINS_AND_DIETARY_SUPPLEMENTS
• HEALTH_PHARMACEUTICALS_PERSONAL_CARE
• HEALTH_AND_BEAUTY_PRODUCTS_AND_SERVICES,
• DENTAL_SERVICES,
• DOCTORS_AND_MEDICAL_SERVICES,
• ELDERLY_OR_OTHER_CARE_HOME,
• FITNESS_SPORTS_SERVICES,
• MEDICAL_EQUIPMENT,
• NURSING_AND_OTHER_CARE_SERVICES,
• PHARMACEUTICALS,
• PHARMACY,
• VITAMINS_AND_DIETARY_SUPPLEMENTS
• PUBLIC_GOVERNMENT_SERVICES
• PUBLIC_ALL_SERVICES
• MAINTENANCE_SERVICES
• GOVERNMENT_SERVICES
• TELECOMMUNICATIONS_SERVICES
• UTILITY_SERVICES
• REAL_ESTATE_CONSTRUCTION
• ARCHITECTURE
• CONSTRUCTION
• REAL_ESTATE_DEVELOPMENT
• REAL_ESTATE_SALE_PURCHASE_AND_MANAGEMENT
• RETAIL_WHOLESALE_MANUFACTURING
• AGRICULTURE_SEEDS_PLANTS
• FINE_ARTS
• ARTS_OTHER
• AUTOMOTIVE_SALES_SPARE_PARTS_TRADE
• AUTOMOTIVE_MANUFACTURING
• CHEMICALS
• CLOTHING
• ELECTRICAL_PRODUCTS
• FIREARMS_WEAPONS_AND_MILITARY_GOODS_SERVICES
• HOME_ACCESSORIES_FURNITURE
• FINE_JEWELLERY_WATCHES
• FASHION_JEWELLERY
• HEALTH_AND_BEAUTY_PRODUCTS_AND_SERVICES
• LEGAL_HIGHS_AND_RELATED_ACCESSORIES
• MACHINERY
• PETS
• PRECIOUS_STONES_DIAMONDS_AND_METALS
• SPORTING_EQUIPMENT
• MANUFACTURING_OTHER
• RETAIL_WHOLESALE_MARKETPLACE_AUCTION
• RETAIL_WHOLESALE_OTHER
• TOYS_AND_GAMES
• TRAVEL_TRANSPORT_TOUR_AGENCIES
• ACCOMMODATION_HOTELS
• PASSENGER_TRANSPORT
• FREIGHT_TRANSPORT
• RIDESHARING_TRANSPORT_SHARING_SERVICES
• TRANSPORT
• TRAVEL_AGENCIES
• TOUR_OPERATORS
• TRAVEL_OR_TOUR_ACTIVITIES_OTHER
• OTHER
• OTHER_NOT_LISTED_ABOVE

Response (Business)

Update

Example Request:

curl -X PUT https://api.sandbox.transferwise.tech/v1/profiles \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{
          "id": <your personal profile id>
          "type": "personal",
          "details": {
            "firstName": "Oliver",
            "lastName": "Wilson",
            "dateOfBirth": "1977-07-01",
            "phoneNumber": "+3725064992",
            "firstNameInKana": null,
            "lastNameInKana": null
           }
        }'

Example Response:

{
  "id": <your personal profile id>,
  "type": "personal",
  "details": {
    "firstName": "Oliver",
    "lastName": "Wilson",
    "dateOfBirth": "1977-07-01",
    "phoneNumber": "+3725064992",
    "avatar": "",
    "occupation": "",
    "occupations": null,
    "primaryAddress": null,
    "firstNameInKana": null,
    "lastNameInKana": null
  }
}

Update user profile information.

If user profile has been verified then there are restrictions on what information is allowed to change, where permitted, use the update window functionality to submit updated data.

Request

PUT https://api.sandbox.transferwise.tech/v1/profiles

Request and response is same as described in Create (Personal) and Create (Business)

Get By Id

Example Request:

curl -X GET https://api.sandbox.transferwise.tech/v1/profiles/{profileId} \
     -H "Authorization: Bearer <your api token>" 

Example Response:

{
  "id": <your personal profile id>,
  "type": "personal",
  "details": {
    "firstName": "Oliver",
    "lastName": "Wilson",
    "dateOfBirth": "1977-07-01",
    "phoneNumber": "+3725064992",
    "avatar": "",
    "occupation": "",
    "primaryAddress": null,
    "firstNameInKana": null,
    "lastNameInKana": null
  }
}

Get profile info by id.

Request

GET https://api.sandbox.transferwise.tech/v1/profiles/{profileId}

List

GET /v2/profiles

Example Request:

curl -X GET https://api.sandbox.transferwise.tech/v2/profiles \
     -H "Authorization: Bearer <your api token>"

Example Response:

[
  {
    "type": "PERSONAL",
    "id": 16155137,
    "userId": 5682283,
    "address": {
      "addressFirstLine": ".......",
      "city": "London",
      "countryIso2Code": "GB",
      "countryIso3Code": "gbr",
      "postCode": "ABC123",
      "stateCode": null
    },
    "email": "",
    "createdAt": "2021-03-25T15:18:35.000Z",
    "updatedAt": "2021-03-25T15:18:35.000Z",
    "obfuscated": false,
    "currentState": "VISIBLE",
    "firstName": "Oliver",
    "lastName": "Wilson",
    "dateOfBirth": "1967-04-03",
    "phoneNumber": "+442038087139",
    "secondaryAddresses": [],
    "fullName": "Oliver Wilson"
  },
  {
    "type": "BUSINESS",
    "id": 16155138,
    "userId": 5682283,
    "address": {
      "addressFirstLine": ".......",
      "city": "London",
      "countryIso2Code": "GB",
      "countryIso3Code": "gbr",
      "postCode": "ABC123",
      "stateCode": null
    },
    "email": "",
    "createdAt": "2021-03-25T15:18:38.000Z",
    "updatedAt": "2021-03-25T15:18:38.000Z",
    "obfuscated": false,
    "currentState": "VISIBLE",
    "businessName": "ABC Logistics Ltd",
    "registrationNumber": "07209813",
    "descriptionOfBusiness": "IT_SERVICES",
    "companyType": "LIMITED",
    "companyRole": "OWNER",
    "operationalAddresses": [],
    "fullName": "ABC Logistics Ltd"
  }
]

List of all profiles belonging to user.

Please note that there might be more than one business profile returned in the response.

Request

GET https://api.sandbox.transferwise.tech/v2/profiles

GET /v1/profiles (deprecated)

Example Request:

curl -X GET https://api.sandbox.transferwise.tech/v1/profiles \
     -H "Authorization: Bearer <your api token>"

Example Response:

[
    {
      "id": <your personal profile id>,
      "type": "personal",
      "details": {
        "firstName": "Oliver",
        "lastName": "Wilson",
        "dateOfBirth": "1977-07-01",
        "phoneNumber": "+3725064992",
        "avatar": "",
        "occupation": "",
        "occupations": null,
        "primaryAddress": null,
        "firstNameInKana": null,
        "lastNameInKana": null
      }
    },
    {
      "id": <your business profile id>,
      "type": "business",
      "details": {
        "name": "ABC Logistics Ltd",
        "registrationNumber": "12144939",
        "acn": null,
        "abn": null,
        "arbn": null,
        "companyType": "LIMITED",
        "companyRole": "OWNER",
        "descriptionOfBusiness": "CHARITY_AND_NOT_FOR_PROFIT",
        "webpage": "https://abc-logistics.com",
        "primaryAddress": null,
        "businessCategory": "CHARITY_AND_NOT_FOR_PROFIT",
        "businessSubCategory": "CHARITY_ALL_ACTIVITIES"
       }
    }
]

List of all profiles belonging to user.

Request

GET https://api.sandbox.transferwise.tech/v1/profiles

Create Identification Document

Example Request:

curl -X POST https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/verification-documents \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
            "firstName": "Oliver",
            "lastName": "Wilson",
            "type": "IDENTITY_CARD",
            "uniqueIdentifier": "AA299822313",
            "issueDate": "2017-12-31",
            "issuerCountry": "EE",
            "issuerState": "",
            "expiryDate": "2027-12-31"
        }'

Example Response:

{
  "errorMessage": null,
  "success": true
}

Add identification document details to user profile. Applicable to personal profiles (not business) only.
Returns empty result if successful.

When sending a social security number (SSN) only type and uniqueIdentifier (only 9 digits no letters or symbols) are required.

Request

POST https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/verification-documents

Get business directors

Example Request:

curl -X GET https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/directors \
     -H "Authorization: Bearer <your api token>"

Example Response:

[
  {
    "id": 10,
    "firstName": "John",
    "lastName": "Doe",
    "dateOfBirth": "1982-05-20",
    "countryOfResidenceIso3Code": "usa"
  },
  {
    "id": 11,
    "firstName": "Jane",
    "lastName": "Doe",
    "dateOfBirth": "1981-12-07",
    "countryOfResidenceIso3Code": "usa"
  }
]

Returns the list of all directors associated with the business profile.

Request (Business)

GET https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/directors

Add business directors

Example Request:

curl -X POST https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/directors \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '[
             {
                 "firstName": "John",
                 "lastName": "Doe",
                 "dateOfBirth": "1982-05-20",
                 "countryOfResidenceIso3Code": "usa"
             },
             {
                 "firstName": "Jane",
                 "lastName": "Doe",
                 "dateOfBirth": "1981-12-07",
                 "countryOfResidenceIso3Code": "usa"
             }
        ]'

Example Response:

[
    {
        "id": 10,
        "firstName": "John",
        "lastName": "Doe",
        "dateOfBirth": "1982-05-20",
        "countryOfResidenceIso3Code": "usa"
    },
    {
        "id": 11,
        "firstName": "Jane",
        "lastName": "Doe",
        "dateOfBirth": "1981-12-07",
        "countryOfResidenceIso3Code": "usa"
    },
    {
        "id": 7,
        "firstName": "Oliver",
        "lastName": "Wilson",
        "dateOfBirth": "2017-12-31",
        "countryOfResidenceIso3Code": "gbr"
    }
]

Adds new directors to the business profile. Returns the list of all directors associated with the business profile.

Request (Business)

POST https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/directors

Update business directors

Example Request:

curl -X PUT https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/directors \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '[
             {
                 "firstName": "John",
                 "lastName": "Doe",
                 "dateOfBirth": "1982-05-20",
                 "countryOfResidenceIso3Code": "usa"
             },
             {
                 "firstName": "Jane",
                 "lastName": "Doe",
                 "dateOfBirth": "1981-12-07",
                 "countryOfResidenceIso3Code": "usa"
             }
        ]'

Example Response:

[
    {
        "id": 14,
        "firstName": "John",
        "lastName": "Doe",
        "dateOfBirth": "1982-05-20",
        "countryOfResidenceIso3Code": "usa"
    },
    {
        "id": 15,
        "firstName": "Jane",
        "lastName": "Doe",
        "dateOfBirth": "1981-12-07",
        "countryOfResidenceIso3Code": "usa"
    }
]

Overrides directors in the business profile. Returns the list of all directors associated with the business profile.

Request (Business)

PUT https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/directors

Get business ultimate beneficial owners

Example Request:

curl -X GET https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/ubos \
     -H "Authorization: Bearer <your api token>" 

Example Response:

[
    {
        "id": "013ab1c2688d0185b582ee7e0bcb28b2",
        "name": "John Doe",
        "dateOfBirth": "1982-05-20",
        "countryOfResidenceIso3Code": "usa",
        "addressFirstLine": "123 Fake St",
        "postCode": "FK 12345",
        "ownershipPercentage": 30
    },
    {
        "id": "912ce3f31c8b3a10572137e78417caa3",
        "name": "Jane Doe",
        "dateOfBirth": "1981-12-07",
        "countryOfResidenceIso3Code": "usa",
        "addressFirstLine": "125 Fake St",
        "postCode": "FK 12545",
        "ownershipPercentage": 70
    }
]

Returns the list of all ultimate beneficial owners associated with the business profile.

Request (Business)

GET https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/ubos

Add business ultimate beneficial owners

Example Request:

curl -X POST https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/ubos \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '[
             {
                 "name": "John Doe",
                 "dateOfBirth": "1982-05-20",
                 "countryOfResidenceIso3Code": "usa",
                 "addressFirstLine": "123 Fake St",
                 "postCode": "FK 12345",
                 "ownershipPercentage": 30
             },
             {
                 "name": "Jane Doe",
                 "dateOfBirth": "1981-12-07",
                 "countryOfResidenceIso3Code": "usa",
                 "addressFirstLine": "125 Fake St",
                 "postCode": "FK 12545",
                 "ownershipPercentage": 40
             }
        ]'

Example Response:

[
     {
         "id": "f3e71aa1c97448d0b1eb5bdc0bacdcce",
         "name": "John Doe",
         "dateOfBirth": "1982-05-20",
         "countryOfResidenceIso3Code": "usa",
         "addressFirstLine": "123 Fake St",
         "postCode": "FK 12345",
         "ownershipPercentage": 30
     },
     {
         "id": "c6008d58a1664413b4c4dcacec1377f4",
         "name": "Jane Doe",
         "dateOfBirth": "1981-12-07",
         "countryOfResidenceIso3Code": "usa",
         "addressFirstLine": "125 Fake St",
         "postCode": "FK 12545",
         "ownershipPercentage": 40
     },
     {
         "id": "63bbdd1cf5ec4dd587597e74dbace376",
         "name": "Oliver Wilson",
         "dateOfBirth": "2017-12-31",
         "countryOfResidenceIso3Code": "gbr",
         "addressFirstLine": "222 Fake St",
         "postCode": "FK 22222",
         "ownershipPercentage": 30
     }
]

Adds new ultimate beneficial owners to the business profile. Returns the list of all ultimate beneficial owners associated with the business profile.

Note that in some cases, we do not require the ownershipPercentage. In these cases, null should be passed as the value.

Request (Business)

POST https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/ubos

Update business ultimate beneficial owners

Example Request:

curl -X PUT https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/ubos \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '[
             {
                 "name": "John Doe",
                 "dateOfBirth": "1982-05-20",
                 "countryOfResidenceIso3Code": "usa",
                 "addressFirstLine": "123 Fake St",
                 "postCode": "FK 12345",
                 "ownershipPercentage": 30
             },
             {
                 "name": "Jane Doe",
                 "dateOfBirth": "1981-12-07",
                 "countryOfResidenceIso3Code": "usa",
                 "addressFirstLine": "125 Fake St",
                 "postCode": "FK 12545",
                 "ownershipPercentage": 70
             }
        ]'

Example Response:

[
     {
         "id": "ff01cf3f206b40c090a14a1e51163e9e",
         "name": "John Doe",
         "dateOfBirth": "1982-05-20",
         "countryOfResidenceIso3Code": "usa",
         "addressFirstLine": "123 Fake St",
         "postCode": "FK 12545",
         "ownershipPercentage": 30
     },
     {
         "id": "c36b687d28ad44ad8c3864411f5f2612",
         "name": "Jane Doe",
         "dateOfBirth": "1981-12-07",
         "countryOfResidenceIso3Code": "usa",
         "addressFirstLine": "125 Fake St",
         "postCode": "FK 12545",
         "ownershipPercentage": 70
     }
]

Overrides ultimate beneficial owners in the business profile. Returns the list of all ultimate beneficial owners associated with the business profile.

Request (Business)

PUT https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/ubos

Remove Trusted Verification from Profile

Example Request:

curl -X DELETE https://api.sandbox.transferwise.tech/v3/profiles/{profileId}/trusted-verification \
     -H "Authorization: Bearer {client-credentials-token}" 

Example Response (204):

No Content

This endpoint allows partners to remove the verification that was given to the profile through them creating the profile. This does not delete a profile nor archive it, it simply removes the trusted verification from that partner.

Note that this uses a client-credentials-token and not a user access_token for authentication.

Open update window

Example Request:

curl -X POST https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/update-window \
     -H "Authorization: Bearer <your api token>" 

Example Response:

Opens the update window for updating the profile information: details, addresses, directors, owners, others.

Request

POST https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/update-window

Close update window

Example Request:

curl -X DELETE https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/update-window \
     -H "Authorization: Bearer <your api token>" 

Example Response:

Deletes the update window for updating the profile.

Request

DELETE https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/update-window

Profile extensions

Example Request:

curl -X GET https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/extension-requirements \
     -H "Authorization: Bearer <your api token>"

Example Response:

[
  {
    "type": "profile-extensions-requirements",
    "usageInfo": null,
    "fields": [
      {
        "name": "Tell us what you're using TransferWise for",
        "group": [
          {
            "key": "accountPurpose",
            "name": "Account Purpose",
            "type": "select",
            "refreshRequirementsOnChange": false,
            "required": true,
            "displayFormat": null,
            "example": null,
            "minLength": null,
            "maxLength": null,
            "validationRegexp": null,
            "validationAsync": null,
            "valuesAllowed": [
              {
                "key": "CONTRIBUTING_TO_PERSONAL_SAVINGS",
                "name": "Contributing to personal savings"
              },
              {
                "key": "GENERAL_MONTHLY_LIVING_EXPENSES",
                "name": "General monthly living expenses"
              },
              {
                "key": "INVESTING_IN_FUNDS_STOCKS_BONDS_OPTIONS_FUTURES_OR_OTHER",
                "name": "Investing in funds stocks bonds options futures or other"
              },
              {
                "key": "PAYING_FOR_GOODS_OR_SERVICES_ABROAD",
                "name": "Paying for goods or services abroad"
              },
              {
                "key": "PAYING_RENT_MORTGAGE_BANK_LOAN_INSURANCE_CREDIT",
                "name": "Paying rent mortgage bank loan insurance credit"
              },
              {
                "key": "PAYING_RENT_UTILITIES_OR_PROPERTY_CHARGES",
                "name": "Paying rent utilities or property charges"
              },
              {
                "key": "RECEIVE_SALARY_IN_DIFFERENT_CURRENCY",
                "name": "Receive salary in different currency"
              },
              {
                "key": "RECEIVE_PENSION_IN_DIFFERENT_CURRENCY",
                "name": "Receive pension in different currency"
              },
              {
                "key": "SENDING_MONEY_REGULARLY_TO_FAMILY",
                "name": "Sending money regularly to family"
              },
              {
                "key": "SENDING_MONEY_TO_MY_OWN_ACCOUNT_TO_BENEFIT_FROM_EXHCANGE_RATE",
                "name": "Sending money to my own account to benefit from exchange rate"
              }
            ]
          }
        ]
      }
    ]
  }
]

After having a profile created, in some situations we can need more specific information about it. In order to know which fields are required for a given profile, and to send the information over, we expose a few endpoints:

GET https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/extension-requirements
POST https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/extension-requirements

and

POST https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/extensions
GET https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/extensions

The GET and POST profile extension-requirements endpoints help you to figure out which fields are required to create a valid profile for different regions. You can use this data to build a dynamic user interface on top of these endpoints.

The POST and GET profile extensions endpoints allow you to send the extra profile information and retrieve it, respectively.

This format for dynamic forms is the same as the one used for recipient creation. See Recipient.Requirements and Using account requirements

This is a step-by-step guide on how these endpoints work.

Using profile extension requirements

1. First create a profile. See User Profiles Create (Personal) and User Profiles Create (Business)

2. Call GET /v1/profiles/{profileId}/extension-requirements to get the list of fields you need to fill with values in the "details" section for adding information that will make a profile valid.

3. Some fields require multiple levels of fields in the details request. This should be handled by the client based on the refreshRequirementsOnChange field. A top level field can have 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 extension-requirements endpoint. You will be returned a response similar the previously returned data from GET extension-requirements but with additional fields.

4. Once you have built your full profile extension details object you can add it to add information to the profile.

This is a valid request to add information to a profile:

POST v1/profiles/{profileId}/extensions

{
    "details": {
        "accountPurpose": "SENDING_MONEY_REGULARLY_TO_FAMILY"
    }
}

Building an user interface

When requesting the form data from the extension-requirements endpoint, the response defines different types of extensions that can be added. Each extension 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:

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 will also be done when a completed profile extension is submitted to POST /v1/profiles/{profileId}/extensions.

Response

Create/Update

Example Request:

curl -X POST https://api.sandbox.transferwise.tech/v1/addresses \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "details": {
            "country": "EE",
            "firstLine": "Narva mnt 5-1",
            "postCode": "10113",
            "city": "Tallinn",
            "occupations": [
              {
                "code": "Software Engineer",
                "format": "FREE_FORM"
              }
            ]
          }
        }'

Example Response:

{
  "id": 236532,
  "profile": <your profile id>,
  "details": {
    "country": "EE",
    "firstLine": "Narva mnt 5-1",
    "postCode": "10113",
    "city": "Tallinn",
    "state": "",
    "occupation": null,
    "occupations": [
      {
        "code": "Software Engnieer",
        "format": "FREE_FORM"
      }
    ]
  }
}

Adds address info to user profile. List of required fields are different for different countries.

State field is required for US, CA, BR and AU addresses.

Occupations is required for CA, IN, JP and within the US for the states AZ and NM. If you serve any of these jurisdictions we recommend submitting occupation for all customers for simplicity, however if this is an issue we can discuss alternative solutions.

Request

POST https://api.sandbox.transferwise.tech/v1/addresses

Response

Get By Id

Example Request:

curl -X GET https://api.sandbox.transferwise.tech/v1/addresses/{addressId} \
     -H "Authorization: Bearer <your api token>"

Example Response:

{
  "id": 236532,
  "profile": <your profile id>,
  "details": {
    "country": "EE",
    "firstLine": "Narva mnt 5-1",
    "postCode": "10113",
    "city": "Tallinn",
    "state": "",
    "occupation": null,
    "occupations": null
  }
}

Get address info by id.

Request

GET https://api.sandbox.transferwise.tech/v1/addresses/{addressId}

List

Example Request:

curl -X GET https://api.sandbox.transferwise.tech/v1/addresses?profile={profileId} \
     -H "Authorization: Bearer <your api token>" 

Example Response:

[
    {
        "id": 7099091,
        "profile": <your profile id>,
        "details": {
            "country": "EE",
            "firstLine": "Veerenni 29",
            "postCode": "12991",
            "city": "Tallinn",
            "state": null,
            "occupation": null,
            "occupations": null
        }
    }
]

List of addresses belonging to user profile.

Request

GET https://api.sandbox.transferwise.tech/v1/addresses?profile={profileId}

Requirements

Example Request:

curl -X GET https://api.sandbox.transferwise.tech/v1/address-requirements \
     -H "Authorization: Bearer <your api token>"

Example Response:

[
  {
    "type": "address",
    "fields": [
      {
        "name": "Country",
        "group": [
          {
            "key": "country",
            "type": "select",
            "refreshRequirementsOnChange": true,
            "required": true,
            "displayFormat": null,
            "example": "Germany",
            "minLength": null,
            "maxLength": null,
            "validationRegexp": null,
            "validationAsync": null,
            "valuesAllowed": [
              {
                "key": "AX",
                "name": "Åland Islands"
              },
              ...
              {
                "key": "ZM",
                "name": "Zambia"
              }
            ]
          }
        ]
      },
      {
        "name": "City",
        "group": [
          {
            "key": "city",
            "type": "text",
            "refreshRequirementsOnChange": false,
            "required": true,
            "displayFormat": null,
            "example": "London",
            "minLength": null,
            "maxLength": null,
            "validationRegexp": null,
            "validationAsync": null,
            "valuesAllowed": null
          }
        ]
      },
      {
        "name": "Postal code",
        "group": [
          {
            "key": "postCode",
            "type": "text",
            "refreshRequirementsOnChange": false,
            "required": true,
            "displayFormat": null,
            "example": "10025",
            "minLength": null,
            "maxLength": null,
            "validationRegexp": null,
            "validationAsync": null,
            "valuesAllowed": null
          }
        ]
      }
      ...
    ]
  }
]

Request

GET https://api.sandbox.transferwise.tech/v1/address-requirements
POST https://api.sandbox.transferwise.tech/v1/address-requirements

GET and POST address-requirements endpoints help you to figure out which fields are required to create a valid address for different countries. You could even build a dynamic user interface on top of these endpoints. This is a step-by-step guide on how these endpoints work.

1. Call GET /v1/address-requirements to get list of fields you need to fill with values in "details" section for creating a valid address. Response contains 4 required top level fields:

• country (select field with list of values)
• city (text field)
• postCode (text field)
• firstLine (text field)

2. Analyze the list of fields. Because refreshRequirementsOnChange for field 'country' is marked as true then this indicates that there are additional fields required depending on the selected value.

3. Call POST /v1/address-requirements with selected country value to expose sub fields.
   For example posting {"details": {"country" : "US"}} will also add "state" to list of fields.
   But posting {"details": {"country" : "GB"}} will not.

4. If you choose "US" as country you will notice that "state" field also has refreshRequirementsOnChange=true. This means you would need to make another POST call to /v1/address-requirements with a specific state value.
   For example posting {"details": { "country" : "US", "state": "AZ" }} will also add "occupation" to list of fields.
   But posting {"details": { "country" : "US", "state": "AL" }} will not.

5. So 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 an address object. For example this is a valid request to create address in US Arizona:

POST /v1/addresses

{
   "profile" : <your-profile-id>,
   "details": {
     "country" : "US",
     "state": "AZ",
     "city": "Phoenix",
     "postCode": "10025",
     "firstLine": "50 Sunflower Ave.",
   "occupation": "software engineer"
   }
}

Response

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": [
              {
                "reason": "sample reason"
              }
            ],
            "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

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.

The option.estimatedDeliveryDelays contains the reason of the delay in a string format.

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

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": [
              {
                "reason": "sample reason"
              }
            ],
            "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": [
              {
                "reason": "sample reason"
              }
            ],
            "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": [
              {
                "reason": "sample reason"
              }
            ],
            "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/

Response

See Create quote's response field information.

Recipient Accounts

These endpoints use a mixture of our v1 and v2 api - please ensure you address the right version to get the expected results. All recipient IDs are cross compatible with v1 and v2.

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 flag 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
• etc.

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. Numbers are not allowed in personal recipient names.
• 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.
• Special characters _()'*,. are allowed for personal and business names.
• In general the following regex describes our permitted characters for a name: [0-9A-Za-zÀ-ÖØ-öø-ÿ-_()'*,.\s].

Recipient requirements will vary depending on recipient type. A GBP example is provided here.
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

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.

Get By Id

Example Request:

curl -X GET https://api.sandbox.transferwise.tech/v2/accounts/{accountId} \
     -H "Authorization: Bearer <your api token>" 

Example Response:

{
    "id": 100,
    "creatorId": 300,
    "profileId": 305,
    "name": {
        "fullName": "Firstname Lastname",
        "givenName": null,
        "familyName": null,
        "middleName": null,
        "patronymicName": null,
        "cannotHavePatronymicName": null
    },
    "address": {
        "country": "US",
        "firstLine": "1 Wall Street",
        "postCode": "10025",
        "city": "New York",
        "state": "NY"
    },
    "currency": "USD",
    "country": "US",
    "type": "Aba",
    "legalEntityType": "PERSON",
    "email": "example@foobar.com",
    "active": true,
    "details": {
        "abartn": "064000020",
        "accountType": "CHECKING",
        "accountNumber": "00000000001"
    },
    "commonFieldMap": {
        "accountNumberField": "accountNumber",
        "bankCodeField": "abartn"
    },
    "hash": "a512e4066bd5997552d35e294d29bacda4b09a7610a7b75562767b17dddadf19",
    "accountSummary": "(064000020) 0********01",
    "longAccountSummary": "USD account ending in 0001",
    "displayFields": [
        {
            "label": "E-mail",
            "value": "example@foobar.com"
        },
        {
            "label": "ACH routing number",
            "value": "064000020"
        },
        {
            "label": "Account number",
            "value": "00000000001"
        }
    ],
    "ownedByCustomer": false
}

Get recipient account info by id. Note here we use the v2 endpoint to get the recipient details despite using v1 to create it. The v2 endpoint provides useful features such as the accountSummary and longAccountSummary field which can be used to represent the recipient's details in your UI. Additionally, the displayFields array would allow you to build an UI containing all the dynamic fields of a recipient individually.

This response also includes a hash of a recipient, this can be used to track if the recipient details change, which they can in some scenarios. This is a security feature to allow you to re-run any checks your system does on the recipient to validate them against, for example, fraud engines. The hash will remain constant unless the recipient's name or information in the details object changes.

Request

GET https://api.sandbox.transferwise.tech/v2/accounts/{accountId}

List

Example Request:

curl -X GET https://api.sandbox.transferwise.tech/v2/accounts?profile=<profileId>&currency=GBP \
     -H "Authorization: Bearer <your api token>" 

Example Response:

{
    "content": [
        {
            "id": 100,
            "creatorId": 300,
            "profileId": 305,
            "name": {
                "fullName": "Firstname Lastname",
                "givenName": null,
                "familyName": null,
                "middleName": null,
                "patronymicName": null,
                "cannotHavePatronymicName": null
            },
            "address": {
                "country": "US",
                "firstLine": "1 Wall Street",
                "postCode": "10025",
                "city": "New York",
                "state": "NY"
            },
            "currency": "USD",
            "country": "US",
            "type": "Aba",
            "legalEntityType": "PERSON",
            "email": "example@foobar.com",
            "active": true,
            "details": {
                "abartn": "064000020",
                "accountType": "CHECKING",
                "accountNumber": "00000000001"
            },
            "commonFieldMap": {
                "accountNumberField": "accountNumber",
                "bankCodeField": "abartn"
            },
            "isDefaultAccount": false,
            "hash": "a512e4066bd5997552d35e294d29bacda4b09a7610a7b75562767b17dddadf19",
            "accountSummary": "(064000020) 0********01",
            "longAccountSummary": "USD account ending in 0001",
            "displayFields": [
                {
                    "label": "E-mail",
                    "value": "example@foobar.com"
                },
                {
                    "label": "ACH routing number",
                    "value": "064000020"
                },
                {
                    "label": "Account number",
                    "value": "00000000001"
                }
            ],
            "ownedByCustomer": false
        },
        {
            "id": 101,
            "creatorId": 300,
            "profileId": 305,
            "name": {
                "fullName": "Firstname Anothername",
                "givenName": null,
                "familyName": null,
                "middleName": null,
                "patronymicName": null,
                "cannotHavePatronymicName": null
            },
            "address": {
                "country": "US",
                "firstLine": "1 Wall Street",
                "postCode": "10025",
                "city": "New York",
                "state": "NY"
            },
            "currency": "USD",
            "country": "US",
            "type": "Aba",
            "legalEntityType": "PERSON",
            "email": "example2@foobar.com",
            "active": true,
            "details": {
                "abartn": "064000020",
                "accountType": "CHECKING",
                "accountNumber": "00000000001"
            },
            "commonFieldMap": {
                "accountNumberField": "accountNumber",
                "bankCodeField": "abartn"
            },
            "isDefaultAccount": false,
            "hash": "992ca6102a11f2055d14682e0cbacd65727fc45e98b1c42ba1292acad08302c5",
            "accountSummary": "(064000020) 0********01",
            "longAccountSummary": "USD account ending in 0001",
            "displayFields": [
                {
                    "label": "E-mail",
                    "value": "example2@foobar.com"
                },
                {
                    "label": "ACH routing number",
                    "value": "064000020"
                },
                {
                    "label": "Account number",
                    "value": "00000000002"
                }
            ],
            "ownedByCustomer": false
        }
    ],
    "sort": {
        "sorted": false,
        "unsorted": true,
        "empty": true
    },
    "size": 2
}