Build Requirements

Partners are required to build out a few components and leverage the Wise API to conduct certain actions. These include:

  1. Configure Profiles
  2. Subscribe to webhook
  3. Develop process for sweeping balance funds
  4. Develop process for reconciliation of transfers

Building these features generally requires access to our sandbox environment, and specific settings are required to make that work. Your implementation manager will direct you on completing the initial configuration + access portion of the integration, and will then provide credentials for access to the sandbox environment.

We do not recommend starting the build of these components until this access has been granted.

You will be supplied with a set of credentials specific for your integration. These credentials must be used to follow our OAuth process, which in turn will allow you to generate an access_token and a refresh_token.

This connection is important, as it is what allows your specific profiles to be linked to SWIFT Receive. This will be a one time operation, but is required to be completed in both our sandbox and production environments.

Please follow the details below to complete this link.

Step 1 - OAuth Account

To start, in a web browser, login to the Wise account you want to link to. If asked, you can access the business profile that you want to use for SWIFT Receive.

In your URL browser, open the following link based on the environment. Note that you will also need to update clientId.

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

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

This will open a screen that will ask you to select the correct profile, and then authorize the connection to your account and profile. Complete this process.

Once complete, you will be redirected to localhost with a set of URL parameters included. One of these parameters is the code. Take note of this for step 2.

Example Request
curl https://api.sandbox.transferwise.tech/oauth/token \
-u '<client id>:<client secret>' \
-d 'grant_type=authorization_code' \
-d 'client_id=<client id>' \
-d 'code=<code from redirect uri>' \
-d 'redirect_uri=https://www.yourapp.com'
Example Response
{
"access_token":"ba8k9935-62f2-475a-60d8-6g45377b4062",
"token_type":"bearer",
"refresh_token":"a235uu9c-9azu-4o28-a1kn-e15500o151cx",
"expires_in": 43199,
"scope":"transfers"
}

Step 2 - Exchange Auth Code

Once you have the code, you need to exchange this for an access_token and a refresh_token. To do this, see the example request to the right.

Example Request
curl https://api.sandbox.transferwise.tech/oauth/token \
-u '<client id>:<client secret>' \
-d 'grant_type=refresh_token' \
-d 'refresh_token=<user refresh token>'
Example Response
{
"access_token":"be69d566-971e-4e15-9648-85a486195863",
"token_type":"bearer",
"refresh_token":"1d0ec7b9-b569-426d-a18d-8dead5b6a3cc",
"expires_in":43199,
"scope":"transfers"
}

Step 3 - Refresh Access Tokens

Access tokens are designed to expire after a short period of time, representing a login session to the Wise Platform API. This increases security of the account and profile in case the token is leaked.

In order to maintain an uninterrupted connection, you can request a new access token whenever the previous one is close to expiring. There is no need to wait for the actual expiration to happen first.

Managing Access Tokens

It is important to note that using a refresh_token to generate a new access_token automatically invalidates the previously granted access_token. It is important to manage the access tokens carefully and to use central storage if using a stateless system.

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.

Under no circumstances should any token data be passed in the URL path or query string.
FieldDescriptionFormat
grant_type"refresh_token"Text
refresh_tokenUser's refresh_token obtained from creating or linking to a TW user.Text

Response

FieldDescriptionFormat
access_tokenAccess token to be used when calling API endpoints on behalf of user. Valid for 12 hours.Text
token_type"bearer"Text
refresh_tokenRefresh token which you need to use in order to request new access_token once the existing one expiresText
expires_inExpiry time in secondsInteger
scope"transfers"Text

When a SWIFT message is received and deposited, we trigger a webhook to be sent to our partners. This notifies you of the transaction, includes the full SWIFT message as it was received, and is confirmation that the funds have been deposited into your balance.

Each partner must subscribe to the webhook following our standard webhook documentation. See the SWIFT-in#credit webhook documentation for complete details on subscribing to and consuming this webhook. We recommend using the latest version of the webhook.

All SWIFT messages and subsequent fund transfers are deposited into a single balance account for the partner. While you can store those funds with Wise, you likely will want to sweep these funds on a regular basis. Due to this, you must create a balance pay out.

To do this, you must create a quote, associate it to a recipient, create the transfer, and then fund that transfer. As this will likely be the same for each sweep, we recommend to follow these steps:

Step 1 - Create Recipient

As part of the initial setup, you will need to create the recipient that you want to sweep funds to. This is a one time operation, and will result in the generation of the accountID that can be used in the subsequent quote call.

Step 2 - Create Quote with Previously Created Recipient

Once you have a recipient, you will want to call the quote create endpoint, making sure to include the targetAccount. This removes the need to patch the quote with the recipient in the future.

You will additionally need to know how much you are looking to transfer. It's recommended that you first reconcile and determine the amount you want to transfer. This will be based on your processes though.

Step 3 - Create Transfer

Once the quote is created, it will then need to be confirmed as a transfer. This is straight forward and will include the targetAccount and quoteUUID along with any given transfer requirements.

Step 4 - Fund Transfer from Balance

Once the transfer is created, you will need to fund that from BALANCE. See the reference on successfully funding from balance.

While we will send webhooks for each SWIFT message received, you will want to reconcile the transfers in your account. To do this, you can use the API to get statements and then reconcile those against what was received.

Get Statements API