Partners are required to build out a few components and leverage the Wise API to conduct certain actions. These include:
- Configure Profiles
- Subscribe to webhook
- Develop process for sweeping balance funds
- Develop process for reconciliation of transfers
Building these features generally requires access to our sandbox environment, and specific settings are required to make that work. Your implementation manager will direct you on completing the initial configuration + access portion of the integration, and will then provide credentials for access to the sandbox environment.
We do not recommend starting the build of these components until this access has been granted.
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
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
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.
curl \'https://api.sandbox.transferwise.tech/oauth/token' \-u '[your-api-client-id]:[your-api-client-secret]' \-d 'grant_type=authorization_code' \-d 'client_id=[your-api-client-id]' \-d 'code=[code-from-redirect-uri]' \-d 'redirect_uri=https://www.yourbank.com'
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.
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]'
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.
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.
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.
|refresh_token||User's refresh_token obtained from creating or linking to a TW user.||Text|
|access_token||Access token to be used when calling API endpoints on behalf of user. Valid for 12 hours.||Text|
|refresh_token||Refresh token which you need to use in order to request new access_token once the existing one expires||Text|
|expires_in||Expiry time in seconds||Integer|
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.
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
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