Partner Account

This guide is intended for Wise partners who are the direct customer of Wise either by transacting on their own partner account (First Party), OR by transacting on their partner account as their customer, providing originator data (Third Party).

First Party

In this model, the end customer is the partner we are working with, and the partner will onboard to Wise and have their own profile. They may be doing payouts or internal treasury operations over Wise’s API.

Third Party

In this model, Wise onboards the partner directly. Wise does not onboard the partner’s customers. Instead, the partner’s customers access Wise services through the partner app as a “third party” customer of Wise. Wise still collects the data of the end user as an “originator” but they do not have their own profiles ( 3rd Party Infrastructure Partner). These are often white-labeled solutions and the customer is not made aware that Wise is being used for their payments.

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

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

Production

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

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.

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.

Refer to Versioning Changes for more information.

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 above
• Required data fields for recipients and transfers vary for different currencies. Please explore Recipient Account Requirements and Transfer 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. Monitor API status

• You can always track our API status here.

There are different ways to build your user experience, especially when it comes to the sequence of steps in the payment flow. We do have a recommended order that has been tuned by the Wise team, and we are happy to assist you to design and build a great experience for your customers.

The transfer flow

To create transfers you need these building blocks:

• Refresh Access Token
• Create Quote
• Create Recipient Account
• Create Transfer
• Fund Transfer