SWIFT Receive Implementation Guide

This guide describes in detail the technical implementation of SWIFT Receive from Wise. If you need any help please reach out to the Wise team here.

How It Works

At its simplest, the SWIFT Receive integration enables a partner's customers to receive international payments via SWIFT. Customers use the partners BIC and their IBAN to direct a payment over SWIFT, which after moving through correspondents is accepted by Wise and deposited into the partners balance.

Partners can then manage their balance and transactions as any other balance with Wise, including sweeping funds, transaction reconciliation, and generating statements. We also provide a specific webhook to notify partners of incoming SWIFT payments in real time.

SWIFT Receive Handling Flow

Implementing SWIFT Receive

Implementing the SWIFT Receive solution with Wise will generally take 4-6 weeks or more. Following this guide, with the aid of your implementation manager, can ensure this goes smoothly.

It's also important to note that partners are required to build some tools and features on the Wise API to enable certain features and functionality. This guide documents the steps required to get this completed. Generally, this can be completed in a few days of development time, depending on the level of automation required by the partner.

Getting Started

To begin technical setup, we recommend first having a kick-off call with your implementation manager. They will walk through the steps outline din this guide and help assist with the non-technical components.

For the technical integration, two distinct steps are required:

  1. Configuration + Access
  2. Partner Technical Build

Step one can be completed at any time and should be done as soon as possible on the recommendation of our implementation team. Once received, we will complete all other pieces in order to begin the process of step 2. We recommend waiting to build out the integration until the implementation team supplies you with sandbox credentials.

Configuration + Access

In order to configure SWIFT Receive, we require some essential steps to be completed by partners. Once those are completed, we can configure your accounts to allow the receipt of SWIFT messages and ensure that those messages are routed to the right balances.

Your implementation manager will assist with this process and collect the right details as described below.

1. Setup Wise Account

SWIFT Receive requires a profile with a balance account to complete transactions and deposits. We recommend that this profile and balance be separate from any other profiles and balances used by the partner to aid in reconciliation and integration management

Please follow the steps below in both our sandbox and production environments.

  1. Login or register for a new account. Make note of the credentials used for this as these will be needed later in your implementation
  2. Ensure that a personal profile is configured on the account. Speak with your implementation manager if you are unsure of who should be included in this profile.
  3. Create a new business profile. The name on this account should match the name of the partner's bank account. Further, the partner must use an email address which is actively monitored and which their back office team has access to; this ensures that any RFIs can and will be dealt with efficiently.
  4. Record the Membership Number (P#######) for the newly created business profile.

The membership number for both environments should then be given to your implementation manager. The business profile in each environment will be given access to SWIFT Receive and all transfers to the configured BICs will deposit to the production profile.

2. Provide BIC(s)

In order to complete configuration, we need to know the BICs you would like us to match and deposit into your balance. This can be a list of specific BICs or can be based on a "starts with" match.

For example, if we configure "BANKDE12", any branch code will also be matched, such as "BANKDE12XXX". If you would like for us to match specific branch codes, those should be provided.

3. Update Test Standing Settlement Instruction

Due to the length of time it can take for the SWIFT network to update the standing settlement instructions for BICs, it's advised that a test BIC to be used for testing be updated to point towards Wise's BIC.

This should only be done for a BIC that is not used by your customers in production at this point. Often this is a separate BIC that is unused or reserved for testing.

Speak with your implementation manager further about this and when it is applicable to make this change.

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 SWIFT 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.

1. Configuring Profiles

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 complete din 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 '[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'

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

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

Step 3 - Refresh Access Tokens

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 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.

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

2. Subscribe to Webhook

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.

3. Sweeping Balance

All SWIFT messages and subsequent fund transfers are depostied into a single balance account for the partner. While you can store those funds with Wise, you likley will want to sweep these funds on a regular basis. Do 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.

4. Reconciliation

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

Testing + Go Live

Testing Swift Receive

Testing over the SWIFT Network is currently not very straight forward, as we have no way to do tests or use any kind of sandbox environment for sending SWIFT messages.

In order to test, we are required to do real payments over the network. As SWIFT messages take some time to complete, testing can be slow through this method. Further, updating SSI details can often take time as well.

To manage these issues, there are two ways we will test the integration.

Mock MT103 with Sandbox

Once we have configured Sandbox, you will be able to complete the initial tech build for webhook subscriptions, balance statements, and sweeping of funds. In addition, we will provide a simulation endpoint to send a mock MT103 to sandbox. This will allow you to check all settings, your webhook subscription, and your process for sweeping your account before moving to production.

Unused/Test BIC in Production

Many of our partners have additional BICs specifically for testing. We recommend updating the SSI on this to our BIC once your implementation manager informs you to. This ensures we can test proper flows and production testing when ready to go live.

Going Live

Once configuration is completed, and production testing has been completed, you will need to update your SSI for your production BIC to point to our BIC.

It is also recommended that you notify other members that the SSI has been updated, as it can often take a long time for members to update on their own. This can be done through an MT670 message sent directly to SWIFT, after which they will send an MT671 to all institutions. Wise needs to send this message on the partner's behalf, and this comes at a cost which will be discussed and invoiced directly.

Quotes

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": [],
            "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

Field Description Format
profileId Personal or business profile id of the sender - required. Integer
sourceCurrency Source (sending) currency code. Text
targetCurrency Target (receiving) currency code. Text
targetAmount Amount in target currency. Decimal
sourceAmount Amount in source currency.
Either sourceAmount or targetAmount is required, never both.
Decimal
targetAccount Optional. If provided can be used as an alternative to updating the quote. Integer
payOut Optional. Preferred payout method. Default value is BANK_TRANSFER. Other possible values are BALANCE, SWIFT, SWIFT_OUR and INTERAC. Text
preferredPayIn Optional. Preferred payin method. Use BANK_TRANSFER to return this method at the top of the response's results. Text

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.

Field Description Format
id ID of this quote (GUID format). Text
sourceCurrency Source (sending) currency code. Text
targetCurrency Target (receive) currency code. Text
sourceAmount Amount in source currency to send. Decimal
targetAmount Amount in target currency to be received by the recipient. Decimal
payOut Mechanism we use to deliver the transfer. Not usually of interest to the user. Text
rate Exchange rate value used for the conversion. Decimal
createdTime Quote created timestamp. Timestamp
user User ID who created the quote. Integer
profile Personal or business profile id. Integer
rateExpirationTime Time the locked rate will expire. Timestamp
providedAmountType Whether the quote was created as "SOURCE" or "TARGET". Text
paymentOptions List of the methods a user can pay for the transfer. See above for help on choosing the correct one to display. [PaymentOption]
option.disabled Whether this option is enabled or not for this quote. Boolean
option.estimatedDelivery The estimated delivery time for this combination of payIn and payOut methods, assuming payIn is performed now. Timestamp
option.formattedEstimatedDelivery A string to display to users for the estimated delivery date. Text
option.estimatedDeliveryDelays Array of strings for delivery delays to display to users. [Text]
option.fee Object containing fee information. Fee
option.fee.transferwise The fee to be paid by the sender based on the current state of the quote. Decimal
option.fee.payIn The fee for this payment option, based on the product type of the payment option. Decimal
option.fee.discount Any discounts that have been applied to this quote for the user. Decimal
option.fee.partner If you have agreed a custom price, it will be displayed here. Decimal
option.fee.total The total fees to be paid - use this figure when displaying fees on your app. Decimal
option.price Object containing the price information. Price
option.price.priceSetId Id if the price structure. Integer
option.price.total The total fees to be paid - use this figure when displaying fees on your app. Total
option.price.total.id ID of this structure. Integer
option.price.total.type Type of the pricing element - "TOTAL" in this case. Text
option.price.total.label Short text describing the price structure this field is nested in. Text
option.price.total.value Object containing value elements. Value
option.price.total.value.amount Amount to be paid. Decimal
option.price.total.value.currency Currency of the amount to be paid. Text
option.price.total.value.label Text version of the price. Text
option.price.total.explanation Text element giving more details about the price. Text
option.price.items Object containing the detals of the different elements of the total price. List
option.price.items.id Id of this item. Integer
option.price.items.type Type of the pricing item. It could be "DISCOUNT" for example. Text
option.price.items.label Short text describing the pricing element. Text
option.price.items.value Object containing value elements. Value
option.price.items.value.amount Amount associated to this pricing element. Can be negative for discounts. Decimal
option.price.items.value.currency Currency on the pricing element. Text
option.price.items.value.label Text feild containing the price and its currency. Text
option.price.items.explanation Text element giving more details about the item. Text
option.sourceAmount sourceAmount when using this payment option. Decimal
option.targetAmount targetAmount when using this payment option. Decimal
option.payIn Type of pay in method for this payment option. Text
option.payOut Type of pay out method for this payment option. Text
option.allowedProfileTypes Array of the allowed types of profile to use this payment option for this quote "PERSONAL", "BUSINESS" or both. [Text]
option.disabledReason Object present if a payment option is disabled. Disabled Reason
option.disabledReason.code Code to denote the reason a payment method is unavailable. Text
option.disabledReason.message User friendly message to display when a method is unavailable. Text
status Current status of this quote, one of: "PENDING", "ACCEPTED", "FUNDED" or "EXPIRED". Text
expirationTime The time the quote expires. Timestamp
notices Array of messages to display to the user in case of useful information based on their selections. May be empty ([]) if there are no messages. [QuoteNotice]
notice.text The message to display. Text
notice.link URL that provides more information to the message. May be null if there's no URL. Text
notice.type Type of message, WARNING or INFO or BLOCKED. If it is BLOCKED, don't allow the quote to be used to create the transfer. Text

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"
      }'
Field Description Format
targetAccount ID of transfer recipient, found in response from POST v1/accounts (recipient creation) Integer
payOut Optional. Preferred payout method. Default value is BANK_TRANSFER. Other possible values are BALANCE, SWIFT, SWIFT_OUR and INTERAC. Text

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": [],
            "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": [],
            "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": [],
            "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/

Field Description Format
sourceCurrency Source (sending) currency code Text
targetCurrency Target (receiving) currency code Text
sourceAmount Amount in source currency.
Either sourceAmount or targetAmount is required, never both.
Decimal
targetAmount Amount in target currency Decimal

Response

See Create quote's response field information.

















































Recipient Accounts

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

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.
  • 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.
  • Digits are not allowed, except in business names.
  • Special characters _()'*,. are allowed for personal and business names.
  • Additionally, special characters []%#^@&{}"~<> are allowed for business names.

These requirements may vary depending of recipient type. A GBP example is provided here. You can find other currency examples below.
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

Field Description Format Optional
currency 3 character currency code Text false
type Recipient type Text false
profile Personal or business profile id Integer false
accountHolderName Recipient full name Text false
ownedByCustomer Whether this account is owned by the sending user Boolean true
details Currency specific fields Object false
details.legalType Recipient legal type: PRIVATE or BUSINESS Text false
details.sortCode Recipient bank sort code (GBP example) Text false
details.accountNumber Recipient bank account no (GBP example) Text false

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.

Field Description Format Nullable
id accountId Integer false
profile Personal or business profile id Integer true
user User that created or owns this recipient Integer false
acccountHolderName Recipient full name Text false
currency 3 character currency code Text false
country 2 character country code Text false
type Recipient type Text false
ownedByCustomer Whether this account is owned by the sending user Boolean false
details Currency specific fields Object false
details.legalType Recipient legal type Text true
details.sortCode Recipient bank sort code (GBP example) Text Currency Dependent
details.accountNumber Recipient bank account no (GBP example) Text Currency Dependent

Get By Id

Example Request:

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

Example Response:

{
    "id": 13967081,
    "profile": <your profile id>, 
    "accountHolderName": "Ann Johnson",
    "type": "sort_code", 
    "country": "GB", 
    "currency": "GBP",
    "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": false
}

Get recipient account info by id.

Request

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

List

Example Request:

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

Example Response:

[
  {
      "id": 13967081,
      "profile": <your profile id>, 
      "accountHolderName": "Ann Johnson",
      "type": "sort_code", 
      "country": "GB", 
      "currency": "GBP",
      "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": false
  },
  {
      "id": 31273090,
      "profile": <your profile id>, 
      "accountHolderName": "George Johnson",
      "type": "sort_code", 
      "country": "GB", 
      "currency": "GBP",
      "details": {
          "address": {
              "country": null,
              "countryCode": null,
              "firstLine": null,
              "postCode": null,
              "city": null,
              "state": null
          },
          "email": null,
          "legalType": "PRIVATE",
          "accountNumber": "29912211",
          "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
  }
]

Fetch a list of the user's recipient accounts. Use the currency and profile parameters to filter by currency and/or the owning user profile ID. This list does not currently support pagination, therefore if please filter by currency to ensure a reasonable response time.

Request

GET https://api.sandbox.transferwise.tech/v1/accounts?profile=<profileId>&currency=<currencyCode>

Both query parameters are optional.

Field Description Format
profileId Personal or business profile id Integer
currency Currency code Text

Delete

Example Request:

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

Deletes a recipient by changing its status to inactive. Only active recipients can be deleted and a recipient cannot be reactivated, however you can create a new recipient with the same details instead.

Response is empty if delete succeeds.

Requesting to delete recipient that is already inactive will return an http status 403 (forbidden).

Request

DELETE https://api.sandbox.transferwise.tech/v1/accounts/{accountId}

Requirements version 1.1

Example Request:

curl -X GET https://api.sandbox.transferwise.tech/v1/quotes/{quoteId}/account-requirements \
     -H "Authorization: Bearer <your api token>" 
     -H "Accept-Minor-Version: 1"

Example Response:

[
    {
        "type": "south_korean_paygate",
        "title": "PayGate",
        "usageInfo": null,
        "fields": [
            {
                "name": "E-mail",
                "group": [
                    {
                        "key": "email",
                        "name": "E-mail",
                        "type": "text",
                        "refreshRequirementsOnChange": false,
                        "required": true,
                        "displayFormat": null,
                        "example": "example@example.ex",
                        "minLength": null,
                        "maxLength": null,
                        "validationRegexp": "^[^\\s]+@[^\\s]+\\.[^\\s]{2,}$",
                        "validationAsync": null,
                        "valuesAllowed": null
                    }
                ]
            },
            {
                "name": "Recipient type",
                "group": [
                    {
                        "key": "legalType",
                        "name": "Recipient type",
                        "type": "select",
                        "refreshRequirementsOnChange": false,
                        "required": true,
                        "displayFormat": null,
                        "example": "",
                        "minLength": null,
                        "maxLength": null,
                        "validationRegexp": null,
                        "validationAsync": null,
                        "valuesAllowed": [
                            {
                                "key": "PRIVATE",
                                "name": "Person"
                            }
                        ]
                    }
                ]
            },
            {
                "name": "Full Name",
                "group": [
                    {
                        "key": "accountHolderName",
                        "name": "Full Name",
                        "type": "text",
                        "refreshRequirementsOnChange": false,
                        "required": true,
                        "displayFormat": null,
                        "example": "",
                        "minLength": 2,
                        "maxLength": 140,
                        "validationRegexp": "^[0-9A-Za-zÀ-ÖØ-öø-ÿ-_()'*,.%#^@{}~<>+$\"\\[\\]\\\\ ]+$",
                        "validationAsync": null,
                        "valuesAllowed": null
                    }
                ]
            },
            {
                "name": "Recipient's Date of Birth",
                "group": [
                    {
                        "key": "dateOfBirth",
                        "name": "Recipient's Date of Birth",
                        "type": "date",
                        "refreshRequirementsOnChange": false,
                        "required": true,
                        "displayFormat": null,
                        "example": "",
                        "minLength": null,
                        "maxLength": null,
                        "validationRegexp": "^\\d{4}\\-\\d{2}\\-\\d{2}$",
                        "validationAsync": null,
                        "valuesAllowed": null
                    }
                ]
            },
            {
                "name": "Recipient Bank Name",
                "group": [
                    {
                        "key": "bankCode",
                        "name": "Recipient Bank Name",
                        "type": "select",
                        "refreshRequirementsOnChange": false,
                        "required": true,
                        "displayFormat": null,
                        "example": "Choose recipient bank",
                        "minLength": null,
                        "maxLength": null,
                        "validationRegexp": null,
                        "validationAsync": null,
                        "valuesAllowed": [
                            {
                                "key": "",
                                "name": "Choose recipient bank"
                            },
                            ...
                        ]
                    }
                ]
            },
            {
                "name": "Account number (KRW accounts only)",
                "group": [
                    {
                        "key": "accountNumber",
                        "name": "Account number (KRW accounts only)",
                        "type": "text",
                        "refreshRequirementsOnChange": false,
                        "required": true,
                        "displayFormat": null,
                        "example": "1254693521232",
                        "minLength": 10,
                        "maxLength": 16,
                        "validationRegexp": null,
                        "validationAsync": null,
                        "valuesAllowed": null
                    }
                ]
            }
        ]
    },

Request

GET https://api.sandbox.transferwise.tech/v1/quotes/{quoteId}/account-requirements
POST https://api.sandbox.transferwise.tech/v1/quotes/{quoteId}/account-requirements
GET https://api.sandbox.transferwise.tech/v1/account-requirements?source=EUR&target=USD&sourceAmount=1000

You can use the data returned by this API to build a dynamic user interface for recipient creation. The third sample shows how to get account requirements for a specific currency route without referring to a particular quote but with the amount, source and target currencies passed as URL parameters.

The v1.1 version of GET and POST account requirements, enabled using the Accept-Minor-Version header enables you to fetch requirements which include both recipient name and email fields in the dynamic form, simplifying implementation of the form. Name and email address dynamic fields are required to support currencies such as KRW, JPY and RUB, and also simplify the use of dynamic forms by removing the need for manual name validation. Set the request header Accept-Minor-Version to 1 to use this version.

These endpoints support use of both v1 and v2 quotes using long or UUID based IDs.

Requirements

Example Request:

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

Example Response:

[
    {
        "type": "aba",
        "title": "Local bank account",
        "fields": [
            {
                "name": "Recipient type",
                "group": [
                    {
                        "key": "legalType",
                        "name": "Recipient type",
                        "type": "select",
                        "refreshRequirementsOnChange": false,
                        "required": true,
                        "displayFormat": null,
                        "example": "",
                        "minLength": null,
                        "maxLength": null,
                        "validationRegexp": null,
                        "validationAsync": null,
                        "valuesAllowed": [
                            {
                                "key": "PRIVATE",
                                "name": "Person"
                            },
                            {
                                "key": "BUSINESS",
                                "name": "Business"
                            }
                        ]
                    }
                ]
            },
            {
                "name": "ACH routing number",
                "group": [
                    {
                        "key": "abartn",
                        "name": "ACH routing number",
                        "type": "text",
                        "refreshRequirementsOnChange": false,
                        "required": true,
                        "displayFormat": null,
                        "example": "026009593",
                        "minLength": 9,
                        "maxLength": 9,
                        "validationRegexp": "^\\d{9}$",
                        "validationAsync": null,
                        "valuesAllowed": null
                    }
                ]
            },
            {
                "name": "Account number",
                "group": [
                    {
                        "key": "accountNumber",
                        "name": "Account number",
                        "type": "text",
                        "refreshRequirementsOnChange": false,
                        "required": true,
                        "displayFormat": null,
                        "example": "12345678",
                        "minLength": 4,
                        "maxLength": 17,
                        "validationRegexp": "^\\d{4,17}$",
                        "validationAsync": null,
                        "valuesAllowed": null
                    }
                ]
            },
            {
                "name": "Account type",
                "group": [
                    {
                        "key": "accountType",
                        "name": "Account type",
                        "type": "radio",
                        "refreshRequirementsOnChange": false,
                        "required": true,
                        "displayFormat": null,
                        "example": "CHECKING",
                        "minLength": null,
                        "maxLength": null,
                        "validationRegexp": null,
                        "validationAsync": null,
                        "valuesAllowed": [
                            {
                                "key": "CHECKING",
                                "name": "Checking"
                            },
                            {
                                "key": "SAVINGS",
                                "name": "Savings"
                            }
                        ]
                    }
                ]
            },
            {
                "name": "Country",
                "group": [
                    {
                        "key": "address.country",
                        "name": "Country",
                        "type": "select",
                        "refreshRequirementsOnChange": true,
                        "required": true,
                        "displayFormat": null,
                        "example": "",
                        "minLength": null,
                        "maxLength": null,
                        "validationRegexp": null,
                        "validationAsync": null,
                        "valuesAllowed": [
                            {
                                "key": "AF",
                                "name": "Afghanistan"
                            },
                            {
                                "key": "AL",
                                "name": "Albania"
                            },
                            {
                            ...
                            }

                        ]
                    }
                ]
            },
            {
                "name": "City",
                "group": [
                    {
                        "key": "address.city",
                        "name": "City",
                        "type": "text",
                        "refreshRequirementsOnChange": false,
                        "required": true,
                        "displayFormat": null,
                        "example": "",
                        "minLength": null,
                        "maxLength": null,
                        "validationRegexp": null,
                        "validationAsync": null,
                        "valuesAllowed": null
                    }
                ]
            },
            {
                "name": "Address",
                "group": [
                    {
                        "key": "address.firstLine",
                        "name": "Address",
                        "type": "text",
                        "refreshRequirementsOnChange": false,
                        "required": true,
                        "displayFormat": null,
                        "example": "",
                        "minLength": null,
                        "maxLength": null,
                        "validationRegexp": null,
                        "validationAsync": null,
                        "valuesAllowed": null
                    }
                ]
            },
            {
                "name": "Post Code",
                "group": [
                    {
                        "key": "address.postCode",
                        "name": "Post Code",
                        "type": "text",
                        "refreshRequirementsOnChange": false,
                        "required": true,
                        "displayFormat": null,
                        "example": "",
                        "minLength": null,
                        "maxLength": null,
                        "validationRegexp": null,
                        "validationAsync": null,
                        "valuesAllowed": null
                    }
                ]
            }
        ]
    },

Request

GET https://api.sandbox.transferwise.tech/v1/quotes/{quoteId}/account-requirements
POST https://api.sandbox.transferwise.tech/v1/quotes/{quoteId}/account-requirements
GET https://api.sandbox.transferwise.tech/v1/account-requirements?source=EUR&target=USD&sourceAmount=1000

The GET and POST account-requirements endpoints help you to figure out which fields are required to create a valid recipient for different currencies. You can use these data to build a dynamic user interface on top of these endpoints. The third sample shows how to get account requirements for a specific currency route without referring to a particular quote but with the amount, source and target currencies passed as URL parameters. This is a step-by-step guide on how these endpoints work.

Using account requirements

1.First create a quote to specify currencies and transfer amounts. See Create.Quote.

2.Call GET /v1/quotes/{quoteId}/account-requirements to get the list of fields you need to fill with values in the "details" section for creating a valid recipient account.

In order to create an "aba" recipient type you need these top level fields:

  • legalType (PRIVATE / BUSINESS)
  • abartn (ABA routing number)
  • accountType (CHECKING / SAVINGS)
  • address.country
  • address.city
  • address.postalCode
  • address.firstLine

Some fields require multiple levels of fields in the details request, for example Country followed by State. This should be handled by the client based on the refreshRequirementsOnChange field. In the example above 'address.country' has 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 account-requirements endpoint. You will be returned a response similar the previosuly returned data from GET account-requirements but with additional fields.

3.For example, construct a recipient object with all top level fields and call POST /v1/quotes/{quoteId}/account-requirements with these value to expose sub fields.
For example posting US as country will also add "state" to list of fields.

{
    "type": "aba",
    "details": {
      "legalType": "PRIVATE",
      "abartn": "111000025",
      "accountNumber": "12345678",
      "accountType": "CHECKING",
      "address": {
        "country": "US"
      }
    }
}

However, posting GB as country will not add any new fields as GB addresses do not have this extra requirement.

{
    "type": "aba",
    "details": {
      "legalType": "PRIVATE",
      "abartn": "111000025",
      "accountNumber": "12345678",
      "accountType": "CHECKING",
      "address": {
        "country": "GB"
      }
    }
}

It is possible that any new fields returned may also have refreshRequirementsOnChange field set to true. Therefore you must keep iterating on the partially created details object until POST account-requirements returns you no new fields that it previously didn't include in the response, you can do this by checking the size of the array returned.

4.Once you have built your full recipient details object you can use it to create a recipient.

For example this is a valid request to create a recipient with address in US Arizona:
POST /v1/accounts:

{
    "profile": your-profile-id,
    "accountHolderName": "John Smith",
    "currency": "USD",
    "type": "aba",
    "details": {
    	"legalType": "PRIVATE",
    	"abartn": "111000025",
    	"accountNumber": "12345678",
    	"accountType": "CHECKING",
    	"address": {
    		"country": "US",
    		"state": "AZ"
       	"city": "New York",
    		"postCode": "10025",
    		"firstLine": "45 Sunflower Ave"
    	}
    }
}

We do not require the recipient's address for most receiving currencies and as such do not return these form elements by default. In some cases it may be desirable for you to collect this from users and store it as part of the recipient object in the Wise platform. If you wish to do this you can include the parameter &addressRequired=true in your call to GET /v1/quotes/{quoteId}/account-requirements, if this is present we will return address fields as part of the form.

Building a user interface

Account requirements help us understand how to create a valid account given a certain context. As a tool to help explore this API, please visit Dynamic Forms UI. This app allows specifying different requests and calls our sandbox environment for account requirements. It then displays the response in JSON along with an example of the rendered form from the said response.

When requesting the form data from the account-requirements endpoint, the first level of the response defines different types of recipient you can create, the first thing to do is present the user a choice of which recipient type they wish to create, e.g. to GBP this could be local details or IBAN format. Each recipient 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:

type UI element
text A free text box
select A selection box/dialog
radio A radio button choice between options
date A text box with a date picker

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 wil also be done when a completed recipient is submitted to POST /v1/accounts.

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.

Response

Field Description Format
type "address" Text
fields[n].name Field description Text
fields[n].group[n].key Key is name of the field you should include in the JSON Text
fields[n].group[n].type Display type of field (e.g. text, select, etc) Text
fields[n].group[n].refreshRequirementsOnChange Tells you whether you should call POST account-requirements once the field value is set to discover required lower level fields. Boolean
fields[n].group[n].required Indicates if the field is mandatory or not Boolean
fields[n].group[n].displayFormat Display format pattern. Text
fields[n].group[n].example Example value. Text
fields[n].group[n].minLength Min valid length of field value. Integer
fields[n].group[n].maxLength Max valid length of field value. Integer
fields[n].group[n].validationRegexp Regexp validation pattern. Text
fields[n].group[n].validationAsync Validator URL and parameter name you should use when submitting the value for validation Text
fields[n].group[n].valuesAllowed[n].key List of allowed values. Value key Text
fields[n].group[n].valuesAllowed[n].name List of allowed values. Value name. Text

Validate Recipient Fields

Example Request (Validate sort code (GBP):

curl -X GET https://api.sandbox.transferwise.tech/v1/validators/sort-code?sortCode=231470

Example Response (Validate sort code (GBP):

{
    "validation": "success"
}

or  

{
    "errors": [
        {
            "code": "VALIDATION_NOT_SUCCESSFUL",
            "message": "sortCode has not passed validation.",
            "path": "sortCode",
            "arguments": [
                "2314701"
            ]
        }
    ]
}

There are several validation URLs that make creating correct recipient accounts easier. These URLs are also included in fields provided by Recipient Accounts.Requirements endpoint.

GBP

Validate UK bank sort code

https://api.transferwise.com/v1/validators/sort-code?sortCode=231470

Validate UK bank account number

https://api.transferwise.com/v1/validators/sort-code-account-number?accountNumber=10000246

BGN CHF, DKK, EUR, GEL, GBP, NOK, PKR, PLN, RON, SEK

Validate IBAN

https://api.transferwise.com/v1/validators/iban?iban=EE867700771000187087

Validate BIC and IBAN

https://api.transferwise.com/v1/validators/bic?bic=LHVBEE22&iban=EE867700771000187087

USD

Validate ABA routing number

https://api.transferwise.com/v1/validators/abartn?abartn=011103093

Validate ABA bank account number

https://api.transferwise.com/v1/validators/aba-account-number?accountNumber=111000025

INR

Validate IFSC code

https://api.transferwise.com/v1/validators/ifsc-code?ifscCode=YESB0236041

Validate Indian bank account number

https://api.transferwise.com/v1/validators/indian-account-number?accountNumber=678911234567891

AUD

Validate BSB code

https://api.transferwise.com/v1/validators/bsb-code?bsbCode=112879

Validate Australian bank account number

https://api.transferwise.com/v1/validators/australian-account-number?accountNumber=123456789

CAD

Validate Canadian institution number

https://api.transferwise.com/v1/validators/canadian-institution-number?institutionNumber=006

Validate Canadian bank transit number

https://api.transferwise.com/v1/validators/canadian-transit-number?institutionNumber=006&transitNumber=04841

Validate Canadian bank account number

https://api.transferwise.com/v1/validators/canadian-account-number?institutionNumber=006&transitNumber=04841&accountNumber=3456712

SEK Validate Bank Giro number

https://api.transferwise.com/v1/validators/bankgiro-number?bankgiroNumber=12345674

HUF

Validate Hungarian bank account number

https://api.transferwise.com/v1/validators/hungarian-account-number?accountNumber=12000000-12345678-00000000

PLN

Validate Polish bank account number

https://api.transferwise.com/v1/validators/polish-account-number?accountNumber=12345678901234567890123456

UAH

Validate Ukrainian bank account number

https://api.transferwise.com/v1/validators/privatbank-account-number?accountNumber=1234

Validate Ukrainian phone number

https://api.transferwise.com/v1/validators/privatbank-phone-number?phoneNumber=123456789

NZD

Validate New Zealand bank account number

https://api.transferwise.com/v1/validators/new-zealand-account-number?accountNumber=03-1587-0050000-00

AED

Validate United Arab Emirates BIC code

https://api.transferwise.com/v1/validators/emirates-bic?bic=BOMLAEAD&iban=AE070331234567890123456

CNY

Validate Chinese Union Pay card number

https://api.transferwise.com/v1/validators/chinese-card-number?cardNumber=6240008631401148

THB

Validate Thailand bank account number

https://api.transferwise.com/v1/validators/thailand-account-number?bankCode=002&accountNumber=9517384260

Banks and Branches

Example Request (Get list of banks for Hong Kong):

curl -X GET https://api.sandbox.transferwise.tech/v1/banks?country=HK \
     -H "Authorization: Bearer <your api token>"

Example Response (Get list of banks for Hong Kong):

{
    "values": [
        {
            "code": "003",
            "title": "STANDARD CHARTERED BANK (HONG KONG) LIMITED"
        },
        {
            "code": "552",
            "title": "AAREAL BANK AG, WIESBADEN, GERMANY"
        },
        {
            "code": "307",
            "title": "ABN AMRO BANK N.V."
        },
        {
            "code": "222",
            "title": "AGRICULTURAL BANK OF CHINA LIMITED"
        },
        {
            "code": "525",
            "title": "ZIBO CITY COMMERCIAL BANK, SHANDONG"
        }
    ]
}

Example Request (Get list of bank branches for a Hong Kong bank with code 003):

curl -X GET https://api.sandbox.transferwise.tech/v1/bank-branches?country=HK&bankCode=003 \
     -H "Authorization: Bearer <your api token>"

Example Response (Get list of bank branches for a Hong Kong bank with code 003):

{
    "country": "HK",
    "values": [
        {
            "code": "251",
            "title": "Quarry Bay Branch [251]",
            "parentCode": "003"
        },
        {
            "code": "983",
            "title": "Canton Road Branch [983]",
            "parentCode": "003"
        },
        {
            "code": "984",
            "title": "Tuen Mun Branch [984]",
            "parentCode": "003"
        },
        {
            "code": "985",
            "title": "Kwun Tong Branch [985]",
            "parentCode": "003"
        }
    ]
}

Get list of banks by country code

List of banks is available for these countries: BD, BR, CZ, CL, EG, GH, HK, ID, IL, IN, JP, KE, LK, MA, NG, NP, PE, PH, RU, SG, TH, VN, ZA

GET https://api.sandbox.transferwise.tech/v1/banks?country=HK

Get list of branches by country and bank code

List of bank branches is available for these countries: BD, GH, HK, IL, IN, JP, LK, SG, VN

GET https://api.sandbox.transferwise.tech/v1/bank-branches?country=HK&bankCode=<bankCode>

Countries and States

Example Request (Get list of allowed countries):

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

Example Response (Get list of allowed countries):

{
    "values": [
        {
            "code": "AL",
            "name": "Albania"
        },
        {
            "code": "DZ",
            "name": "Algeria"
        },
        ...
        {
            "code": "ZW",
            "name": "Zimbabwe"
        },
        {
            "code": "AX",
            "name": "Åland Islands"
        }
    ]
}

Example Request (Get list of states for a country code US):

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

Example Response (Get list of states for a country code US):

{
    "values": [
        {
            "code": "AL",
            "name": "Alabama"
        },
        {
            "code": "AK",
            "name": "Alaska"
        },
        ...
        {
            "code": "PR",
            "name": "Puerto Rico"
        },
        {
            "code": "VI",
            "name": "Virgin Islands"
        }
    ]
}

Get list of countries

List of allowed countries to be used in recipient or user-profile addresses.

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

Get list of states by country code

List of states is available for these countries: US, CA, BR, AU.

GET https://api.sandbox.transferwise.tech/v1/countries/{countryCode}/states

Create AED Recipient

Example Request (AED):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "AED",
          "type": "emirates",
          "legalType": "PRIVATE",
          "details": {
      	   "IBAN": "AE070331234567890123456"
         }
      }'

Send payments to United Arab Emirates.

Private and business recipients are supported.

Recipient type = 'emirates'

Required details: IBAN

Create ARS Recipient

Example Request (ARS):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "ARS",
          "type": "argentina",
          "details": {
           "legalType": "PRIVATE",
           "taxId": "20-34149938-1",
           "accountNumber": "0110482420048200036238"
         }
      }'

Send payments to Argentina.

Private and business recipients are supported.

Recipient type = 'argentina'

Required details:

taxId - Recipient’s CUIT / CUIL (Single Tax Identification/ Single Labor Identification), 11 characters

accountNumber - Recipient’s account CBU, 22 characters (Alias not supported)

Create AUD Recipient

Example Request (AUD australian):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "AUD",
          "type": "australian",
          "details": {
           "address": {
            "city": "New York",
            "countryCode": "US",
            "postCode": "10025",
            "state": "NY",
            "firstLine": "158 Wall Street"
           },
           "legalType": "PRIVATE",
           "bsbCode": "182512",
           "accountNumber": "123456789"
          }
        }'

Example Request for business recipient

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "AUD",
          "type": "australian",
          "details": {
           "address": {
            "city": "New York",
            "countryCode": "US",
            "postCode": "10025",
            "state": "NY",
            "firstLine": "158 Wall Street"
           },
           "legalType": "BUSINESS",
           "bsbCode": "182512",
           "accountNumber": "123456789"
          }
        }'

Example Request for BPay recipient

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "AUD",
          "legalType":"BUSINESS",
          "details":{
           "address": {
            "city": "New York",
            "countryCode": "US",
            "postCode": "10025",
            "state": "NY",
            "firstLine": "158 Wall Street"
           },
           "billerCode":"12345",
           "customerReferenceNumber":"1234567890"
          },
          "type":"australian_bpay"
        }'

Send payments to Australia.

Recipient type = 'australian'

Private and business recipients are supported.

Required details:

bsbCode - 6 digits

accountNumber - 4..9 digits


OR


Recipient type = 'australian_bpay'

Only business recipients are supported.

Required details:

billerCode - 3..10 digits

customerReferenceNumber - 2..20 digits

Create BDT Recipient

Example Request (BDT):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "BDT",
          "type": "bangladesh",
          "details": {
           "legalType": "PRIVATE",
           "bankCode": "015",
           "branchCode": "015270362",
           "accountNumber": "5060011118"
           }
        }'

Send payments to Bangladesh.

Recipient type = 'iban'

Required details: bankCode, branchCode, accountNumber

Lists of banks and branches can be obtained from Banks and Branches endpoints.

You can also get list of bank and branch codes by using /v1/quotes/{quoteId}/account-requirements endpoint.

Create BGN Recipient

Example Request (BGN):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "BGN",
          "type": "iban",
          "details": {
           "legalType": "PRIVATE",
           "IBAN": "BG89370400440532013000"
           }
        }'

Send payments to Bulgaria.

Private and business recipients are supported.

Recipient type = 'iban'

Required details: IBAN

Create BRL Recipient

Example Request (BRL):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "BRL",
          "type": "brazil",
          "details": {
           "legalType": "PRIVATE",
           "bankCode": "218",
           "branchCode": "1234",
           "accountNumber": "12345678-9",
           "accountType": "CHECKING",
           "cpf": "123.456.789-12",
           "phoneNumber": "+55 21 5555 5555"
           }
        }'

Send payments to Brazil.

Recipient type = 'brazil'

Required details: bankCode, branchCode, accountNumber, accountType (CHECKING or SAVINGS), cpf (tax reg no), recipient phone number

Lists of banks and branches can be obtained from Banks and Branches endpoints.

You can also get list of bank and branch codes by using /v1/quotes/{quoteId}/account-requirements endpoint.

Create CAD Recipient

Example Request (CAD):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "CAD",
          "type": "canadian",
          "details": {
           "legalType": "PRIVATE",
           "institutionNumber": "006",
           "transitNumber": "04841",
           "accountNumber": "3456712",
           "accountType": "Checking",
     }
  }'

Send payments to Canada.

Private and business recipients are supported.

Recipient type = 'canadian'

Required details: institutionNumber, transitNumber, accountNumber, accountType (Checking or Saving)

Create CAD Interac Recipient

Example Request (CAD):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "CAD",
          "type": "interac",
          "details": {
           "interacAccount": "<recipient email>",
     }
  }'

Send payments to Canada via Interac.

Private and business recipients are supported. 10,000 CAD max per payment.

Recipient type = 'interac'

Required details: interacAccount

Create CHF Recipient

Example Request (CHF):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "CHF",
          "type": "iban",
          "details": {
           "legalType": "PRIVATE",
           "IBAN": "CH89370400440532013000",
           "town": "Zürich",
           "postCode": 8037
           }
        }'

Send payments to Switzerland.

Private and business recipients are supported.

Recipient type = 'iban'

Required details: IBAN


Required details: IBAN, town, postcode

Where town and postcode are the recipient's home town and postcode.

If the recpient's country does not use a postcode, then please fill it with 0 (zero).

Create CLP Recipient

Example Request (CLP):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "CLP",
          "type": "chile",
          "details": {
           "legalType": "PRIVATE",
           "bankCode": "504",
           "accountNumber": "12345678901234567890",
           "rut": "760864285",
           "accountType": "CHECKING",
           "phoneNumber": "+56 33 555 5555"
           }
        }'

Send payments to Chile.

Private and business recipients are supported.

Recipient type = 'chile'

Required details: bankCode, accountNumber, rut (Rol Único Tributario), accountType (CHECKING, SAVINGS, CUENTA_VISTA), recipient phone number

Lists of banks and branches can be obtained from Banks and Branches endpoints.

You can also get list of bank and branch codes by using /v1/quotes/{quoteId}/account-requirements endpoint.

Create CNY Recipient

Example Request (CNY Alipay id):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": <recipient name>,
          "currency": "CNY",
          "type": "chinese_alipay",
          "details": {
           "legalType": "PRIVATE",
           "accountNumber": "email@example.com"
          }
         }'

Example Request (CNY Weixin recipient):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "CNY",
          "type": "chinese_wechatpay",
          "details": {
           "legalType": "PRIVATE",
           "accountNumber": "+86-12345678901",
          }
         }'

Example Request (CNY business recipient):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "CNY",
          "type": "chinese_local_business",
          "details": {
           "legalType": "BUSINESS",
           "accountNumber": "373929340923",
           "swiftCode": "CHASCNSH",
           "address": {
            "city": "Shanghai",
            "country": "CN",
            "firstLine": "No.999 Zhongshan West Road",
            "postCode": "200051"
           }
          }
         }'

Recipient type = 'chinese_alipay'

Required details: accountNumber - Chinese mobile number or email


OR


Recipient type = 'chinese_wechatpay'

Required details: accountNumber - Chinese mobile number


OR


Recipient type = 'chinese_local_business'

Required details: accountNumber, swiftCode, address of the recipient

Create CZK Recipient

Example Request (CZK Local):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "CZK",
          "type": "czech",
          "details": {
           "legalType": "PRIVATE",
           "prefix": "000000",
           "accountNumber": "5060011118",
           "bankCode": "5500"
           }
        }'

Example Request (CZK IBAN):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "CZK",
          "type": "iban",
          "details": {
           "legalType": "PRIVATE",
           "IBAN": "CZ89370400440532013000"
           }
        }'

Send payments to Czech Republic.

Private and business recipients are supported.


Recipient type = 'czech'

Required details: prefix, accountNumber, bankCode

Lists of banks and branches can be obtained from Banks and Branches endpoints.

You can also get list of bank and branch codes by using /v1/quotes/{quoteId}/account-requirements endpoint.


OR


Recipient type = 'iban'

Required details: IBAN

Create DKK Recipient

Example Request (DKK):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "DKK",
          "type": "iban",
          "details": {
           "legalType": "PRIVATE",
           "IBAN": "DK89370400440532013000"
           }
        }'

Send payments to Denmark.

Private and business recipients are supported.

Recipient type = 'iban'

Required details: IBAN

Create EGP Recipient

Example Request (EGP):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "EGP",
          "type": "iban",
          "details": {
           "legalType": "PRIVATE",
           "IBAN": "EG380019000500000000263180002"
           }
        }'

Send payments to Egypt.

Private and business recipients are supported.

Recipient type = 'iban'

Required details: IBAN

Create EUR Recipient

Example Request (EUR):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "EUR",
          "type": "iban",
          "details": {
           "legalType": "PRIVATE",
           "IBAN": "DE89370400440532013000"
           }
        }'

Send payments to Eurozone countries: Austria, Belgium, Cyprus, Estonia, Finland, France, Germany, Greece, Ireland, Italy, Latvia, Lithuania, Luxembourg, Malta, Netherlands, Portugal, Slovakia, Slovenia, Spain.

Private and business recipients are supported.

Recipient type = 'iban'

Required details: IBAN

Create GBP Recipient

Example Request (GBP Sort Code):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "GBP",
          "type": "sort_code",
          "details": {
           "legalType": "PRIVATE",
           "sortCode": "40-30-20",
           "accountNumber": "12345678"
           }
        }'

Example Request (GBP IBAN):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "GBP",
          "type": "iban",
          "details": {
            "legalType": "PRIVATE",
            "IBAN": "GB89370400440532013000"
           }
        }'

Send payments to United Kingdom.

Private and business recipients are supported.


Recipient type = 'sort_code'

Required details: sortCode, accountNumber


OR


Recipient type = 'iban'

Required details: IBAN

Create GEL Recipient

Example Request (GEL):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "GEL",
          "type": "iban",
          "details": {
           "legalType": "PRIVATE",
           "IBAN": "GE89370400440532013000"
           }
        }'

Send payments to Georgia.

Private and business recipients are supported.

Recipient type = 'iban'

Required details: IBAN

Create GHS Recipient

Example Request (GHS):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "GHS",
          "type": "ghana_local",
          "details": {
           "legalType": "PRIVATE",
           "bankCode": "030100",
           "accountNumber": "0011XXXXXXXXXX"
           }
        }'

Send payments to Ghana.

Private and business recipients are supported.

Recipient type = 'ghana_local'

Required details: bankCode, accountNumber

Lists of banks and branches can be obtained from Banks and Branches endpoints.

You can also get list of bank and branch codes by using /v1/quotes/{quoteId}/account-requirements endpoint.

Create HKD Recipient

Example Request (HKD):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "accountHolderName": "<recipient name>",
          "currency": "HKD",
          "type": "hongkong",
          "details": {
           "legalType": "PRIVATE",
           "bankCode": "307",
           "accountNumber": "005-231289-112"
           }
        }'

Send payments to Hong Kong.

Private and business recipients are supported.

Recipient type = 'hongkong'

Required details: bankCode, accountNumber

Lists of banks and branches can be obtained from Banks and Branches endpoints.

You can also get list of bank and branch codes by using /v1/quotes/{quoteId}/account-requirements endpoint.

Create HRK Recipient

Example Request:

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "HRK",
          "type": "iban",
          "details": {
           "legalType": "PRIVATE",
           "IBAN": "HR89370400440532013000"
           }
        }'

Send payments to Croatia.

Private and business recipients are supported.

Recipient type = 'iban'

Required details: IBAN

Create HUF Recipient

Example Request (HUF Local):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "HUF",
          "type": "hungarian",
          "details": {
           "legalType": "PRIVATE",
           "accountNumber": "12000000-12345678-00000000"
           }
        }'

Example Request (HUF IBAN):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "HUF",
          "type": "iban",
          "details": {
           "legalType": "PRIVATE",
           "IBAN": "HU89370400440532013000"
           }
        }'

Send payments to Hungary.

Private and business recipients are supported.


Recipient type = 'hungarian'

Required details: accountNumber


OR


Recipient type = 'iban'

Required details: IBAN

Create IDR Recipient

Example Request (IDR):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "IDR",
          "type": "indonesian",
          "details": {
           "legalType": "PRIVATE",
           "bankCode": "610306",
           "accountNumber": "6789112345678"
           }
        }'

Send payments to Indonesia.

Private and business recipients are supported.

Recipient type = 'indonesian'

Required details: bankCode, accountNumber

Lists of banks and branches can be obtained from Banks and Branches endpoints.

You can also get list of bank and branch codes by using /v1/quotes/{quoteId}/account-requirements endpoint.

Create ILS Recipient

Example Request (ILS IBAN):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
        "profile": <your profile id>,
        "accountHolderName": "<recipient name>",
        "currency": "ILS",
        "type": "israeli_local",
        "details": {
         "legalType": "PRIVATE",
         "IBAN": "IL620108000000099999999"
         }
      }'

Send payments to Israel.

Private and business recipients are supported.


Recipient type = 'israeli_local'

Required details: IBAN

Create INR Recipient

Example Request (INR):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "INR",
          "type": "indian",
          "details": {
           "legalType": "PRIVATE",
           "ifscCode": "YESB0236041",
           "accountNumber": "678911234567891",
           }
        }'

Send payments to India.

Private and business recipients are supported.

Recipient type = 'indian'

Required details: ifscCode, accountNumber

Lists of banks and branches can be obtained from Banks and Branches endpoints.

You can also get list of bank and branch codes by using /v1/quotes/{quoteId}/account-requirements endpoint.

Create JPY Recipient

Example Request (JPY):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "JPY",
          "type": "japanese",
          "details": {
           "legalType": "PRIVATE",
           "bankCode": "6470",
           "branchCode": "100",
           "accountType": "CURRENT",
           "accountNumber": "1234567"
           }
        }'

Send payments to Japan.

Private and business recipients are supported.

Recipient type = 'japanese'

Required details: bankCode, branchCode accountNumber, accountType (CURRENT, SAVINGS, CHECKING),

Lists of banks and branches can be obtained from Banks and Branches endpoints.

You can also get list of bank and branch codes by using /v1/quotes/{quoteId}/account-requirements endpoint.

Create KES Recipient

Example Request (KES Bank Account):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "KES",
          "type": "kenya_local",
          "details": {
           "legalType": "PRIVATE",
           "bankCode": "35",
           "accountNumber": "0023183991919"
           }
        }'

Example Request (KES Mobile MPESA):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "KES",
          "type": "kenya_mobile",
          "details": {
           "legalType": "PRIVATE",
           "accountNumber": "2547XXXXXXXX"
           }
        }'

Send payments to Kenya.

Private and business recipients are supported. However please note that only individuals can hold MPESA accounts.


Recipient type = 'kenya_local'

Required details: bankCode, accountNumber

Lists of banks and branches can be obtained from Banks and Branches endpoints.

You can also get list of bank and branch codes by using /v1/quotes/{quoteId}/account-requirements endpoint.


OR


Recipient type = 'kenya_mobile'

Required details: accountNumber - mobile number

Create KRW Recipient

Example Request (KRW PayGate):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipients name>",
          "currency": "KRW",
          "type": "south_korean_paygate",
          "details": {
           "legalType": "PRIVATE",
           "bankCode": "BUSAN_032",
           "accountNumber": "1254693521232",
           "dateOfBirth" : "yyyy-mm-dd",
           "email": "<recipients email>"
           }
        }'

Example Request (KRW PayGate to Business):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient business name>",
          "currency": "KRW",
          "type": "south_korean_paygate_business",
          "details": {
           "legalType": "BUSINESS",
           "bankCode" : "BUSAN_032",
           "accountNumber": "1254693521232"
           }
        }'

Send payments to South Korea.

Private and business recipients are supported.


Recipient type = 'south_korean_paygate'

Required details: bankCode, accountNumber, dateOfBirth, email

Lists of banks and branches can be obtained from Banks and Branches endpoints.

You can also get list of bank and branch codes by using /v1/quotes/{quoteId}/account-requirements endpoint.


OR


Recipient type = 'south_korean_paygate_business'

Required details: bankCode, accountNumber

Create LKR Recipient

Example Request (LKR):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "LKR",
          "type": "srilanka",
          "details": {
           "legalType": "PRIVATE",
           "bankCode": "7214",
           "branchCode": "100",
           "accountNumber": "5060011118"
           }
        }'

Send payments to Sri Lanka.

Private and business recipients are supported.

Recipient type = 'srilanka'

Required details: bankCode, branchCode, accountNumber

Lists of banks and branches can be obtained from Banks and Branches endpoints.

You can also get list of bank and branch codes by using /v1/quotes/{quoteId}/account-requirements endpoint.

Create MAD Recipient

Example Request (MAD):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "MAD",
          "type": "morocco",
          "details": {
           "legalType": "PRIVATE",
           "bankCode": "BCMAMAMC",
           "accountNumber": "123456789012345678901234"
           }
        }'

Send payments to Morocco.

Private and business recipients are supported. 260,000 MAD per transaction

Recipient type = 'morocco'

Required details: bankCode, accountNumber

Lists of banks and branches can be obtained from Banks and Branches endpoints.

You can also get list of bank and branch codes by using /v1/quotes/{quoteId}/account-requirements endpoint.

Create MXN Recipient

Example Request (MXN):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "MXN",
          "type": "mexican",
          "details": {
           "legalType": "PRIVATE",
           "clabe": "032180000118359719"
           }
        }'

Send payments to Mexico.

Private and business recipients are supported.

Recipient type = 'mexican'

Required details: clabe

Create MYR Recipient

Example Request (MYR):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "MYR",
          "type": "malaysian",
          "details": {
           "legalType": "PRIVATE",
           "swiftCode": "ABNAMYKL",
           "accountNumber": "159012938613"
           }
        }'

Send payments to Malaysia.

Private and business recipients are supported. Maximum amount is 10,000,000 MYR per payment.

Recipient type = 'malaysian'

Required details: swiftCode, accountNumber

Create NGN Recipient

Example Request (NGN):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "NGN",
          "type": "nigeria",
          "details": {
           "legalType": "PRIVATE",
           "bankCode": "044",
           "accountNumber": "0584412903"
           }
        }'

Send payments to Nigeria.

Private and business recipients are supported. Maximum amount is 2,000,000 NGN per payment.

Recipient type = 'nigeria'

Required details: bankCode, accountNumber

Lists of banks and branches can be obtained from Banks and Branches endpoints.

You can also get list of bank and branch codes by using /v1/quotes/{quoteId}/account-requirements endpoint.

Create NOK Recipient

Example Request (NOK):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "NOK",
          "type": "iban",
          "details": {
           "legalType": "PRIVATE",
           "IBAN": "DE89370400440532013000"
           }
        }'

Send payments to Norway.

Private and business recipients are supported.

Recipient type = 'iban'

Required details: IBAN

Create NPR Recipient

Example Request (NPR):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "NPR",
          "type": "nepal",
          "legalType": "PRIVATE",
          "details": {
           "bankCode": "977056",
           "accountNumber": "1234567890"
           }
        }'

Send payments to Nepal.

Private recipients are supported. 1mln NPR per transaction / per month for individual account.

Recipient type = 'nepal'

Required details: bankCode, accountNumber

Lists of banks and branches can be obtained from Banks and Branches endpoints.

You can also get list of bank and branch codes by using /v1/quotes/{quoteId}/account-requirements endpoint.

Create NZD Recipient

Example Request (NZD):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "NZD",
          "type": "newzealand",
          "details": {
           "legalType": "PRIVATE",
           "accountNumber": "03-1587-0050000-00"
           }
        }'

Send payments to New Zealand.

Recipient type = 'newzealand'

Required details: accountNumber

Create PHP Recipient

Example Request (PHP):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "PHP",
          "type": "philippines",
          "details": {
           "legalType": "PRIVATE",
           "bankCode": "AMA",
           "accountNumber": "0044XXXXXXXX",
           "address" : {
              "country": "GB",
              "city": "London",
              "postCode": "10025",
              "firstLine": "50 Branson Ave"
             }
          }
        }'

Send payments to Philippines.

Private and business recipients are supported. 480,000 PHP per payment.

Recipient type = 'philippines'

Required details: bankCode, accountNumber, recipient address

Lists of banks and branches can be obtained from Banks and Branches endpoints.

You can also get list of bank and branch codes by using /v1/quotes/{quoteId}/account-requirements endpoint.

Create PKR Recipient

Example Request (PKR):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "PKR",
          "type": "iban",
          "details": {
           "legalType": "PRIVATE",
           "IBAN": "PK89370400440532013000"
           }
        }'

Send payments to Pakistan. Max 1 million PKR per payment.

Recipient type = 'iban'

Required details: IBAN

Create PLN Recipient

Example Request (PLN IBAN):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "PLN",
          "type": "iban",
          "details": {
           "legalType": "PRIVATE",
           "IBAN": "PL89370400440532013000"
           }
        }'

Example Request (PLN Local):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "PLN",
          "type": "polish",
          "details": {
           "legalType": "PRIVATE",
           "accountNumber": "109010140000071219812874"
           }
        }'

Send payments to Poland.

Private and business recipients are supported.


Recipient type = 'iban'

Required details: IBAN


OR


Recipient type = 'polish'

Required details: accountNumber

Create RON Recipient

Example Request (RON):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "RON",
          "type": "iban",
          "details": {
           "legalType": "PRIVATE",
           "IBAN": "RO89370400440532013000"
           }
        }'

Send payments to Romania.

Private and business recipients are supported.

Recipient type = 'iban'

Required details: IBAN

Create RUB Recipient

Example Request (RUB):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "RUB",
          "type": "russiarapida",
          "details": {
           "legalType": "PRIVATE",
           "bankCode": "044525290",
           "accountNumber": "40820810999999999999",
           "russiaRegion": "ALTAIKRAI",
           "address" : {
              "country": "GB",
              "city": "London",
              "postCode": "10025",
              "firstLine": "50 Branson Ave"
             }
           }
        }'

Send payments to Russia.

Recipient type = 'russiarapida'

Required details: bankCode, accountNumber, region, recipient address.

You have to provide first, last and patronymic names in Cyrillic, in order for your transfer to be accepted by the recipient bank. (unless the recipient is registered at the bank with no patronymic)

You can get list of bank, region and country codes by using /v1/quotes/{quoteId}/account-requirements endpoint.

Lists of banks and branches can be obtained from Banks and Branches endpoints.

Create SEK Recipient

Example Request (SEK IBAN):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "SEK",
          "type": "iban",
          "details": {
           "legalType": "PRIVATE",
           "IBAN": "SE89370400440532013000"
           }
        }'

Example Request (SEK Local):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "SEK",
          "type": "sweden_local",
          "details": {
           "legalType": "PRIVATE",
           "clearingNumber": "1234",
           "accountNumber": "1234567"
           }
        }'

Example Request (SEK BankGiro):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "SEK",
          "type": "bankgiro",
          "details": {
           "legalType": "PRIVATE",
           "bankgiroNumber": "1234-5678"
           }
        }'

Send payments to Sweden.

Private and business recipients are supported.


Recipient type = 'iban'

Required details: IBAN


OR


Recipient type = 'sweden_local'

Required details: clearingNumber, accountNumber


OR


Recipient type = 'bankgiro'

Required details: bankgiroNumber

Create SGD Recipient

Example Request (SGD):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "SGD",
          "type": "singapore",
          "details": {
           "legalType": "PRIVATE",
           "bankCode": "7418",
           "accountNumber": "1238827822"
           }
        }'

Send payments to Singapore.

Private and business recipients are supported.

Recipient type = 'singapore'

Required details: bankCode, accountNumber

Lists of banks and branches can be obtained from Banks and Branches endpoints.

You can also get list of bank and branch codes by using /v1/quotes/{quoteId}/account-requirements endpoint.

Create THB Recipient

Example Request (THB):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "THB",
          "type": "thailand",
          "details": {
           "legalType": "PRIVATE",
           "bankCode": "002",
           "accountNumber": "9517384260"
           "address" : {
              "country": "GB",
              "city": "London",
              "postCode": "10025",
              "firstLine": "50 Branson Ave"
             }
           }
        }'

Send payments to Thailand. Max 2 mln THB per payment.

Private and business recipients are supported.

Recipient type = 'thailand'

Required details: bankCode, accountNumber

Lists of banks and branches can be obtained from Banks and Branches endpoints.

You can also get list of bank and branch codes by using /v1/quotes/{quoteId}/account-requirements endpoint.

Create TRY Recipient

Example Request (TRY):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "TRY",
          "type": "turkish_earthport",
          "details": {
           "legalType": "PRIVATE",
           "IBAN": "TR330006100519786457841326"
           }
        }'

Send payments to Turkey.

Private and business recipients are supported. 1 000 000 TRY per payment.

Recipient type = 'turkish_earthport'

Required details: IBAN

Create UAH Recipient

Example Request (UAH):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{
          "profile": {{profileId}},
          "accountHolderName": "<recipient name>",
          "currency": "UAH",
          "type": "privatbank",
          "details": {
            "legalType": "PRIVATE",
            "phoneNumber": "777210012",
            "accountNumber": "2662",
            "address": {
              "firstLine": "1 A ROAD",
              "country": "UA",
              "city": "Lviv",
              "postCode": 79007
        }
    }
}'

Send payments to Ukraine. Maximum 1,2m UAH per payment.

Recipient type = 'privatbank'

Required details:

  • phoneNumber = Use phone number registered in Privat Bank
  • accountNumber = Last 4 digits of UAH PrivatBank card

Create USD Recipient

Example Request (USD):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "USD",
          "type": "aba",
          "details": {
           "legalType": "PRIVATE",
           "abartn": "111000025",
           "accountNumber": "12345678",
           "accountType": "CHECKING",
           "address" : {
              "country": "GB",
              "city": "London",
              "postCode": "10025",
              "firstLine": "50 Branson Ave"
             }
           }
        }'

Send payments to USA.

Private and business recipients are supported. Max 1 Million USD per payment.

Recipient type = 'aba'

Required details:

  • abartn = ACH Routing number
  • accountNumber = Recipient bank account number
  • accountType = CHECKING or SAVINGS
  • address = Recipient address

Create VND Recipient

Example Request (VND):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "VND",
          "type": "vietname_earthport",
          "details": {
           "legalType": "PRIVATE",
           "swiftCode": "ABBKVNVX",
           "branchCode": "001",
           "accountNumber": "1234567890"
           }
        }'

Send payments to Vietnam.

Private and business recipients are supported.

Recipient type = 'vietname_earthport'

Required details: swiftCode, branchCode, accountNumber

Lists of banks and branches can be obtained from Banks and Branches endpoints.

You can also get list of bank and branch codes by using /v1/quotes/{quoteId}/account-requirements endpoint.

Create ZAR Recipient

Example Request (ZAR):

curl -X POST "https://api.sandbox.transferwise.tech/v1/accounts" \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "accountHolderName": "<recipient name>",
          "currency": "ZAR",
          "type": "southafrica",
          "details": {
           "legalType": "PRIVATE",
           "swiftCode": "ALBRZAJJ",
           "accountNumber": "0000000052312891"
           }
        }'

Send payments to South African Republic.

Private and business recipients are supported.

Recipient type = 'southafrica'

Required details: swiftCode, accountNumber

You can get list of bank codes by using /v1/quotes/{quoteId}/account-requirements endpoint.

Lists of banks and branches can be obtained from Banks and Branches endpoints.

Create Email Recipient

Example Request (Create email recipient):

curl -X POST https://api.sandbox.transferwise.tech/v1/accounts \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>, 
          "accountHolderName": "Ann Johnson",
          "currency": "EUR", 
          "type": "email", 
           "details": { 
              "email": "ann.johnson@gmail.com"
           } 
         }'

Example Response (Lookup email recipient):

{
    "id": 13967196,
    "business": null,
    "profile": <your profile id>,
    "accountHolderName": "Ann Johnson",
    "currency": "EUR",
    "country": null,
    "type": "email",
    "details": {
        "address": {
            "country": null,
            "countryCode": null,
            "firstLine": null,
            "postCode": null,
            "city": null,
            "state": null
        },
        "email": "ann.johnson@gmail.com",
        "legalType": "PRIVATE",
        "accountNumber": null,
        "sortCode": null,
        "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": false
}

If you don't know recipient bank account details you can set up email recipient so that Wise will collect bank details directly from the recipient.

Wise will email your recipient with a link to collect their bank account details. Once your recipient provides bank account details securely to Wise we are able to complete your transfer.

https://wise.com/help/articles/2932105/can-i-send-money-to-someone-with-only-their-email-address

Transfers

Create

Example Request:

curl -X POST https://api.sandbox.transferwise.tech/v1/transfers \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "sourceAccount": <refund recipient account id>,   
          "targetAccount": <recipient account id>,   
          "quoteUuid": <v2 quote id>,
          "customerTransactionId": "<the unique identifier you generated for the transfer attempt>",
          "details" : {
              "reference" : "to my friend",
              "transferPurpose": "verification.transfers.purpose.pay.bills",
              "transferPurposeSubTransferPurpose": "verification.sub.transfers.purpose.pay.interpretation.service"
              "sourceOfFunds": "verification.source.of.funds.other"
            } 
         }'

Example Response:

{
    "id": 468956,
    "user": <your user id>,
    "targetAccount": <recipient account id>,
    "sourceAccount": null,
    "quote": null,
    "quoteUuid": <v2 quote id>,
    "status": "incoming_payment_waiting",
    "reference": "to my friend",
    "rate": 0.9065,
    "created": "2018-08-28 07:43:55",
    "business": <your business profile id>,
    "transferRequest": null,
    "details": {
        "reference": "to my friend"
    },
    "hasActiveIssues": false,
    "sourceCurrency": "EUR",
    "sourceValue": 661.89,
    "targetCurrency": "GBP",
    "targetValue": 600,
    "customerTransactionId": "bd244a95-dcf8-4c31-aac8-bf5e2f3e54c0"
}

A transfer is a payment order to recipient account based on a quote. Once created, a transfer needs to be funded within the next five working days. Otherwise, it will be automatically canceled.

Request

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

Field Description Format
sourceAccount (optional) Refund recipient account id. Integer
targetAccount Recipient account id. You can create multiple transfers to same recipient account. Integer
quoteUuid V2 quote id. You can only create one transfer per one quote.
You cannot use same quote ID to create multiple transfers.
Text
customerTransactionId This is required to perform idempotency check to avoid duplicate transfers in case of network failures or timeouts. UUID
details.reference (optional) Recipient will see this reference text in their bank statement. Maximum allowed characters depends on the currency route. Business Payments Tips article has a full list. Text
details.transferPurpose (conditionally required) For example when target currency is THB. See more about conditions at Transfers.Requirements Text
details.transferPurposeSubTransferPurpose (conditionally required) For example when target currency is CNY. See more about conditions at Transfers.Requirements Text
details.sourceOfFunds (conditionally required) For example when target currency is USD and transfer amount exceeds 80k. See more about conditions at Transfers.Requirements Text

There are two options to deal with conditionally required fields:

  • Always call `transfer-requirements` endpoint and submit values only if indicated so.
  • Always provide values for these fields based on a hard coded list. It is possible these fields change over time so hard coding the options does create some risk of issues.

Response

You need to save the transfer id for tracking its status later via webhooks.

Field Description Format
id Transfer id Integer
user Your user id Integer
targetAccount Recipient account id Integer
sourceAccount Refund recipient account id Integer
quote v1 quote id (where applicable) Integer
quoteUuid v2 quote id Text
status Transfer current status Text
reference Deprecated, use details.reference instead Text
rate Exchange rate value Decimal
created Timestamp when transfer was created Timestamp
business Your business profile id
transferRequest Not used Integer
details.reference Payment reference text Text
hasActiveIssues Are there any pending issues which stop executing the transfer? Boolean
sourceCurrency Source currency code Text
sourceValue Transfer amount in source currency Decimal
targetCurrency Target currency code Text
targetValue Transfer amount in target currency Decimal
customerTransactionId Unique identifier randomly generated per transfer request by the calling client UUID

Avoiding duplicate transfers

We use customerTransactionId field to avoid duplicate transfer requests. If your initial call to create a transfer fails (error or timeout) then you should retry the call using the same value in the customerTransactionId field that you used in the original call. This way we can treat subsequent retry messages as repeat messages and will not create duplicate transfers to your account should one have succeeded before. You should not retry indefinitely but use a sensible limit, perhaps with a back-off approach.

Fund

Example Request:

curl -X POST https://api.sandbox.transferwise.tech/v3/profiles/{profileId}/transfers/{transferId}/payments \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "type": "BALANCE"   
         }'

Example Response:

{
  "type": "BALANCE",
  "status": "COMPLETED",
  "errorCode": null
}

This API call is the final step for executing payouts, but is only required if you are settling transfers from a Wise multi-currency account. Upon calling the endpoint Wise will debit funds from your multi-currency account and start processing your transfer. If your multi-currency account does not have the required funds to complete the action then this call will fail with an "insufficient funds" error.

This is not required if you fund transfers using the following methods:

  • BANK_TRANSFER - where you send the funds directly to Wise's bank account.
  • TRUSTED_PRE_FUND_BULK - where you are using a prefunded bulk settlement approach.
  • Another option unique to your integration.

If you are unsure if you need this please contact your Wise implementation team to clarify.

Request

POST https://api.sandbox.transferwise.tech/v3/profiles/{profileId}/transfers/{transferId}/payments

Use transfer id that you obtained in previous step.

Field Description Format
type "BALANCE".
This indicates that your transfer will be funded from your multi-currency account.
Text

Response

You need to save transfer id for tracking its status later.

Field Description Format
type "BALANCE" Text
status "COMPLETED" or "REJECTED" Text
errorCode Failure reason. For example "balance.payment-option-unavailable" Text

Cancel

Example Request:

curl -X PUT https://api.sandbox.transferwise.tech/v1/transfers/{transferId}/cancel \
     -H "Authorization: Bearer <your api token>" 

Example Response:

{
  "id": 16521632,
  "user": 4342275,
  "targetAccount": 8692237,
  "sourceAccount": null,
  "quote": 657171,
  "status": "cancelled",
  "reference": "reference text",
  "rate": 0.89,
  "created": "2017-11-24 10:47:49",
  "business": null,
  "transferRequest": null,
  "details": {
    "reference": "Testing"
  },
  "hasActiveIssues": false,
  "sourceCurrency": "EUR",
  "sourceValue": 0,
  "targetCurrency": "GBP",
  "targetValue": 150,
  "customerTransactionId": "54a6bc09-cef9-49a8-9041-f1f0c654cd88"
}

Only transfers which are not funded can be cancelled. Cancellation is final - it can not be undone.

Request

PUT https://api.sandbox.transferwise.tech/v1/transfers/{transferId}/cancel

Use transfer id that you obtained when creating a transfer.

Response

Field Description Format
id Transfer id Integer
user Your user id Integer
targetAccount Recipient account id Integer
sourceAccount Refund recipient account id Integer
quote Quote id Integer
status Transfer current status Text
reference Deprecated, use details.reference instead Text
rate Exchange rate value Decimal
created Timestamp when transfer was created Timestamp
business Your business profile id
transferRequest Not used Integer
details.reference Payment reference text Text
hasActiveIssues Are there any pending issues which stop executing the transfer? Boolean
sourceCurrency Source currency code Text
sourceValue Transfer amount in source currency Decimal
targetCurrency Target currency code Text
targetValue Transfer amount in target currency Decimal
customerTransactionId Unique identifier randomly generated per transfer request by the calling client UUID

Get by Id

Example Request:

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

Example Response:

{
  "id": 15574445,
  "user": 294205,
  "targetAccount": 7993919,
  "sourceAccount": null,
  "quote": 113379,
  "status": "incoming_payment_waiting",
  "reference": "good times",
  "rate": 1.2151,
  "created": "2017-03-14 15:25:51",
  "business": null,
  "transferRequest": null,
  "details": {
    "reference": "good times"
  },
  "hasActiveIssues": false,
  "sourceValue": 1000,
  "sourceCurrency": "EUR",
  "targetValue": 895.32,
  "targetCurrency": "GPB",
  "customerTransactionId": "6D9188CF-FA59-44C3-87A2-4506CE9C1EA3"
}

Get transfer info by id. Since we don't have push notifications yet, you can poll this endpoint to track your transfer status.

Request

GET https://api.sandbox.transferwise.tech/v1/transfers/{transferId}

Response

Field Description Format
id Transfer id Integer
user Your user id Integer
targetAccount Recipient account id Integer
sourceAccount Refund recipient account id Integer
quote Quote id Integer
status Transfer current status Text
reference Deprecated, use details.reference instead Text
rate Exchange rate value Decimal
created Timestamp when transfer was created Timestamp
business Your business profile id
transferRequest Not used Integer
details.reference Payment reference text Text
hasActiveIssues Are there any pending issues which stop executing the transfer? Boolean
sourceCurrency Source currency code Text
sourceValue Transfer amount in source currency Decimal
targetCurrency Target currency code Text
targetValue Transfer amount in target currency Decimal
customerTransactionId Unique identifier randomly generated per transfer request by the calling client UUID

Get Delivery Estimate

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

Request

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

Response

Field Description Format
estimatedDeliveryDate Estimated time when funds will arrive to recipient's bank account Timestamp

Get Receipt PDF

Example Request:

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

Example Response:

Receipt presented as application/pdf content-type

Download transfer confirmation receipt in PDF format for transfers that are in status outgoing_payment_sent.

Request

GET https://api.sandbox.transferwise.tech/v1/transfers/{transferId}/receipt.pdf

Response

Transfer confirmation receipt in PDF format.

List

Example Request:

curl -X GET https://api.sandbox.transferwise.tech/v1/transfers?offset=0&limit=100&profile=<your profile id>&status=funds_refunded&createdDateStart=2018-12-15&createdDateEnd=2018-12-30  \
     -H "Authorization: Bearer <your api token>" 

Example Response:

[
  {
    "id": 15574445,
    "user": 294205,
    "targetAccount": 7993919,
    "sourceAccount": null,
    "quote": 113379,
    "status": "funds_refunded",
    "reference": "good times",
    "rate": 1.1179,
    "created": "2018-12-16 15:25:51",
    "business": null,
    "transferRequest": null,
    "details": {
      "reference": "good times"
    },
    "hasActiveIssues": false,
    "sourceValue": 1000,
    "sourceCurrency": "EUR",
    "targetValue": 895.32,
    "targetCurrency": "GPB",
    "customerTransactionId": "6D9188CF-FA59-44C3-87A2-4506CE9C1EA3"
  },
  {
    "id": 14759252,
    "user": 294205,
    "targetAccount": 5570192,
    "sourceAccount": null,
    "quote": 113371,
    "status": "funds_refunded",
    "reference": "",
    "rate": 1.1179,
    "created": "2018-12-26 15:25:51",
    "business": null,
    "transferRequest": null,
    "details": {
      "reference": ""
    },
    "hasActiveIssues": false,
    "sourceValue": 1000,
    "sourceCurrency": "EUR",
    "targetValue": 895.32,
    "targetCurrency": "GPB",
    "customerTransactionId": "785C67AD-7E29-4DBC-9D4A-4C45D4D5333A"
  }
]

Get the list of transfers for given user's profile (defaults to user's personal profile).

You can add query parameters to specify user's profile (personal or business), time period and/or payment status.

For example you can query:

  • all failed payments created since last week
  • all completed payments created since yesterday

Request

GET https://api.sandbox.transferwise.tech/v1/transfers/?offset=0&limit=100&profile=<your profile id>&status=funds_refunded&sourceCurrency=EUR&createdDateStart=2018-12-15T01:30:00.000Z&createdDateEnd=2018-12-30T01:30:00.000Z

Field Description Format
profile User profile id. If parameter is omitted, defaults to user's personal profile Integer
status Status code or codes list (as comma separated value list) to filter returned transfers with. See Track transfer status for complete list of statuses. Text
sourceCurrency Source currency code Text
targetCurrency Target currency code Text
createdDateStart Starting date to filter transfers, inclusive of the provided date. yyyy-MM-dd'T'HH:mm:ss.SSS'Z'
createdDateEnd Ending date to filter transfers, inclusive of the provided date. yyyy-MM-dd'T'HH:mm:ss.SSS'Z'
limit Maximum number of records to be returned in response Integer
offset Starting record number Integer

Response

Field Description Format
id Transfer id Integer
user Your user id Integer
targetAccount Recipient account id Integer
sourceAccount Refund recipient account id Integer
quote Quote id Integer
status Transfer current status Text
reference Deprecated, use details.reference instead Text
rate Exchange rate value Decimal
created Timestamp when transfer was created Timestamp
business Your business profile id
transferRequest Not used Integer
details.reference Payment reference text Text
hasActiveIssues Are there any pending issues which stop executing the transfer? Boolean
sourceCurrency Source currency code Text
sourceValue Transfer amount in source currency Decimal
targetCurrency Target currency code Text
targetValue Transfer amount in target currency Decimal
customerTransactionId Unique identifier assigned by customer. Used for idempotency check purposes. UUID

Requirements

Example Request:

curl -X POST https://api.sandbox.transferwise.tech/v1/transfer-requirements \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
            "targetAccount": <recipient account id>,
            "quoteUuid": <quote uuid>,
            "details": {
              "reference": "good times",
              "sourceOfFunds": "verification.source.of.funds.other",
              "sourceOfFundsOther": "Trust funds"
            },
            "customerTransactionId": "6D9188CF-FA59-44C3-87A2-4506CE9C1EA3"
         }'

Example Response:

[
  {
    "type": "transfer",
    "fields": [
      {
        "name": "Transfer reference",
        "group": [
          {
            "key": "reference",
            "name": "Transfer reference",
            "type": "text",
            "refreshRequirementsOnChange": false,
            "required": false,
            "displayFormat": null,
            "example": null,
            "minLength": null,
            "maxLength": 10,
            "validationRegexp": null,
            "validationAsync": null,
            "valuesAllowed": null
          }
        ]
      },
      {
        "name": "Transfer purpose",
        "group": [
          {
            "key": "transferPurpose",
            "name": "Transfer purpose",
            "type": "select",
            "refreshRequirementsOnChange": true,
            "required": true,
            "displayFormat": null,
            "example": null,
            "minLength": null,
            "maxLength": null,
            "validationRegexp": null,
            "validationAsync": null,
            "valuesAllowed": [
              {
                "key": "verification.transfers.purpose.purchase.property",
                "name": "Buying property abroad"
              },
              {
                "key": "verification.transfers.purpose.pay.bills",
                "name": "Rent or other property expenses"
              },
              {
                "key": "verification.transfers.purpose.mortgage",
                "name": "Mortgage payment"
              },
              {
                "key": "verification.transfers.purpose.pay.tuition",
                "name": "Tuition fees or studying expenses"
              },
              {
                "key": "verification.transfers.purpose.send.to.family",
                "name": "Sending money home to family"
              },
              {
                "key": "verification.transfers.purpose.living.expenses",
                "name": "General monthly living expenses"
              },
              {
                "key": "verification.transfers.purpose.other",
                "name": "Other"
              }
            ]
          },
          {
            "key": "transferPurposeSubTransferPurpose",
            "name": "Please select a specific reason for your transfer",
            "type": "select",
            "refreshRequirementsOnChange": true,
            "required": true,
            "displayFormat": null,
            "example": null,
            "minLength": null,
            "maxLength": null,
            "validationRegexp": null,
            "validationAsync": null,
            "valuesAllowed": [
              {
                  "key": "INTERPRETATION_SERVICE",
                  "name": "Interpretation service"
              },
              {
                  "key": "TRANSLATION_SERVICE",
                  "name": "Translation service"
              },
              {
                  "key": "HUMAN_RESOURCE_SERVICE",
                  "name": "Human resource service"
              },
              {
                  "key": "ESTATE_AGENCY_SERVICE",
                  "name": "Estate agency service"
              },
              {
                  "key": "SOFTWARE_DEVELOPMENT_SERVICE",
                  "name": "Software development service"
              },
              {
                  "key": "WEB_DESIGN_OR_DEVELOPMENT_SERVICE",
                  "name": "Web design or development service"
              },
              {
                  "key": "DRAFTING_LEGAL_SERVICE",
                  "name": "Drafting legal service"
              },
              {
                  "key": "LEGAL_RELATED_CERTIFICATION_SERVICE",
                  "name": "Legal related certification service"
              },
              {
                  "key": "ACCOUNTING_SERVICE",
                  "name": "Accounting service"
              },
              {
                  "key": "TAX_SERVICE",
                  "name": "Tax service"
              },
              {
                  "key": "ARCHITECTURAL_DECORATION_DESIGN_SERVICE",
                  "name": "Architectural decoration design service"
              },
              {
                  "key": "ADVERTISING_SERVICE",
                  "name": "Advertising service"
              },
              {
                  "key": "MARKET_RESEARCH_SERVICE",
                  "name": "Market research service"
              },
              {
                  "key": "EXHIBITION_BOOTH_SERVICE",
                  "name": "Exhibition booth service"
              }
            ]
          }
        ]
      },
      {
        "name": "Source of funds",
        "group": [
          {
            "key": "sourceOfFunds",
            "name": "Source of funds",
            "type": "select",
            "refreshRequirementsOnChange": true,
            "required": true,
            "displayFormat": null,
            "example": null,
            "minLength": null,
            "maxLength": null,
            "validationRegexp": null,
            "validationAsync": null,
            "valuesAllowed": [
              {
                "key": "verification.source.of.funds.salary",
                "name": "Salary"
              },
              {
                "key": "verification.source.of.funds.investment",
                "name": "Investments (stocks, properties, etc.)"
              },
              {
                "key": "verification.source.of.funds.inheritance",
                "name": "Inheritance"
              },
              {
                "key": "verification.source.of.funds.loan",
                "name": "Loan"
              },
              {
                "key": "verification.source.of.funds.other",
                "name": "Other"
              }
            ]
          }
        ]
      }
    ]
  }
]

Almost every region has its own specific nuances when it comes to the nitty gritty details of domestic payment systems and money transfer regulations. The maximum allowed length of reference text is a good example. The US payment system, ACH, supports 10 characters only, but transfers within Mexico allow up to 100 characters, and so on.

The same is true for requirements arising from Anti Money Laundering regulations adopted in different countries. Depending on the chosen currencies and the amount to be transferred, either in one go or cumulatively over time, Wise may require more details about the customer's source of funds or transfer purpose, for example.

The endpoint /transfer-requirements exposes all these specific requirements based on the sender, the specific quote and selected target recipient account.

To make sure that processing of your customer's transfers does not get delayed because of missing details, we highly recommend to verify the transfer requirements before submitting any transfer and collecting the data we request from the user using the returned dynamic form.

Request

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

1.Prepare the request body to create transfer object first. Now post this request body to the transfer-requirements endpoint to figure out if there are any other required fields.

2.Analyze the returned list of fields. Our example includes reference, sourceOfFunds and transferPurpose fields. Field 'reference' is optional. Fields 'sourceOfFunds' and 'transferPurpose' are required and both have refreshRequirementsOnChange=true which indicates that there could be additional fields required depending on the selected value.

In our example you will have to POST request to/v1/transfer-requirements` second time as well with values set for 'transferPurpose' and 'sourceOfFunds'. So in case you set sourceOfFunds = 'verification.source.of.funds.other' then another text field called "sourceOfFundsOther" is also required where you need to specify the details in free format.

3.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 a transfer object. For example this is a valid request to create a transfer.
POST /v1/transfers:

{
"targetAccount": ,
"quote": ,
"details": {
"reference": "good times",
"sourceOfFunds": "verification.source.of.funds.other",
"sourceOfFundsOther": "Trust funds"
},
"customerTransactionId": "6D9188CF-FA59-44C3-87A2-4506CE9C1EA3"
}

Response

Field Description Format
type "transfer" Text
fields[n].name Field description Text
fields[n].group[n].key Key is name of the field you should include in the JSON Text
fields[n].group[n].name Field description Text
fields[n].group[n].type Display type of field (e.g. text, select, etc) Text
fields[n].group[n].refreshRequirementsOnChange Tells you whether you should call POST transfer-requirements once the field value is set to discover required lower level fields. Boolean
fields[n].group[n].required Indicates if the field is mandatory or not Boolean
fields[n].group[n].displayFormat Display format pattern. Text
fields[n].group[n].example Example value. Text
fields[n].group[n].minLength Min valid length of field value. Integer
fields[n].group[n].maxLength Max valid length of field value. Integer
fields[n].group[n].validationRegexp Regexp validation pattern. Text
fields[n].group[n].validationAsync Validator URL and parameter name you should use when submitting the value for validation Text
fields[n].group[n].valuesAllowed[n].key List of allowed values. Value key Text
fields[n].group[n].valuesAllowed[n].name List of allowed values. Value name. Text




































Profile Webhooks

Profile webhook subscription is a mechanism that will allow you to receive notifications to your servers whenever various events happen in relation to different resources created under a specific profile.

Before proceeding, make sure the endpoint where you intend to receive webhooks satisfies the following requirements:

  • Has a valid domain name (IPs are disallowed)
  • Listens to HTTPS requests on port 443
  • Has a valid HTTPS certificate signed by a trusted Certificate Authority - CA (self-signed or expired certificates are not accepted)
  • Does not include any query arguments in the URL

https://webhooks.example.com/balance-change is a valid URL; http://webhooks.example.com:8080/hook.php?type=balance is not.

You can have multiple subscriptions per event type though be mindful you will receive duplicate callbacks, one for each subscription. Find out more about webhook events here.

If you will be dealing with multiple profiles in your integration, check out application webhooks. You will have to subscribe only once and you will receive updates concerning all resources that were created in your application.

There are two ways you can manage profile webhooks:

  • via API (read more below)
  • via user interface (go to your settings page)

Create

Create a profile subscription.

URL validation

Our system will validate the requested delivery URL before creating a subscription.

A test notification will be sent to the URL and if a 2xx-series HTTP response is not received then the creation request will be rejected with error code INVALID_CALLBACK_URL.

Your notification endpoint must be ready to respond to the test notification. Test notifications can be distinguished by the presence of an HTTP request header. See the section Event HTTP requests for more information on request headers.

Example Request:

curl -X POST "https://api.transferwise.com/v3/profiles/{profileId}/subscriptions" \
  -H "Authorization: Bearer <your user token>" \
  -H "Content-Type: application/json" \
  -d '{
       "name": "Webhook Subscription #1",
       "trigger_on": "transfers#state-change",
       "delivery": {
         "version": "2.0.0",
         "url": "https://your.webhook.url/12345"
         }
      }'

Example Response:

{
    "id": "72195556-e5cb-495e-a010-b37a4f2a3043", 
    "name": "Webhook Subscription #1",
    "delivery": {
        "version": "2.0.0",
        "url": "https://your.webhook.url/12345" 
    },
    "trigger_on": "transfers#state-change", 
    "scope": {
        "domain": "profile", 
        "id": "<profile ID>"
    },
    "created_by": {
        "type": "user",
        "id": "<your user ID>"
    },
    "created_at": "2008-09-15T15:53:00Z"
}

Request

POST https://api.transferwise.com/v3/profiles/{profileId}/subscriptions

profileId - ID of the profile you are subscribing to.

All fields listed below are required for creating a webhook subscription.

Field Description Format
name A custom name for your webhook to ease with identification Text
trigger_on Choose from a list of available events Text
delivery.version The event representation semantic Text
delivery.url Required. The URL where your server will be listening for events. Text

Response

Field Description Format
id UUID that uniquely identifies the subscription Text
name A custom name for your webhook to ease with identification Text
trigger_on transfers#state-change, transfers#active-cases or balances#credit Text
delivery.version The event representation semantic Text
delivery.url Required. The URL where your server will be listening for events. Text
scope.domain Scope of this subscription, always "profile" in this case Text
scope.id Profile ID used to create this subscription Text
created_by.type Creator type. Always user in this case Text
created_by.id User id of the creator Text
created_at Timestamp of when the subscription was created Text

Delete

Deletes a subscription by its identifier.

Example Request:

curl -X DELETE "https://api.transferwise.com/v3/profiles/{profileId}/subscriptions/{id}" \
  -H "Authorization: Bearer <your user token>"

Example Response:

Request

DELETE https://api.transferwise.com/v3/profiles/{profileId}/subscriptions/{id}

Get by ID

Retrieves a subscription by its identifier.

Example Request:

curl -X GET "https://api.transferwise.com/v3/profiles/{profileId}/subscriptions/{id}" \
  -H "Authorization: Bearer <your user token>"

Example Response:

{
    "id": "f215f353-35fd-405b-b27f-4fd603c905ed", 
    "name": "Webhook Subscription #1",
    "delivery": {
        "version": "2.0.0",
        "url": "https://your.webhook.url/12345" 
    },
    "trigger_on": "balances#credit", 
    "scope": {
        "domain": "profile", 
        "id": "<profile ID>"
    },
    "created_by": {
        "type": "user",
        "id": "<your user ID>"
    },
    "created_at": "2008-09-15T15:53:00Z"
}

Request

GET https://api.transferwise.com/v3/profiles/{profileId}/subscriptions/{id}

List

List all your subscriptions

Example Request:

curl -X GET "https://api.transferwise.com/v3/profiles/{profileId}/subscriptions" \
  -H "Authorization: Bearer <your user token>"

Example Response:

[
  {
    "id": "e889e085-3677-4110-be26-3e9160ac9f25",
    "name": "#1 subscription",
    "delivery": {
      "version": "2.0.0",
      "url": "https://your.webhook.url/12345"
    },
    "trigger_on": "transfers#state-change",
    "created_by": {
      "type": "user",
      "id": "<your user ID>"
    },
    "scope": {
      "domain": "profile",
      "id": "<profile ID>"
    }
  },
  {
    "id": "eabeb3f5-c134-4a1c-99e2-86a1163daf1b",
    "name": "#2 subscription",
    "delivery": {
      "version": "2.0.0",
      "url": "https://your.webhook.url/12345"
    },
    "trigger_on": "transfers#state-change",
    "created_by": {
      "type": "user",
      "id": "<your user ID>"
    },
    "scope": {
      "domain": "profile",
      "id": "<profile ID>"
    }
  }
]

Request

GET https://api.transferwise.com/v3/profiles/{profileId}/subscriptions

Webhook events

Webhook events are messages that describe certain business events that occur within Wise's system. For example, an event may describe a change in the status of a transfer you have made.

Events that are related to your Wise resources can be sent to your server as HTTP POST requests. You can start receiving events by creating webhook subscriptions using the Wise Platform API or website interface.

Subscriptions specify what type of event should be sent, and what server location the event should be sent to.

Events will not contain any personally identifiable information.

Webhook handlers

To receive events, you must set up a publicly accessible HTTPS endpoint and create a subscription that uses this endpoint. Our system will send HTTP POST requests to this endpoint with events encoded using JSON.

Your system must respond with a 2xx-series HTTP status code within 5 seconds of receiving a request to acknowledge successful delivery of a webhook notification. If this "success" response is not received by us within this time period, we will consider the delivery attempt as having failed and will later try to resend the message. We will attempt to redeliver messages at increasing intervals over a two week period. We will try at most 25 times to do this.

A recommended strategy for handling notifications is to do some basic validation and then store the notification for processing by a separate server process. This will avoid our delivery system from considering delivery attempts to have failed if your handler does not respond in time due to a long handling process. Basic validation could include signature verification (see below).

Event HTTP requests

Event HTTP request bodies have a type-specific structure. Events using version 2 of our type schema will contain a common base structure with additional event-specific details. Each event type is described in detail later in this section.

Event HTTP requests also contain the following custom headers:

Signature header X-Signature-SHA256

Wise's public webhook signing key for the production environment:

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvO8vXV+JksBzZAY6GhSO
XdoTCfhXaaiZ+qAbtaDBiu2AGkGVpmEygFmWP4Li9m5+Ni85BhVvZOodM9epgW3F
bA5Q1SexvAF1PPjX4JpMstak/QhAgl1qMSqEevL8cmUeTgcMuVWCJmlge9h7B1CS
D4rtlimGZozG39rUBDg6Qt2K+P4wBfLblL0k4C4YUdLnpGYEDIth+i8XsRpFlogx
CAFyH9+knYsDbR43UJ9shtc42Ybd40Afihj8KnYKXzchyQ42aC8aZ/h5hyZ28yVy
Oj3Vos0VdBIs/gAyJ/4yyQFCXYte64I7ssrlbGRaco4nKF3HmaNhxwyKyJafz19e
HwIDAQAB
-----END PUBLIC KEY-----

Wise's public webhook signing key for the sandbox environment:

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwpb91cEYuyJNQepZAVfP
ZIlPZfNUefH+n6w9SW3fykqKu938cR7WadQv87oF2VuT+fDt7kqeRziTmPSUhqPU
ys/V2Q1rlfJuXbE+Gga37t7zwd0egQ+KyOEHQOpcTwKmtZ81ieGHynAQzsn1We3j
wt760MsCPJ7GMT141ByQM+yW1Bx+4SG3IGjXWyqOWrcXsxAvIXkpUD/jK/L958Cg
nZEgz0BSEh0QxYLITnW1lLokSx/dTianWPFEhMC9BgijempgNXHNfcVirg1lPSyg
z7KqoKUN0oHqWLr2U1A+7kqrl6O2nx3CKs1bj1hToT1+p4kcMoHXA7kA+VBLUpEs
VwIDAQAB
-----END PUBLIC KEY-----

Each outgoing webhook request is signed. You should verify that any request you handle was sent by Wise and has not been forged or tampered with. You should not process any requests with signatures that fail verification.

Signatures are generated using an RSA key and SHA256 digest of the message body. They are transmitted using the X-Signature-SHA256 request header and are Base64 encoded.

In this repository, you can see some reference implementations in Java, Node and Ruby.

Delivery ID header X-Delivery-Id

Each outgoing notification is assigned a unique delivery UUID.

Test notification header X-Test-Notification

This header is present with the value true if the notification is a test message.

Test messages can be sent to verify callback URLs when subscriptions are being set up.

Event payload

All event notification payloads have the same high-level structure. Top-level properties are common to all events. The data property is an object that can contain various properties. The exact properties that the data object contains depends on the event type and schema version of the event.

Basic event payload:

{
  "data": {},
  "subscription_id": "01234567-89ab-cdef-0123-456789abcdef",
  "event_type": "event#type",
  "schema_version": "2.0.0",
  "sent_at": "2020-01-01T12:34:56Z"
}

Common properties

Field Description Format
data Event type- and schema version-specific details Object
subscription_id ID of the webhook subscription that triggered the event notification Text
event_type Event type (what event happened in our system) String
schema_version Schema version (what notification structure is being used to model the event) String
sent_at When the event notification was sent from our system Datetime

Event types

The follow event types are available. Please note that some event types are restricted to certain types of webhook subscription.

Event type Profile subscriptions Application subscriptions
transfers#state-change supported supported
transfers#active-cases supported not supported
balances#credit supported not supported
profiles#verification-state-change not supported supported
transfers#payout-failure not supported supported
swift-in#credit supported not supported

Transfer status change event

Event type: transfers#state-change

This event will be triggered every time a transfer's status is updated. Each event contains a timestamp. As we do not guarantee the order of events, please use data.occurred_at to reconcile the order.

If you would like to subscribe to transfer state change events, please use transfers#state-change when creating your subscription.

Example v2.0.0 transfers#state-change event:

{
  "data": {
    "resource": {
      "type": "transfer",
      "id": 111,
      "profile_id": 222,
      "account_id": 333
    },
    "current_state": "processing",
    "previous_state": "incoming_payment_waiting",
    "occurred_at": "2020-01-01T12:34:56Z"
  },
  "subscription_id": "01234567-89ab-cdef-0123-456789abcdef",
  "event_type": "transfers#state-change",
  "schema_version": "2.0.0",
  "sent_at": "2020-01-01T12:34:56Z"
}

Schema version 2.0.0 (latest)

Field Description Format
data.resource.type Transfer resource type (always transfer) String
data.resource.id ID of the transfer Integer
data.resource.profile_id ID of the profile that owns the transfer Integer
data.resource.account_id ID of transfer's recipient account Integer
data.current_state Current transfer state (see transfer statuses) String
data.previous_state Previous transfer state (see transfer statuses) String
data.occurred_at When the state change occurred Datetime

Transfer active cases event

Event type: transfers#active-cases

This event will be triggered every time a transfer's list of active cases is updated. Active cases indicate potential problems with transfer processing.

If you would like to subscribe to transfer active cases events, please use transfers#active-cases when creating your subscription.

Example v2.0.0 transfers#active-cases event:

{
  "data": {
    "resource": {
      "type": "transfer",
      "id": 111,
      "profile_id": 222,
      "account_id": 333
    },
    "active_cases": ["deposit_amount_less_invoice"]
  },
  "subscription_id": "01234567-89ab-cdef-0123-456789abcdef",
  "event_type": "transfers#active-cases",
  "schema_version": "2.0.0",
  "sent_at": "2020-01-01T12:34:56Z"
}

Schema version 2.0.0 (latest)

Field Description Format
data.resource.type Transfer resource type (always transfer) String
data.resource.id ID of the transfer Integer
data.resource.profile_id ID of the profile that owns the transfer Integer
data.resource.account_id ID of transfer's recipient account Integer
data.active_cases Ongoing issues related to the transfer List of strings

Balance credit event

Event type: balances#credit

This event will be triggered every time a multi-currency account is credited.

If you would like to subscribe to balance credit events, please use balances#credit when creating your subscription.

Please note: This event is not currently delivered to application subscriptions.

Example v2.0.0 balances#credit event:

{
  "data": {
    "resource": {
      "type": "balance-account",
      "id": 111,
      "profile_id": 222
    },
    "transaction_type": "credit",
    "amount": 1.23,
    "currency": "EUR",
    "post_transaction_balance_amount": 2.34,
    "occurred_at": "2020-01-01T12:34:56Z"
  },
  "subscription_id": "01234567-89ab-cdef-0123-456789abcdef",
  "event_type": "balances#credit",
  "schema_version": "2.0.0",
  "sent_at": "2020-01-01T12:34:56Z"
}

Schema version 2.0.0 (latest)

Field Description Format
data.resource.type Resource type (always balance-account) String
data.resource.id ID of the account Integer
data.resource.profile_id ID of the profile that owns the account Integer
data.transaction_type Always credit String
data.amount Deposited amount Decimal
data.currency Currency code String
data.post_transaction_balance_amount Balance after the credit was applied Decimal
data.occurred_at When the credit occurred Datetime

Verification state change event

Event type: profiles#verification-state-change

This event will be triggered when the verification state of a connected profile changes.

A profile's verification state can be verified or not_verified. If the state is verified, then the user is ready to make payments using Wise. If the state is not_verified, then we advise not to initiate any transfers with the user's access token as the payments will not be processed until the verification is completed.

There is a more in-depth discussion of verification state in our Connected Apps Integration Guide.

Please note: This event is currently delivered only to application subscriptions.

If you would like to subscribe to verification state change events, please use profiles#verification-state-change when creating your subscription.

Example v2.0.0 profiles#verification-state-change event:

{
  "data": {
    "resource": {
      "type": "profile",
      "id": 111
    },
    "current_state": "verified",
    "occurred_at": "2020-01-01T12:34:56Z"
  },
  "subscription_id": "01234567-89ab-cdef-0123-456789abcdef",
  "event_type": "profiles#verification-state-change",
  "schema_version": "2.0.0",
  "sent_at": "2020-01-01T12:34:56Z"
}

Schema version 2.0.0 (latest)

Field Description Format
data.resource.type Profile resource type (always profile) String
data.resource.id ID of the profile Integer
data.current_state Current verification state of the profile (see discussion above) String
data.occurred_at When the verification state change occurred Datetime

Batch Payment Initiations state change event

Event type: batch-payment-initiations#state-change

This event will be triggered when the payment initiation state of a batch group payment changes.

The expected state of a batch payment initiation can be one of: NEW, PROCESSING, COMPLETED, FAILED, CHARGED_BACK.

If you would like to subscribe to batch payment initiation state change events, please use batch-payment-initiations#state-change when creating your subscription.

Example v2.0.0 batch-payment-initiations#state-change event:

{
  "data": {
    "resource": {
        "id": 12345,
        "batchGroupId": "068e186d-9632-4937-b753-af3e53f4d0b0",
        "profileId": 2
    },
    "previousStatus": "NEW",
    "newStatus": "PROCESSING",
    "occurredAt": "2021-04-13T19:51:41.423404Z" ,
    "returnCode": "200"
  },
  "subscription_id": "01234567-89ab-cdef-0123-456789abcdef",
  "event_type": "batch-payment-initiations#state-change",
  "schema_version": "2.0.0",
  "sent_at": "2020-01-01T12:34:56Z"
}

Schema version 2.0.0 (latest)

Field Description Format
data.resource.id Payment initiation ID Number
data.resource.batchGroupId Batch group ID Text
data.resource.profileId The ID of the profile this payment belongs to Number
data.previousStatus Previous payment initiation state Text
data.currentStatus Current payment initiation state Text
data.occurredAt When the payment initiation state change occurred Timestamp
data.returnCode Return code of the underlying payment system Text

Payout failure events

Event type: transfers#payout-failure

This event will be triggered every time a payout fails. The event can be used to get further information about a failed payment.

transfers#state-change event provides high level information about the state of transfers. But it doesn't provide details about payout failures.

While the transfers#state-change event is in outgoing_payment_sent state, the payout could fail for certain reasons listed below.

Using this event, you can understand the reason behind the failure and even ask your customers to fix the problem by themselves. If the failure reason code is WRONG_ACCOUNT_NUMBER for example.

Please note that not every payout failure will trigger a transfers#state-change. For example a payout might fail with MANDATE_NOT_FILLED_IN code but the corresponding transfer might stay in the same state.

We recommend to process both event types(transfers#payout-failure and transfers#state-change) separate from each other.

If you would like to subscribe to payout failure events, please use transfers#payout-failure when creating your subscription.

Example v2.0.0 transfers#payout-failure event:

{
  "data": {
    "transfer_id": 111,
    "failure_reason_code": "WRONG_ID_NUMBER",
    "failure_description": "Invalid recipient's ID document number",
    "occurred_at": "2020-01-01T12:34:56Z"
  },
  "subscription_id": "01234567-89ab-cdef-0123-456789abcdef",
  "event_type": "transfers#payout-failure",
  "schema_version": "2.0.0",
  "occured_at": "2020-01-01T12:34:56Z"
}

Schema version 2.0.0 (latest)

Field Description Format
data.transfer_id ID of the transfer Integer
data.failure_reason_code Code of the failure error String
data.failure_description Description of the failure code String
data.occurred_at When the state change occurred Datetime

Table of available failure reason codes and descriptions

Code Description
ACCOUNT_CLOSED The recipient details are correct, but beneficiary account is closed
ACCOUNT_FROZEN The recipient details are correct, but beneficiary account is frozen
ACCOUNT_BLOCKED The recipient details are correct, but beneficiary account is blocked
ACCOUNT_LIMIT_REACHED The recipient details are correct, but beneficiary account has a limit that can be unblocked by the recipient
WRONG_ACCOUNT_NUMBER Invalid account number
WRONG_CARD_NUMBER Invalid card number
WRONG_ACCOUNT_DETAILS Invalid account number AND/OR invalid bank code
WRONG_ACCOUNT_TYPE Incorrect account type
WRONG_BANK_CODE Invalid sort/BIC/routing/etc number
WRONG_BRANCH_CODE Invalid branch code
WRONG_NAME Account number matches, but the name is not 100% correct
WRONG_PHONE_NUMBER Recipient phone number is incorrect
WRONG_ID_NUMBER Invalid recipient's ID document number
WRONG_RUT_NUMBER Invalid recipient's RUT (Rol Único Tributario) number
TAX_ID_NOT_MATCHING Tax ID doesn't match recipient's name
TAX_ID_SUSPENDED Tax ID is suspended
WRONG_REFERENCE Invalid payment reference
WRONG_PAYMENT_PURPOSE Invalid or not accepted payment purpose
ACCOUNT_DOES_NOT_EXIST Format is correct but this account does not exist in recipient bank
WRONG_CURRENCY Recipient account is in different currency
WRONG_CARD_TYPE Recipient account doesn't support payments to this card type
CANNOT_ACCEPT_FROM_3RD_PARTY Recipient bank can't accept the payments from 3rd party
CREDITING_ACCOUNT_FORBIDDEN Terms and Conditions of Account do not permit crediting of these funds
DUPLICATE_ENTRY Recipient bank informs that there has been another payment in the same amount
FUNDS_NOT_EXPECTED_RETURNED Beneficiary not expecting funds/instructed return
MANDATE_NOT_FILLED_IN Recipient didn't fill out the mandate form on time or the email address is incorrect
BUSINESS_PAYMENTS_FORBIDDEN Payment to business accounts are not allowed
DUPLICATE_ENTRY Recipient bank informs that there has been another payment in the same amount
REASON_NOT_SPECIFIED Reason not specified

Wise could add new failure codes to this list and your system should be able to handle the events even if the failure reason code is not recognised.

SWIFT Receive Events

Event type: swift-in#credit

This event will be triggered every time a SWIFT message is received and deposited into a balance account.

Please note: It is recommended that you do not subscribe to balances#credit or transfers#state-change on the same profile to avoid duplication of webhook details.

Example swift-in#credit event:

{
    "data": {
        "action": {
              "type": "credit",
              "id": 12345,
              "profile_id": 222,
              "account_id": 333
        },
        "resource": {
            "id": "55555",
            "type": "103",
            "message": "
                {1:F21TRWIGB22AXXX123456789}{4:{177:0123456789}{451:0}}{1:F01TRWIGB22AXXX12345678}{2:O1030727211112LHVBEE22AXXX15007123456789912345WN}{3:{108:ASW86540/12112FA}{119:STP}{111:001}{121:f875814b-7d44-4d1b-a499-123456789abcde}}{4:
                :20:ASW86540/123456
                :23B:CRED
                :26T:K90
                :32A:211112EUR3,54
                :33B:EUR3,54
                :50F:/EE947700771111111111
                1/SMITH#JOHN
                2/EVERGREEN STREET, 10
                3/BE/BRUSSELS
                4/12345678
                :52A:ZYABEE20
                :57A:AGRNMD2XXXX
                :59F:/BE1234567891234
                1/SMITH#JOHN
                2/EVERGREEN AVE, 6
                3/BE/BRUSSELS
                :70:/RFB/BET072
                :70:/INV/abc/SDF-96//1234-234///ROC/98I
                U87
                :70:/TSU/00000089963-0820-01/ABC-15/256
                214,
                :71A:SHA
                -}
            "
        }
        "occurred_at": "2020-01-01T12:34:56Z"
    },
    "subscription_id": "01234567-89ab-cdef-0123-456789abcdef",
    "event_type": "swift-in#credit",
    "schema_version": "2.0.0",
    "sent_at": "2020-01-01T12:34:56Z"
}

Schema version 2.0.0 (latest)

Field Description Format
data.action.type Type of action (always credit) String
data.action.id TransferID of the credit Integer
data.action.profile_id ProfileID for the transfer Integer
data.action.account_id AccountID for the transfer Integer
data.resource.type SWIFT message type String
data.resource.id ID of webhook Integer
data.resource.message Complete SWIFT Message as received String
data.occurred_at When the credit occurred Datetime

Balance Account

Balance accounts are included as part of the Wise Multi-Currency Account. Please refer to our multi-currency account guide for more information on the general use of the endpoints included below.

Balance account object

Example Balance Account:

{
  "id": 22656,
  "currency": "EUR",
  "type": "STANDARD",
  "name": null,
  "icon": null,
  "investmentState": "NOT_INVESTED",
  "amount": {
    "value": 0,
    "currency": "EUR"
  },
  "reservedAmount": {
    "value": 0,
    "currency": "EUR"
  },
  "cashAmount": {
    "value": 0,
    "currency": "EUR"
  },
  "totalWorth": {
    "value": 0,
    "currency": "EUR"
  },
  "creationTime": "2020-05-20T14:43:16.658Z",
  "modificationTime": "2020-05-20T14:43:16.658Z",
  "visible": true,
}
Field Description Format
id balance id integer
currency balance currency (ISO 4217 Alphabetic Code) text
type balance type (STANDARD, SAVINGS) text
name balance name text
icon emoji string text
investmentState Investment state of balance (NOT_INVESTED, INVESTED, DIVESTING, UNKNOWN) text
amount.value Available balance value that can be used to fund transfers decimal
amount.currency balance currency (ISO 4217 Alphabetic Code) text
reservedAmount.value Amount reserved for transactions decimal
reservedAmount.currency balance currency (ISO 4217 Alphabetic Code) text
cashAmount.value Cash amount in the account decimal
cashAmount.currency balance currency (ISO 4217 Alphabetic Code) text
totalWorth.value Current total worth decimal
totalWorth.currency balance currency (ISO 4217 Alphabetic Code) text
creationTime date when the balance was created timestamp
modificationTime date when the balance was last modified timestamp
visible if balance is visible for the user or not boolean

Create balance account

Example Request:

curl -L -X POST 'https://api.sandbox.transferwise.tech/v3/profiles/{{profileId}}/balances' \
  -H 'Authorization: Bearer <your api token>' \
  -H 'Content-Type: application/json' \
  -H 'X-idempotence-uuid: <uuid>' \
  --data-raw '{
      "currency": "EUR",
      "type": "STANDARD"
  }'

Example Response:

{
  "id": 22656,
  "currency": "EUR",
  "type": "STANDARD",
  "name": null,
  "icon": null,
  "investmentState": "NOT_INVESTED",
  "amount": {
    "value": 0,
    "currency": "EUR"
  },
  "reservedAmount": {
    "value": 0,
    "currency": "EUR"
  },
  "cashAmount": {
    "value": 0,
    "currency": "EUR"
  },
  "totalWorth": {
    "value": 0,
    "currency": "EUR"
  },
  "creationTime": "2020-05-20T14:43:16.658Z",
  "modificationTime": "2020-05-20T14:43:16.658Z",
  "visible": true,
}

Purpose

This endpoint opens a balance within the specified profile, in the currency and type specified in the request.

For STANDARD balances, only one can be created for a currency. For SAVINGS balances, multiples in the same currency can be opened.

When sending the request, the currency and type are required. If creating a SAVINGS type balance, a name is also required.

Request

Field Description Format
currency balance currency (ISO 4217 Alphabetic Code) text
type Type of Balance. Accepts STANDARD or SAVINGS text
name balance name text

List balance accounts

Example Request:

curl -X GET https://api.sandbox.transferwise.tech/v4/profiles/{{profileId}}/balances?types=STANDARD \
     -H "Authorization: Bearer <your api token>"

Example Response:

[
  {
    "id": 22656,
    "currency": "EUR",
    "type": "STANDARD",
    "name": null,
    "icon": null,
    "investmentState": "NOT_INVESTED",
    "amount": {
      "value": 0,
      "currency": "EUR"
    },
    "reservedAmount": {
      "value": 0,
      "currency": "EUR"
    },
    "cashAmount": {
      "value": 0,
      "currency": "EUR"
    },
    "totalWorth": {
      "value": 0,
      "currency": "EUR"
    },
    "creationTime": "2020-05-20T14:43:16.658Z",
    "modificationTime": "2020-05-20T14:43:16.658Z",
    "visible": true,
  },
  ...
]

Purpose

Retrieve the user's multi-currency account balance accounts. It returns all balance accounts the profile has in the types specified.

Parameters

A parameter of type must be passed and include at least a single type. To return more than one type, comma separate the values. Acceptable values are STANDARD and SAVINGS.

Get balance account by ID

Example Request:

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

Example Response:

{
  "id": 22656,
  "currency": "EUR",
  "type": "STANDARD",
  "name": null,
  "icon": null,
  "investmentState": "NOT_INVESTED",
  "amount": {
    "value": 0,
    "currency": "EUR"
  },
  "reservedAmount": {
    "value": 0,
    "currency": "EUR"
  },
  "cashAmount": {
    "value": 0,
    "currency": "EUR"
  },
  "totalWorth": {
    "value": 0,
    "currency": "EUR"
  },
  "creationTime": "2020-05-20T14:43:16.658Z",
  "modificationTime": "2020-05-20T14:43:16.658Z",
  "visible": true,
}

Purpose

This endpoint returns a balance based on the specified balance ID.

Delete a balance

Example Request:

curl -X DELETE https://api.sandbox.transferwise.tech/v3/profiles/{{profileId}}/balances/{{balanceId}} \
     -H "Authorization: Bearer {{access-token}}"

Example Response:

{
  "id": 22656,
  "currency": "EUR",
  "type": "STANDARD",
  "name": null,
  "icon": null,
  "amount": {
    "value": 0.00,
    "currency": "EUR"
  },
  "reservedAmount": {
    "value": 0.00,
    "currency": "EUR"
  },
  "creationTime": "2020-05-20T14:43:16.658Z",
  "modificationTime": "2020-05-20T14:43:16.658Z",
  "visible": true,
}

Purpose

Close a balance account for the users profile. Balance accounts must have a zero balance in order for it to be closed. Bank account details for a balance account will also be deactivated and may not be restored in the future.

Get balance account statement

Example Request:

curl -X GET https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/balance-statements/{balanceId}/statement.json?
intervalStart=2018-03-01T00:00:00.000Z&intervalEnd=2018-03-15T23:59:59.999Z&type=COMPACT \
     -H "Authorization: Bearer <your api token>"

Example Response:

{
  "accountHolder": {
    "type": "PERSONAL",
    "address": {
      "addressFirstLine": "Veerenni 24",
      "city": "Tallinn",
      "postCode": "12112",
      "stateCode": "",
      "countryName": "Estonia"
    },
    "firstName": "Oliver",
    "lastName": "Wilson"
  },
  "issuer": {
    "name": "TransferWise Ltd.",
    "firstLine": "56 Shoreditch High Street",
    "city": "London",
    "postCode": "E1 6JJ",
    "stateCode": "",
    "country": "United Kingdom"
  },
  "bankDetails": null,
  "transactions": [
    {
      "type": "DEBIT",
      "date": "2018-04-30T08:47:05.832Z",
      "amount": {
        "value": -7.76,
        "currency": "EUR"
      },
      "totalFees": {
        "value": 0.04,
        "currency": "EUR"
      },
      "details": {
        "type": "CARD",
        "description": "Card transaction of 6.80 GBP issued by Tfl.gov.uk/cp TFL TRAVEL CH",
        "amount": {
          "value": 6.8,
          "currency": "GBP"
        },
        "category": "Transportation Suburban and Loca",
        "merchant": {
          "name": "Tfl.gov.uk/cp",
          "firstLine": null,
          "postCode": "SW1H 0TL  ",
          "city": "TFL TRAVEL CH",
          "state": "   ",
          "country": "GB",
          "category": "Transportation Suburban and Loca"
        }
      },
      "exchangeDetails": {
        "forAmount": {
          "value": 6.8,
          "currency": "GBP"
        },
        "rate": null
      },
      "runningBalance": {
        "value": 16.01,
        "currency": "EUR"
      },
      "referenceNumber": "CARD-249281"
    },
    {
      "type": "CREDIT",
      "date": "2018-04-17T07:47:00.227Z",
      "amount": {
        "value": 200,
        "currency": "EUR"
      },
      "totalFees": {
        "value": 0,
        "currency": "EUR"
      },
      "details": {
        "type": "DEPOSIT",
        "description": "Received money from HEIN LAURI with reference SVWZ+topup card",
        "senderName": "HEIN LAURI",
        "senderAccount": "EE76 1700 0170 0049 6704 ",
        "paymentReference": "SVWZ+topup card"
      },
      "exchangeDetails": null,
      "runningBalance": {
        "value": 207.69,
        "currency": "EUR"
      },
      "referenceNumber": "TRANSFER-34188888"
    },
    {
      "type": "CREDIT",
      "date": "2018-04-10T05:58:34.681Z",
      "amount": {
        "value": 9.94,
        "currency": "EUR"
      },
      "totalFees": {
        "value": 0,
        "currency": "EUR"
      },
      "details": {
        "type": "CONVERSION",
        "description": "Converted 8.69 GBP to 9.94 EUR",
        "sourceAmount": {
          "value": 8.69,
          "currency": "GBP"
        },
        "targetAmount": {
          "value": 9.94,
          "currency": "EUR"
        },
        "fee": {
          "value": 0.03,
          "currency": "GBP"
        },
        "rate": 1.147806
      },
      "exchangeDetails": null,
      "runningBalance": {
        "value": 9.94,
        "currency": "EUR"
      },
      "referenceNumber": "CONVERSION-1511237"
    }
  ],
  "endOfStatementBalance": {
    "value": 9.94,
    "currency": "EUR"
  },
  "query": {
    "intervalStart": "2018-03-01T00:00:00Z",
    "intervalEnd": "2018-04-30T23:59:59.999Z",
    "currency": "EUR",
    "accountId": 64
  }
}

Purpose

This endpoint allows for statements to be generated for the provided balanceId, with the response in JSON. To generate in CSV or PDF, replace statement.json with statement.csv or statement.pdf respectively in the above URL. Note that the PDF includes Wise branding.

The period between intervalStart and intervalEnd cannot exceed 469 days (around 1 year 3 months).

Request

GET https://api.sandbox.transferwise.tech/v1/profiles/{{profileId}}/balance-statements/{{balanceId}}/statement.json? currency=EUR&intervalStart=2018-03-01T00:00:00.000Z&intervalEnd=2018-03-15T23:59:59.999Z&type=COMPACT

Field Description Format
intervalStart Statement start time in UTC time Timestamp.
intervalEnd Statement start time in UTC time Timestamp.
type COMPACT for a single statement line per transaction. FLAT for accounting statements where transaction fees are on a separate line. Text

Response

Field Description Format
accountHolder.type Account holder type: PERSONAL or BUSINESS Text
accountHolder.address.addressFirstLine Account holder address street Text
accountHolder.address.city Account holder address city Text
accountHolder.address.postCode Account holder address zipc ode Text
accountHolder.address.stateCode Account holder address state Text
accountHolder.address.countryName Account holder address country Text
accountHolder.firstName Account holder first name Text
accountHolder.lastName Account holder last name Text
issuer.name Account issuer name Text
issuer.firstLine Account issuer address street Text
issuer.city Account issuer address city Text
issuer.postCode Account issuer address zip code Text
issuer.stateCode Account issuer address state Text
issuer.country Account issuer address country Text
bankDetails Your local bank details Group
transactions[n].type DEBIT or CREDIT Text
transactions[n].date Time of transaction Zulu time
transactions[n].amount.value Transaction amount Decimal
transactions[n].amount.currency Transaction currency code Text
transactions[n].totalFees.value Transaction fee amount Decimal
transactions[n].totalFees.currency Transaction fee currency code Text
transactions[n].details.type CARD, CONVERSION, DEPOSIT, TRANSFER, MONEY_ADDED Text
transactions[n].details.description Human readable explanation about the transaction Text
transactions[n].details.amount.value Amount in original currency (card transactions abroad) Decimal
transactions[n].details.amount.currency Original currency code Text
transactions[n].details.sourceAmount.value Amount in source currency (conversions) Decimal
transactions[n].details.sourceAmount.currency Source currency code Text
transactions[n].details.targetAmount.value Amount in target currency (conversions) Decimal
transactions[n].details.targetAmount.currency Target currency code Text
transactions[n].details.fee.value Conversion fee amount Decimal
transactions[n].details.fee.currency Conversion fee currency code Text
transactions[n].details.rate Conversion exchange rate Decimal
transactions[n].details.senderName Deposit sender name Text
transactions[n].details.senderAccount Deposit sender bank account details Text
transactions[n].details.paymentReference Deposit payment reference text Text
transactions[n].details.category Card transaction category Text
transactions[n].details.merchant.name Card transaction merchant name Text
transactions[n].details.merchant.firstLine Merchant address street Text
transactions[n].details.merchant.postCode Merchant address zipcode Text
transactions[n].details.merchant.city Merchant address city Text
transactions[n].details.merchant.state Merchant address state Text
transactions[n].details.merchant.country Merchant address country Text
transactions[n].details.merchant.category Merchant category Text
transactions[n].exchangeDetails.forAmount.value Currency exchange amount Decimal
transactions[n].exchangeDetails.forAmount.currency Currency code Text
transactions[n].exchangeDetails.rate Exchange rate Decimal
transactions[n].runningBalance.value Running balance after the transaction Decimal
transactions[n].runningBalance.currency Running balance currency code Text
transactions[n].referenceNumber Wise assigned unique transaction reference number Text
endOfStatementBalance.value Closing balance for specified time period Decimal
endOfStatementBalance.currency Closing balance currency code Text
query.intervalStart Query parameter repeated Zulu time
query.intervalEnd Query parameter repeated Zulu time
query.currency Query parameter repeated Text
query.accountId Query parameter repeated Integer

Convert across balance accounts

Example Request:

curl -X POST https://api.sandbox.transferwise.tech/v2/profiles/{profileId}/balance-movements \
     -H "Authorization: Bearer <your api token>"  \
     -H "Content-Type: application/json" \
     -H "X-idempotence-uuid: <your generated uuid> \
     -d '{
            "quoteId": <conversion quote id>
         }'

Example Response:

{
  "id": <conversion transaction id>,
  "type": "CONVERSION",
  "state": "COMPLETED",
  "balancesAfter": [
    {
      "id": 1,
      "value": 10000594.71,
      "currency": "GBP"
    },
    {
      "id": 2,
      "value": 9998887.01,
      "currency": "EUR"
    }
  ],
  "creationTime": "2017-11-21T09:55:49.275Z",
  "steps": [
    {
      "id": 369588,
      "type": "CONVERSION",
      "creationTime": "2017-11-21T09:55:49.276Z",
      "balancesAfter": [
        {
          "value": 9998887.01,
          "currency": "EUR"
        },
        {
          "value": 10000594.71,
          "currency": "GBP"
        }
      ],
      "channelName": null,
      "channelReferenceId": null,
      "tracingReferenceCode": null,
      "sourceAmount": {
        "value": 113.48,
        "currency": "EUR"
      },
      "targetAmount": {
        "value": 100,
        "currency": "GBP"
      },
      "fee": {
        "value": 0.56,
        "currency": "EUR"
      },
      "rate": 0.88558
    }
  ],
  "sourceAmount": {
    "value": 113.48,
    "currency": "EUR"
  },
  "targetAmount": {
    "value": 100,
    "currency": "GBP"
  },
  "rate": 0.88558,
  "feeAmounts": [
    {
      "value": 0.56,
      "currency": "EUR"
    }
  ]
}

This endpoint allows the conversion of funds between two STANDARD balance accounts in different currencies. You first must generate a quote with "payOut": "BALANCE".

Interested in moving money in/out of Jar? Check Move money between balances

Request

POST https://api.sandbox.transferwise.tech/v2/profiles/{profileId}/balance-movements

Please also note that this call needs an extra field in the header called "X-idempotence-uuid". This should be generated and used for any subsequent retry call in the case that the initial POST fails.

Field Description Format
profileId Authenticated profile id. Integer
quoteId Quote id, quote must be created with "payOut": "BALANCE". UUID
X-idempotence-uuid Unique identifier assigned by you. Used for idempotency check purposes. Should your call fail for technical reasons then you can use the same value again for making retry call. UUID

Move money between balances

Example Request:

curl -X POST https://api.sandbox.transferwise.tech/v2/profiles/{profileId}/balance-movements \
     -H "Authorization: Bearer <your api token>"  \
     -H "Content-Type: application/json" \
     -H "X-idempotence-uuid: <your generated uuid> \
     -d '{
            "amount": {
              value: <decimal>,
              currency: <currency>
            }
            "sourceBalanceId": <source id>,
            "targetBalanceId": <target balance id>,
            "quoteId": <conversion quote id>
         }'

Example Response:

{
  "id": <conversion transaction id>,
  "type": "CONVERSION",
  "state": "COMPLETED",
  "balancesAfter": [
    {
      "id": 1,
      "value": 10000594.71,
      "currency": "GBP"
    },
    {
      "id": 2,
      "value": 9998887.01,
      "currency": "EUR"
    }
  ],
  "creationTime": "2017-11-21T09:55:49.275Z",
  "steps": [
    {
      "id": 369588,
      "type": "CONVERSION",
      "creationTime": "2017-11-21T09:55:49.276Z",
      "balancesAfter": [
        {
          "value": 9998887.01,
          "currency": "EUR"
        },
        {
          "value": 10000594.71,
          "currency": "GBP"
        }
      ],
      "channelName": null,
      "channelReferenceId": null,
      "tracingReferenceCode": null,
      "sourceAmount": {
        "value": 113.48,
        "currency": "EUR"
      },
      "targetAmount": {
        "value": 100,
        "currency": "GBP"
      },
      "fee": {
        "value": 0.56,
        "currency": "EUR"
      },
      "rate": 0.88558
    }
  ],
  "sourceAmount": {
    "value": 113.48,
    "currency": "EUR"
  },
  "targetAmount": {
    "value": 100,
    "currency": "GBP"
  },
  "rate": 0.88558,
  "feeAmounts": [
    {
      "value": 0.56,
      "currency": "EUR"
    }
  ]
}

This endpoint allows the following money movements:

  • Add money to same-currency Jar (i.e move money from STANDARD to SAVINGS balance without conversion, amount is provided as request parameter);
  • Add money to another-currency Jar (i.e. convert money, amount is determined by provided quoteId);
  • Withdraw money from Jar (i.e move money from SAVINGS to STANDARD balance without conversion, amount is provided as request parameter).

Note that this call needs an extra field in header called "X-idempotence-uuid".

Interested in converting money from one balance to another? Check Convert across balance accounts

Request

POST https://api.sandbox.transferwise.tech/v2/profiles/{profileId}/balance-movements

Field Description Format
profileId Authenticated profile id. Integer
sourceBalanceId Source balance id. If present, targetBalanceId is required. Integer
targetBalanceId Target balance id. If present, sourceBalanceId is required. Integer
quoteId Quote id, quote must be created with "payOut": "BALANCE". Required for cross-currency movements. UUID
amount Either amount or quoteId are required. Money
X-idempotence-uuid Unique identifier assigned by you. Used for idempotency check purposes. Should your call fail for technical reasons then you can use the same value again for making retry call. UUID

Deprecated

Get Account Balance

Example Request:

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

Example Response:

[
    {
        "id": 64,
        "profileId": <your profile id>,
        "recipientId": 13828530,
        "creationTime": "2018-03-14T12:31:15.678Z",
        "modificationTime": "2018-03-19T15:19:42.111Z",
        "active": true,
        "eligible": true,
        "balances": [
            {
                "balanceType": "AVAILABLE",
                "currency": "GBP",
                "amount": {
                    "value": 10999859,
                    "currency": "GBP"
                },
                "reservedAmount": {
                    "value": 0,
                    "currency": "GBP"
                },
                "bankDetails": null
            },
            {
                "balanceType": "AVAILABLE",
                "currency": "EUR",
                "amount": {
                    "value": 9945236.2,
                    "currency": "EUR"
                },
                "reservedAmount": {
                    "value": 0,
                    "currency": "EUR"
                },
                "bankDetails": {
                    "id": 90,
                    "currency": "EUR",
                    "bankCode": "DEKTDE7GXXX",
                    "accountNumber": "DE51 7001 1110 6050 1008 91",
                    "swift": "DEKTDE7GXXX",
                    "iban": "DE51 7001 1110 6050 0008 91",
                    "bankName": "Handelsbank",
                    "accountHolderName": "Oliver Wilson",
                    "bankAddress": {
                        "addressFirstLine": "Elsenheimer Str. 41",
                        "postCode": "80687",
                        "city": "München",
                        "country": "Germany",
                        "stateCode": null
                    }
                }
            }
        ]
    }
]

Get available balances for all activated currencies in your multi-currency account.

Request

GET https://api.sandbox.transferwise.tech/v1/borderless-accounts?profileId={profileId}

Use profile id obtained earlier to make this call.

Response

Field Description Format
id Multi-currency account id Integer
profileId Personal or business profile id Integer
recipientId Recipient id you can use for a multi-currency account deposit Integer
creationTime Date when multi-currency account was opened Timestamp
modificationTime Date when multi-currency account setup was modified. Timestamp
active Is multi-currency account active or inactive Boolean
eligible Ignore Boolean
balances[n].balanceType AVAILABLE Text
balances[n].currency Currency code Text
balances[n].amount.value Available balance in specified currency Decimal
balances[n].amount.currency Currency code Text
balances[n].reservedAmount.value Reserved amount from your balance Decimal
balances[n].reservedAmount.currency Reserved amount currency code Text
balances[n].bankDetails Bank account details assigned to your multi-currency account. Available for EUR, GBP, USD, AUD, NZD Group
balances[n].bankDetails.id Bank account details id Integer
balances[n].bankDetails.currency Bank account currency Text
balances[n].bankDetails.bankCode Bank account code Text
balances[n].bankDetails.accountNumber Bank account number Text
balances[n].bankDetails.swift Bank account swift code Text
balances[n].bankDetails.iban Bank account iban Text
balances[n].bankDetails.bankName Bank name
balances[n].bankDetails.accountHolderName Bank account holder name Text
balances[n].bankDetails.bankAddress.addressFirstLine Bank address street and house Text
balances[n].bankDetails.bankAddress.postCode Bank address zip code Text
balances[n].bankDetails.bankAddress.city Bank address city Text
balances[n].bankDetails.bankAddress.country Bank address country Text
balances[n].bankDetails.bankAddress.stateCode Bank address state code Text

Get Account Statement

Example Request:

curl -X GET https://api.sandbox.transferwise.tech/v3/profiles/{profileId}/borderless-accounts/{borderlessAccountId}/statement.json?
currency=EUR&intervalStart=2018-03-01T00:00:00.000Z&intervalEnd=2018-03-15T23:59:59.999Z&type=COMPACT \
     -H "Authorization: Bearer <your api token>"

Example Response:

{
  "accountHolder": {
    "type": "PERSONAL",
    "address": {
      "addressFirstLine": "Veerenni 24",
      "city": "Tallinn",
      "postCode": "12112",
      "stateCode": "",
      "countryName": "Estonia"
    },
    "firstName": "Oliver",
    "lastName": "Wilson"
  },
  "issuer": {
    "name": "TransferWise Ltd.",
    "firstLine": "56 Shoreditch High Street",
    "city": "London",
    "postCode": "E1 6JJ",
    "stateCode": "",
    "country": "United Kingdom"
  },
  "bankDetails": null,
  "transactions": [
    {
      "type": "DEBIT",
      "date": "2018-04-30T08:47:05.832Z",
      "amount": {
        "value": -7.76,
        "currency": "EUR"
      },
      "totalFees": {
        "value": 0.04,
        "currency": "EUR"
      },
      "details": {
        "type": "CARD",
        "description": "Card transaction of 6.80 GBP issued by Tfl.gov.uk/cp TFL TRAVEL CH",
        "amount": {
          "value": 6.8,
          "currency": "GBP"
        },
        "category": "Transportation Suburban and Loca",
        "merchant": {
          "name": "Tfl.gov.uk/cp",
          "firstLine": null,
          "postCode": "SW1H 0TL  ",
          "city": "TFL TRAVEL CH",
          "state": "   ",
          "country": "GB",
          "category": "Transportation Suburban and Loca"
        }
      },
      "exchangeDetails": {
        "forAmount": {
          "value": 6.8,
          "currency": "GBP"
        },
        "rate": null
      },
      "runningBalance": {
        "value": 16.01,
        "currency": "EUR"
      },
      "referenceNumber": "CARD-249281"
    },
    {
      "type": "CREDIT",
      "date": "2018-04-17T07:47:00.227Z",
      "amount": {
        "value": 200,
        "currency": "EUR"
      },
      "totalFees": {
        "value": 0,
        "currency": "EUR"
      },
      "details": {
        "type": "DEPOSIT",
        "description": "Received money from HEIN LAURI with reference SVWZ+topup card",
        "senderName": "HEIN LAURI",
        "senderAccount": "EE76 1700 0170 0049 6704 ",
        "paymentReference": "SVWZ+topup card"
      },
      "exchangeDetails": null,
      "runningBalance": {
        "value": 207.69,
        "currency": "EUR"
      },
      "referenceNumber": "TRANSFER-34188888"
    },
    {
      "type": "CREDIT",
      "date": "2018-04-10T05:58:34.681Z",
      "amount": {
        "value": 9.94,
        "currency": "EUR"
      },
      "totalFees": {
        "value": 0,
        "currency": "EUR"
      },
      "details": {
        "type": "CONVERSION",
        "description": "Converted 8.69 GBP to 9.94 EUR",
        "sourceAmount": {
          "value": 8.69,
          "currency": "GBP"
        },
        "targetAmount": {
          "value": 9.94,
          "currency": "EUR"
        },
        "fee": {
          "value": 0.03,
          "currency": "GBP"
        },
        "rate": 1.147806
      },
      "exchangeDetails": null,
      "runningBalance": {
        "value": 9.94,
        "currency": "EUR"
      },
      "referenceNumber": "CONVERSION-1511237"
    }
  ],
  "endOfStatementBalance": {
    "value": 9.94,
    "currency": "EUR"
  },
  "query": {
    "intervalStart": "2018-03-01T00:00:00Z",
    "intervalEnd": "2018-04-30T23:59:59.999Z",
    "currency": "EUR",
    "accountId": 64
  }
}

Get multi-currency account statement for one currency and for specified time range. The period between intervalStart and intervalEnd cannot exceed 455 days (around 1 year 3 month).

Request

GET https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/balance-statements/{balanceId}/statement.json? currency=EUR&intervalStart=2018-03-01T00:00:00.000Z&intervalEnd=2018-03-15T23:59:59.999Z&type=COMPACT

Field Description Format
borderlessAccountId This is included in the Get Account Balance response "id" field. Integer
currency Currency code Text
intervalStart Statement start time in UTC time Zulu time. Don't forget the 'Z' at the end.
intervalEnd Statement start time in UTC time Zulu time. Don't forget the 'Z' at the end.
type (optional) COMPACT (default) for a single statement line per transaction. FLAT for accounting statements where transaction fees are on a separate line. Text

Note that you can also download statements in PDF and CSV formats if you replace statement.json with statement.csv or statement.pdf respectively in the above URL.

Response

Field Description Format
accountHolder.type Account holder type: PERSONAL or BUSINESS Text
accountHolder.address.addressFirstLine Account holder address street Text
accountHolder.address.city Account holder address city Text
accountHolder.address.postCode Account holder address zipc ode Text
accountHolder.address.stateCode Account holder address state Text
accountHolder.address.countryName Account holder address country Text
accountHolder.firstName Account holder first name Text
accountHolder.lastName Account holder last name Text
issuer.name Account issuer name Text
issuer.firstLine Account issuer address street Text
issuer.city Account issuer address city Text
issuer.postCode Account issuer address zip code Text
issuer.stateCode Account issuer address state Text
issuer.country Account issuer address country Text
bankDetails Your local bank details Group
transactions[n].type DEBIT or CREDIT Text
transactions[n].date Time of transaction Zulu time
transactions[n].amount.value Transaction amount Decimal
transactions[n].amount.currency Transaction currency code Text
transactions[n].totalFees.value Transaction fee amount Decimal
transactions[n].totalFees.currency Transaction fee currency code Text
transactions[n].details.type CARD, CONVERSION, DEPOSIT, TRANSFER, MONEY_ADDED Text
transactions[n].details.description Human readable explanation about the transaction Text
transactions[n].details.amount.value Amount in original currency (card transactions abroad) Decimal
transactions[n].details.amount.currency Original currency code Text
transactions[n].details.sourceAmount.value Amount in source currency (conversions) Decimal
transactions[n].details.sourceAmount.currency Source currency code Text
transactions[n].details.targetAmount.value Amount in target currency (conversions) Decimal
transactions[n].details.targetAmount.currency Target currency code Text
transactions[n].details.fee.value Conversion fee amount Decimal
transactions[n].details.fee.currency Conversion fee currency code Text
transactions[n].details.rate Conversion exchange rate Decimal
transactions[n].details.senderName Deposit sender name Text
transactions[n].details.senderAccount Deposit sender bank account details Text
transactions[n].details.paymentReference Deposit payment reference text Text
transactions[n].details.category Card transaction category Text
transactions[n].details.merchant.name Card transaction merchant name Text
transactions[n].details.merchant.firstLine Merchant address street Text
transactions[n].details.merchant.postCode Merchant address zipcode Text
transactions[n].details.merchant.city Merchant address city Text
transactions[n].details.merchant.state Merchant address state Text
transactions[n].details.merchant.country Merchant address country Text
transactions[n].details.merchant.category Merchant category Text
transactions[n].exchangeDetails.forAmount.value Currency exchange amount Decimal
transactions[n].exchangeDetails.forAmount.currency Currency code Text
transactions[n].exchangeDetails.rate Exchange rate Decimal
transactions[n].runningBalance.value Running balance after the transaction Decimal
transactions[n].runningBalance.currency Running balance currency code Text
transactions[n].referenceNumber Wise assigned unique transaction reference number Text
endOfStatementBalance.value Closing balance for specified time period Decimal
endOfStatementBalance.currency Closing balance currency code Text
query.intervalStart Query parameter repeated Zulu time
query.intervalEnd Query parameter repeated Zulu time
query.currency Query parameter repeated Text
query.accountId Query parameter repeated Integer

Convert Currencies

Example Request:

curl -X POST https://api.sandbox.transferwise.tech/v1/borderless-accounts/{borderlessAccountId}/conversions \
     -H "Authorization: Bearer <your api token>"  \
     -H "Content-Type: application/json" \
     -H "X-idempotence-uuid: <your generated uuid> \
     -d '{
            "quoteId": <conversion quote id>
         }'

Example Response:

{
  "id": <conversion transaction id>,
  "type": "CONVERSION",
  "state": "COMPLETED",
  "balancesAfter": [
    {
      "value": 10000594.71,
      "currency": "GBP"
    },
    {
      "value": 9998887.01,
      "currency": "EUR"
    }
  ],
  "creationTime": "2017-11-21T09:55:49.275Z",
  "steps": [
    {
      "id": 369588,
      "type": "CONVERSION",
      "creationTime": "2017-11-21T09:55:49.276Z",
      "balancesAfter": [
        {
          "value": 9998887.01,
          "currency": "EUR"
        },
        {
          "value": 10000594.71,
          "currency": "GBP"
        }
      ],
      "channelName": null,
      "channelReferenceId": null,
      "tracingReferenceCode": null,
      "sourceAmount": {
        "value": 113.48,
        "currency": "EUR"
      },
      "targetAmount": {
        "value": 100,
        "currency": "GBP"
      },
      "fee": {
        "value": 0.56,
        "currency": "EUR"
      },
      "rate": 0.88558
    }
  ],
  "sourceAmount": {
    "value": 113.48,
    "currency": "EUR"
  },
  "targetAmount": {
    "value": 100,
    "currency": "GBP"
  },
  "rate": 0.88558,
  "feeAmounts": [
    {
      "value": 0.56,
      "currency": "EUR"
    }
  ]
}

Convert funds between your multi-currency account currencies. Quote which is used in this call must be created with "payOut": "BALANCE".

Note that this call needs an extra field in header called "X-idempotence-uuid".

Request

POST https://api.sandbox.transferwise.tech/v1/borderless-accounts/{borderlessAccountId}/conversions

Field Description Format
profileId This is included in the Get Account Balance response "id" field. Integer
X-idempotence-uuid Unique identifier assinged by you. Used for idempotency check purposes. Should your call fail for technical reasons then you can use the same value again for making retry call. UUID

Errors

HTTP Status Codes

We use common HTTP status codes included in the response header to indicate success or failure.

Code Description
200 OK. Successful request.
201 OK. Resource created.
400 Bad request. Request message data did not pass validation.
401 Unauthorised. Not authorised to access requested data.
403 Forbidden. Access to requested data is forbidden.
404 Not Found. Requested resource does not exist.
408 Timeout. Operation timed out.
422 Unprocessable entity. Request message data did not pass validation.
500 Server error.

Validation Errors

Example Validation Error:

{
    "errors": [
        {
            "code": "error.route.not.supported",
            "message": "This route is not supported",
            "arguments": [
                "CNY-EUR"
            ]
        }
    ]
}

Data validation or violation of business rules related errors. Response could contain multiple errors.

Authentication Errors

Example Authentication Error:

{
    "error": "unauthorized",
    "error_description": "Full authentication is required to access this resource"
}

Security related errors.

System Errors

Example System Error:

{
  "timestamp": "2017-02-02T13:07:39.644+0000",
  "status": 500,
  "error": "Internal Server Error",
  "exception": "java.lang.NullPointerException",
  "message": "No message available",
  "path": "/v1/quotes/0b63b0cb-2041-4bc4-b3fc-1e51a1454a1b/account-requirements"
}

Something went wrong in our side.