Build Requirements
Partners are required to build out a few components and leverage the Wise API to conduct certain actions. These include:
- Configure Profiles
- Subscribe to 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 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.
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'
{"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.
curl https://api.sandbox.transferwise.tech/oauth/token \-u '<client id>:<client secret>' \-d 'grant_type=refresh_token' \-d 'refresh_token=<user refresh token>'
{"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.
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.
Field | Description | Format |
---|---|---|
grant_type | "refresh_token" | Text |
refresh_token | User's refresh_token obtained from creating or linking to a TW user. | Text |
Response
Field | Description | Format |
---|---|---|
access_token | Access token to be used when calling API endpoints on behalf of user. Valid for 12 hours. | Text |
token_type | "bearer" | Text |
refresh_token | Refresh token which you need to use in order to request new access_token once the existing one expires | Text |
expires_in | Expiry time in seconds | Integer |
scope | "transfers" | Text |
When a Swift message is received, we trigger a webhook to notify you of the transaction. This includes the full Swift message as received and is confirmation that the funds have been deposited into your balance.
Each partner should subscribe to the latest version of the swift-in#credit
webhook following our webhook documentation. If you plan to run any validation on the message content, we recommend you do so after accepting the webhook. Wise won't take any action based on delivery failures so partners will need to manually resolve validation errors or request a return of the failed payment via the Returns API.
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