Multi-Currency Accounts Guide

Introduction

This document provides guidelines for the implementation of multi-currency accounts for all partners. It's broken down into key areas and describes the logic to:

  • Determine a user's eligibility for multi-currency accounts.
  • Determine which balance account currencies are supported.
  • Create balance accounts for personal and business profiles.
  • Add bank account details to eligible balance accounts.
  • Top up a balance account from an external source.
  • Send money from a balance account.
  • Convert funds between two balances in different currencies.
  • View the transaction history for a balance account.

Multi-currency account structure

The structure of a multi-currency account is as follows:

  1. A User has a profile (personal or business).
  2. A Profile has the ability to open a Multi-Currency Account.
  3. A Multi-Currency Account has the ability to have multiple Balance Accounts in different currencies.
  4. A Balance Account has a specific currency and can contain a set of Bank Account Details.
  5. Bank Account Details are a set of local account details.

The diagram below illustrates the relationships between each of the components highlighted above.

Multi-Currency Accounts Structure Diagram

Authentication

Base URL Sandbox

https://api.sandbox.transferwise.tech

Base URL LIVE

https://api.transferwise.com

All calls relating to multi-currency accounts are authenticated with an Authorization: Bearer {{access-token}} header. This is specific to the user, is referred to as an API token, and can be obtained directly from the Settings > API tokens page for a logged-in user. An example is included with each endpoint that shows the correct header format.

To operate on multi-currency accounts and account balances, you will need to request a customer access token using the proper authentication flow. Guides on customer authentication can be found here:

Profiles

Most endpoints included in this guide require a profile ID and/or a balance ID as part of the path. These are denoted with {{profileId}} and {{balanceId}} throughout the guide, and are obtained from previous requests to endpoints as outlined.

Additional headers

Accept-Language

Each endpoint accepts an additional header of Accept-Language. This should include an ISO 639-1 language code. This will default to en if it is not passed as part of the request. The examples in this guide include the header for those calls that return translated strings.

Content-Type

Endpoints that include a body require a Content-Type: application/json header to be included. This is included in the examples where required.

Postman collection

We've created a postman collection for the multi-currency accounts API that follows along the same flows as documented below. Please use this to test your integrations.

In the collection, we have done a few things to make life a bit easier:

  • Included our sandbox environment, where you can fully test your integration.
  • Included a set of the common calls required to create new users and profiles through bank and connected app authorizations.
  • Included tests that automatically copy details from previous calls to environment variables.
  • Examples of successful call results for quick reference.

All of these additions should allow you to easily test through the entire flow with minimal efforts.

We recommend as well that you fork the collection. This allows you to receive updates and bug fixes as they become available.

Multi-Currency Accounts

Multi-currency account management endpoints allow you to manage the user's multi-currency account overall. We have also included information on getting profile information for an authenticated customer.

Generally, the following flow should be taken to open a multi-currency account:

  1. Get profile - Get the profile ID of the profile you want to operate on.
  2. List available currencies - Determine which currencies are supported for the user.
  3. Get multi-currency Account - Get current multi-currency accounts and balance accounts for the profile, determine next steps.
  4. Check eligibility - Check the eligibility of the profile for multi-currency accounts.
  5. Create a multi-currency account - Create a multi-currency account and first balance account for the profile, if not already created.

Get profile

Example Request:

curl -X GET https://api.sandbox.transferwise.tech/v2/profiles \
     -H "Authorization: Bearer {{access-token}}"

Example Response:

[
  {
    "type": "PERSONAL",
    "id": 16155137,
    "userId": 5682283,
    "address": {
      "addressFirstLine": ".......",
      "city": "London",
      "countryIso2Code": "GB",
      "countryIso3Code": "gbr",
      "postCode": "ABC123",
      "stateCode": null
    },
    "email": "",
    "createdAt": "2021-03-25T15:18:35.000Z",
    "updatedAt": "2021-03-25T15:18:35.000Z",
    "obfuscated": false,
    "currentState": "VISIBLE",
    "firstName": "Oliver",
    "lastName": "Wilson",
    "dateOfBirth": "1967-04-03",
    "phoneNumber": "+442038087139",
    "secondaryAddresses": [],
    "fullName": "Oliver Wilson"
  },
  {
    "type": "BUSINESS",
    "id": 16155138,
    "userId": 5682283,
    "address": {
      "addressFirstLine": ".......",
      "city": "London",
      "countryIso2Code": "GB",
      "countryIso3Code": "gbr",
      "postCode": "ABC123",
      "stateCode": null
    },
    "email": "",
    "createdAt": "2021-03-25T15:18:38.000Z",
    "updatedAt": "2021-03-25T15:18:38.000Z",
    "obfuscated": false,
    "currentState": "VISIBLE",
    "businessName": "ABC Logistics Ltd",
    "registrationNumber": "07209813",
    "descriptionOfBusiness": "IT_SERVICES",
    "companyType": "LIMITED",
    "companyRole": "OWNER",
    "operationalAddresses": [],
    "fullName": "ABC Logistics Ltd"
  }
]

Purpose

Get the existing profile IDs of the authenticated user. Some endpoints require a profile ID to be passed in the request. Both personal and business profiles will be returned in this call, and multiple business accounts can exist.

Full API Reference

List User Profiles

List available currencies

Example Request:

curl -X GET https://api.sandbox.transferwise.tech/v2/borderless-accounts-configuration/profiles/{{personal-profile-id}}/available-currencies \
     -H "Authorization: Bearer {{access-token}}" 

Example Response:

[
  "EUR",
  "GBP",
  "USD",
  ...
]

Purpose

This endpoint returns all the currencies available for balance accounts. You can use this list to create a balance account for the currency included.

Full API Reference

List Available Currencies

Get multi-currency account

Example Request:

curl -X GET https://api.sandbox.transferwise.tech/v4/profiles/{{profileId}}/multi-currency-account \
     -H "Authorization: Bearer {{access-token}}"

Example Response - 200: Account Exists

{
    "id": < multi-currency account Id >,
    "profileId": < profile Id >,
    "recipientId": 12345678,
    "creationTime": "2020-05-20T14:43:16.658Z",
    "modificationTime": "2020-05-20T14:43:16.658Z",
    "active": true,
    "eligible": true
}

Example Response - 404: Not Found

No Content

Purpose

This endpoint returns the multi-currency account details for the specified profileId. If the user does not yet have a multi-currency account, a 404 Not Found will be returned.

If the user already has a multi-currency account, then you can move forward to create and manage Balance Accounts.

If the user does not have a multi-currency account, then you should check eligibility and create a multi-currency account.

Check eligibility

Example Request:

curl -X GET https://api.sandbox.transferwise.tech/v4/multi-currency-account/eligibility?profileId={{profileId}} \
     -H "Authorization: Bearer {{access-token}}"

Example Response:

{
  "eligible": true,
  "eligibilityCode": "eligible",
  "accountType": "FULL",
  "ineligibilityReason": null
}

Purpose

This endpoint checks that the customer is eligible for a multi-currency account for a specific profile. Customers in some countries may not be eligible for a multi currency account.

The profileId should be passed as a parameter instead of in the path.

Response

Field Description Format
eligible Profile is eligible for MCA Account Boolean
eligibilityCode Reason for the ineligibility eligible, invalid.profile.type, invalid.country, or invalid.state
accountType Account type available INELIGIBLE, RECEIVE_ONLY or FULL. Generally this will be returned as FULL.
ineligibilityReason Reason the profile is not eligible String

Create a multi-currency account

To create a multi-currency account, you simply need to open a balance in at least one currency. When doing so, a multi-currency account will automatically be created. To move forward, you should create a balance account.

Balance Accounts

Balance accounts are the accounts that sit inside the multi-currency account and hold the currency balance, ledger of transactions, and other details specifically for that account. For the purpose of this guide, only STANDARD balances will be included/discussed. Additional types, such as jars (type = SAVINGS) will be ignored.

The balance account endpoints are provided to create, view and manage the balance accounts for a particular profile and a particular multi-currency account. They also are what is used to create a multi-currency account when one does not exist for a profile.

Via the Multi-Currency Account Management section, you should know the profileId you want to operate on, what balance account currencies you want to open, and should have created the multi-currency account and first balance account for the profile. The next steps are to:

  1. Create a balance account - Create the first or subsequent balance accounts in a different currencies.
  2. List all balance accounts - List the balance accounts currently included in the multi-currency account for this profile.
  3. Get balance account by ID - Get the details of a balance account by its ID.
  4. Delete balance account - Remove a balance account from a multi-currency account.
  5. Get balance account statement - Get a balance account statement for a specified time range.

Prerequisites & Notes

Investment Status

Balance accounts include a field of investmentStatus. This can include multiple different statuses, however the one to watch for is NOT_INVESTED. If a balance has any other value, then the balance should not and currently cannot be operated on via the API.

If a balance is invested, it should still be shown, however it should be shown as an un-operable balance in your integration. This should only be the case for user accounts that are linked and already have balances, but should be taken into account when building your integration.

Create a balance account

Example Request:

curl -X POST https://api.sandbox.transferwise.tech/v4/profiles/{{profileId}}/balances \
     -H "Authorization: Bearer {{access-token}}" \
     -H "Content-Type: application/json" \
     -H "Accept-Language: {{ISO 639-1}}" \
     -d '{
          "type": "STANDARD",
          "currency": "SGD",
          "name": "My SGD Balance"
        }'

Example Response:

{
  "id": 102359,
  "currency": "SGD",
  "amount": {
    "value": 50.00,
    "currency": "SGD"
  },
  "reservedAmount": {
    "value": 0.00,
    "currency": "SGD"
  },
  "cashAmount": {
    "value": 50.00,
    "currency": "SGD"
  },
  "totalWorth": {
    "value": 50.00,
    "currency": "SGD"
  },
  "type": "STANDARD",
  "name": null,
  "icon": null,
  "investmentState": "NOT_INVESTED",
  "creationTime": "2022-03-21T11:52:17.583606Z",
  "modificationTime": "2022-03-21T14:25:03.843759Z",
  "visible": true
}

Purpose

This endpoint creates a new balance account for the currency provided, or returns the details of the balance account if already created. If this is the first balance account, it will also create a multi-currency account for the profile.

When creating a balance, you must send the currency and "type": "STANDARD" as this creates a standard balance account in that currency. You also can optionally pass a name which will be assigned to that balance.

List all balance accounts

Example Request:

curl -X GET https://api.sandbox.transferwise.tech/v4/profiles/{{profileId}}/balances?types={{type}} \
     -H "Authorization: Bearer {{access-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 lists all balance accounts for a particular profile and multi-currency account. It can only be used after a multi-currency account has been created with the POST endpoint.

The types query parameter must be passed with either STANDARD (normal currency balance) or SAVINGS ( JAR or SAVINGS balance)

Get balance account by ID

Example Request:

curl -X GET 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

This endpoint returns the information of the balance account.

Close balance account

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 a 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": {
    "id": 12345678,
    "currency": "USD",
    "bankCode": "CMFABC123",
    "accountNumber": "12345678",
    "swift": "CMFABC123",
    "bankName": "TransferWise",
    "accountHolderName": "Test Profile",
    "bankAddress": {
      "addressFirstLine": "19 W 24th Street",
      "postCode": "10010",
      "city": "New York",
      "country": "United States",
      "stateCode": "NY"
    }
  },
  "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 end 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
statementLocale (optional) used to specify the language of the PDF format. Text; example: en-US, es, fr, de, ro etc.

Response

For full details of the response and what should be expected, see the full API reference for Get Statement.

Additional Authentication Requirements

This endpoint is subject to additional authentication requirements. The additional authentication is only required once every 90 days, viewing the statement on the website or in the mobile app counts towards that as well.

Bank Account Details

Bank account detail endpoints are provided to create, view, and manage bank account details for an account balance.

Via the Multi-Currency Accounts and Balance Accounts sections of this guide, you will know the profile and multi-currency account, as well as the specific balance accounts created. The next optional steps are:

  1. List current bank account details - View a list of all existing bank account details for the multi-currency account.
  2. Request bank account details - Create a request for bank account details to be added to the profile and multi-currency account.
  3. List bank account detail orders - View open requests for bank account details on the profile and multi-currency account.

List bank account details

Example Request:

curl -X GET https://api.sandbox.transferwise.tech/v1/profiles/{{profileId}}/account-details \
     -H "Authorization: Bearer {{access-token}}" \
     -H "Accept-Language: {{ISO 639-1}}" 

Example Response:

[
  {
    "id": null,
    "currency": "EUR",
    "holderName": "John Smith",
    "bankCode": {
      "swiftCode": "TRWIBEB1XXX"
    },
    "accountNumber": {
      "iban": "BE29 9670 0000 0164"
    },
    "address": {
      "default": {
        "firstLine": "TransferWise Europe SA",
        "secondLine": "Avenue Louise 54, Room S52",
        "city": "Brussels",
        "postCode": "1050",
        "country": "Belgium",
        "stateCode": null
      }
    },
    "limits": {
      "daily": {
        "currency": "EUR",
        "value": null
      },
      "yearly": {
        "currency": "EUR",
        "value": null
      }
    },
    "status": "AVAILABLE",
    "deprecated": false,
    "alert": null,
    "bankFeatures": [
      {
        "id": 3,
        "key": "LOCAL_RECEIVE",
        "description": "Receive locally",
        "supported": true
      },
      {
        "id": 4,
        "key": "SWIFT",
        "description": "Receive internationally (SWIFT)",
        "supported": true
      },
      {
        "id": 2,
        "key": "DIRECT_DEBITS",
        "description": "Set up Direct Debits",
        "supported": true
      },
      {
        "id": 5,
        "key": "PLATFORM_RECEIVE",
        "description": "Receive from PayPal and Stripe",
        "supported": true
      }
    ],
    "translations": {
      "accountHolderName": "TW account holder",
      "holderName": "TW account holder",
      "accountNumber.iban": "IBAN",
      "bankCode.swiftCode": "Bank code (SWIFT/BIC)",
      "address.default": "Address",
      "title": "New details",
      "accountLimits.daily": "24 hour receive limit",
      "accountLimits.yearly": "Annual receive limit"
    }
  },
  ...
]

Purpose

This endpoint returns bank account details for each currency in the profile, including examples.

Example bank account details are returned for any currency where bank account details have not been requested and issued. Examples will always include an id of null.

Request bank account details

Example Request:

curl -X POST https://api.sandbox.transferwise.tech/v1/profiles/{{profileId}}/account-details-orders \
     -H "Authorization: Bearer {{access-token}}" \
     -H "Content-Type: application/json" \
     -H "Accept-Language: {{ISO 639-1}}" \
     -d '{
	      "currency": "EUR"
        }'

Example Response:

{
  "status": "PENDING_USER",
  "currency": "EUR",
  "requirements": [
    {
      "type": "TOP_UP",
      "status": "DONE"
    },
    {
      "type": "VERIFICATION",
      "status": "PENDING_USER"
    }
  ]
}

Purpose

This endpoint requests bank account details for the currency specified in the path. Once received, we will issue the bank account details when possible.

For bank account details to be issued, a series of requirements must be met. The status of the returned object can be:

  • PENDING_USER - A requirement has not been met and the user needs to take an action.
  • PENDING_TW - The issuance is pending something on Wise's side.
  • DONE - The issuance of the bank account details is complete.

Currently, two types of requirements can be returned:

  • "type": "TOP_UP" - A top-up is required on the balance for this currency before bank account details will be issued.
  • "type": "VERIFICATION" - Verification on the profile is required before the bank account details can be issued.

Sandbox Postman Top Up

In the included Postman Collection, two additional endpoints are included for use with our Sandbox environment only. This allows you to top up a balance with funds as well as verify a profile directly. Please use these endpoints in your testing in sandbox.

List bank account details orders

Example Request:

curl -X GET https://api.sandbox.transferwise.tech/v1/profiles/{{profileId}}/account-details-orders \
     -H "Authorization: Bearer {{access-token}}" \
     -H "Accept-Language: {{ISO 639-1}}" 

Example Response:

[
  {
    "status": "PENDING_USER",
    "currency": "EUR",
    "requirements": [
      {
        "type": "TOP_UP",
        "status": "PENDING_USER",
      },
      {
        "type": "VERIFICATION",
        "status": "PENDING_USER",
      }
    ]
  },
  ...
]

Purpose

This endpoint returns the bank account assignment requests for a profile and multi-currency account.

Transfer To Balance Account

There are two different ways you can transfer money to a multi-currency balance accounts:

  1. Simply send domestic bank transfer from a bank account to the balance account's bank account details (e.g. IBAN, sort code & account number, etc.). There is no need to set up a quote/transfer in this case.

  2. Create a quote/transfer and then fund that transfer as per requirements.

Create quote

Step 1 - Create quote:

curl -X POST https://api.sandbox.transferwise.tech/v3/profiles/{{profileId}}/quotes \
     -H "Authorization: Bearer {{access-token}}" \
     -H "Content-Type: application/json" \
     -d '{
          "sourceCurrency": "GBP",
          "targetCurrency": "USD",
          "sourceAmount": 100,
          "targetAmount": null,
          "payOut": "BALANCE",
          "preferredPayIn": null
        }'

First, create a quote in the same way as described in Create quote.

You must set the payOut as BALANCE in order to get the correct pricing in the quote for this type of quote. By not doing so, it will default to BANK_TRANSFER and the fees will be inconsistent between quote and transfer.

Get multi-currency account recipientId

Step 2 - Find out the user's multi-currency account recipient id:

curl -X GET https://api.sandbox.transferwise.tech/v4/profiles/{{profileId}}/multi-currency-accounts \
     -H "Authorization: Bearer {{access-token}}" 

Example Response:

[
    {
        "id": 64,
        "profileId": <your profile id>,
        "recipientId": <your multi-currency account recipient id>,
        ...
   }
]

Next, call Check account balance endpoint and get the recipientId field value from the response.

Note that recipientId does not change so can be stored and reused.

Create transfer

Step 3 - Create transfer:

curl -X POST https://api.sandbox.transferwise.tech/v1/transfers \
     -H "Authorization: Bearer {{access-token}}" \
     -H "Content-Type: application/json" \
     -d '{ 
          "targetAccount": {{recipientId}},   
          "quote": {{quoteId}},
          "customerTransactionId": "{{uniqueIdentifier}}",
          "details" : {
              "reference" : "optional text to identify your transfer"
            } 
         }'

Next, create a transfer. This is the same call as described in Create transfer, however the value for targetAccount should be the recipientId as determined from the previous step.

As per the standard create transfer flow, you also need to create and pass a customerTransactionId for idempotency.

Fund transfer

Once the transfer is created, a method will be required to fund the transfer. This will differ based on your specific integration. For more details on funding transfers, see:

Transfer From Balance Account

Transferring from a balance follows the exact same flow as a standard transfer, with the exception being that it is funded from balance.

The steps below illustrate the flow required to create a quote, recipient, and transfer. Once the transfer is created, it can then be funded from the balance account

Generate transfer

Follow the guides below to create a quote, recipient, and transfer as per the usual flow.

Fund from balance

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
}

Once the transfer is created, this call is the final step for executing the payout. Upon calling the endpoint Wise will debit funds from the user's multi-currency account's balance with the matching currency and start processing the transfer. You cannot fund a transfer in this way unless you already hold funds in the sourceCurrency of the transfer.

If the multi-currency account does not have the required funds to complete the action in the correct currency, then this call will fail with an "insufficient funds" error. To correct this, a from balance to balance will first need to be completed.

API Reference

Funding a transfer

Convert from Balance to Balance

Converting funds from one balance account to another occurs in two parts. It's easiest to think of it as a transfer, with a standard quote being required first, and then the funding being made from balance to a balance.

To complete the transfer, follow these two steps:

  1. Create a quote - Use the quotes api to generate a quote for the transfer between balance accounts.
  2. Execute the quote - Approve the transfer and execute it.

Create a quote

Example Request:

curl -X POST https://api.sandbox.transferwise.tech/v3/profiles/{{profileId}}/quotes \
     -H "Authorization: Bearer {{access-token}}" \
     -H "Accept-Language: {{ISO 639-1}}" \
     -H "Content-Type: application/json" \
     -d '{
          "sourceCurrency": "GBP",
          "targetCurrency": "USD",
          "sourceAmount": 100,
          "targetAmount": null,
          "payOut": "BALANCE"
        }'

Example Response:

{
  "id": <<quoteId>>,
  "profile": <<profileId>>,
  "user": <<userId>>,
  "sourceAmount": 100.00,
  "guaranteedTargetAmountAllowed": true,
  "targetAmountAllowed": true,
  "transferFlowConfig": {
    "highAmount": {
      "showFeePercentage": false,
      "trackAsHighAmountSender": false,
      "showEducationStep": false,
      "offerPrefundingOption": false,
      "overLimitThroughCs": false
    }
  },
  "rateTimestamp": "2022-03-18T15:34:59Z",
  "clientId": "transferwise-personal-tokens",
  "type": "REGULAR",
  "status": "PENDING",
  "rate": 1.3154,
  "targetCurrency": "USD",
  "sourceCurrency": "GBP",
  "createdTime": "2022-03-18T15:36:05Z",
  "rateType": "FIXED",
  "rateExpirationTime": "2022-03-18T17:36:05Z",
  "payOut": "BALANCE",
  "guaranteedTargetAmount": false,
  "providedAmountType": "SOURCE",
  "expirationTime": "2022-03-18T16:06:05Z",
  "payInCountry": "GB",
  "funding": "POST"
  "paymentOptions": [
    {
      "formattedEstimatedDelivery": "by March 21st",
      "estimatedDeliveryDelays": [],
      "allowedProfileTypes": [
        "PERSONAL",
        "BUSINESS"
      ],
      "payInProduct": "BALANCE",
      "feePercentage": 0.0035,
      "estimatedDelivery": "2022-03-21T12:30:00Z",
      "sourceAmount": 100.00,
      "targetAmount": 131.08,
      "targetCurrency": "USD",
      "sourceCurrency": "GBP",
      "payOut": "BALANCE",
      "fee": {
        "transferwise": 0.35,
        "payIn": 0.0,
        "discount": 0,
        "total": 0.35,
        "priceSetId": 134,
        "partner": 0.0
      },
      "price": {
        "priceSetId": 134,
        "total": {
          "type": "TOTAL",
          "label": "Total fees",
          "value": {
            "amount": 0.35,
            "currency": "GBP",
            "label": "0.35 GBP"
          }
        },
        "items": [
          {
            "type": "TRANSFERWISE",
            "label": "Our fee",
            "value": {
              "amount": 0.35,
              "currency": "GBP",
              "label": "0.35 GBP"
            }
          }
        ]
      },
      "payIn": "BALANCE",
      "disabled": false
    },
    ...
  ],
  "notices": []
}

To begin the process of converting funds from one balance account to another, you first need to generate a quote.

Creating the quote will require input data that includes the source and target currency, the amount of either the source or target, and the payout of BALANCE. If you supply both source and target amounts, the call will fail.

The returned quote will return multiple payout options, with one having a value for payIn and payOut of BALANCE. If the profile does not have a balance account in each of those currencies, then this option will be returned with "disabled": true.

The balance to balance option contains further details on the cost of the conversion, including the fees included and either the final source or target amount.

The quote will also contain the rate, which will be locked for 30 minutes to give time to create the transfer, after which the rate lock is extended.

Execute the transfer

Example Request:

curl -X POST https://api.sandbox.transferwise.tech/v2/profiles/{{profileId}}/balance-movements \
     -H "Authorization: Bearer {{access-token}}" \
     -H "Accept-Language: {{ISO 639-1}}" \
     -H "Content-Type: application/json" \
     -H "X-idempotence-uuid: {{generatedUuid}} \
     -d '{
            "quoteId": {{quoteId}}
         }'

Example Response:

{
  "id": <<conversion transaction id>>,
  "type": "CONVERSION",
  "state": "COMPLETED",
  "accountId": <<userId>>,
  "channelName": "BALANCE",
  "channelReferenceId": "2563987",
  "balancesAfter": [
    {
      "id": 100942,
      "value": 1075450.52,
      "currency": "GBP",
      "cashAmount": {
        "value": 1075450.52,
        "currency": "GBP"
      },
      "availableAmount": {
        "value": 1075450.52,
        "currency": "GBP"
      },
      "totalWorth": {
        "value": 1075450.52,
        "currency": "GBP"
      }
    },
    {
      "id": 100944,
      "value": 2900131.30,
      "currency": "USD",
      "cashAmount": {
        "value": 2900131.30,
        "currency": "USD"
      },
      "availableAmount": {
        "value": 2900131.30,
        "currency": "USD"
      },
      "totalWorth": {
        "value": 2900131.30,
        "currency": "USD"
      }
    }
  ],
  "creationTime": "2022-03-18T15:59:01.816Z",
  "steps": [
    {
      "id": 5016135,
      "transactionId": 2563987,
      "type": "CONVERSION",
      "creationTime": "2022-03-18T15:59:01.816947Z",
      "balancesAfter": [
        {
          "value": 1075450.52,
          "currency": "GBP"
        },
        {
          "value": 2900131.30,
          "currency": "USD"
        }
      ],
      "channelName": "BALANCE",
      "channelReferenceId": "2563987",
      "tracingReferenceCode": null,
      "sourceBalanceId": 100942,
      "targetBalanceId": 100944,
      "sourceAmount": {
        "value": 100.00,
        "currency": "GBP"
      },
      "targetAmount": {
        "value": 131.30,
        "currency": "USD"
      },
      "fee": {
        "value": 0.35,
        "currency": "GBP"
      },
      "rate": 1.31760000
    }
  ],
  "sourceAmount": {
    "value": 100.00,
    "currency": "GBP"
  },
  "targetAmount": {
    "value": 131.30,
    "currency": "USD"
  },
  "rate": 1.31760000,
  "feeAmounts": [
    {
      "value": 0.35,
      "currency": "GBP"
    }
  ]
}

Once a quote is generated, you are able to execute that transfer from one balance to the other. This endpoint converts funds between those balance accounts using the quoteId.

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

Events Notifications & Webhooks

Certain webhooks should be subscribed to and listened for with relation to multi-currency accounts and related transactions on balance accounts.

Profile based subscriptions

The following two event types will update you on any changes or issues related with transfers and balance accounts for the profile. These are profile specific, and therefore need to be subscribed to on a profile basis.

  • transfers#active-cases - Monitors and alerts for any issues with a transfer.
  • balances#credit - Monitors and alerts if any credits are applied to a balance. Useful for when pay in may take time to complete or if being paid from another source.

It's recommended that subscriptions for these endpoints be included in your integration to monitor for transactions on the balance and if there are any issues with transfers.

Integration based subscriptions

The following two event types are available for the verification of profiles and for monitoring transfer state changes. These are supported at an integration level (subscribe once for the entire integration).

Full webhook reference

Webhook Documentation

Addresses

Create/Update

Example Request:

curl -X POST https://api.sandbox.transferwise.tech/v1/addresses \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "profile": <your profile id>,
          "details": {
            "country": "EE",
            "firstLine": "Narva mnt 5-1",
            "postCode": "10113",
            "city": "Tallinn",
            "occupations": [
              {
                "code": "Software Engineer",
                "format": "FREE_FORM"
              }
            ]
          }
        }'

Example Response:

{
  "id": 236532,
  "profile": <your profile id>,
  "details": {
    "country": "EE",
    "firstLine": "Narva mnt 5-1",
    "postCode": "10113",
    "city": "Tallinn",
    "state": "",
    "occupation": null,
    "occupations": [
      {
        "code": "Software Engnieer",
        "format": "FREE_FORM"
      }
    ]
  }
}

Adds address info to user profile. List of required fields are different for different countries.

State field is required for US, CA, BR and AU addresses.

Occupations is required for CA, IN, JP and within the US for the states AZ and NM. If you serve any of these jurisdictions we recommend submitting occupation for all customers for simplicity, however if this is an issue we can discuss alternative solutions.

Request

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

Field Description Format Validation Rules
profile User profile id. Integer ID of the user's personal or business profile
details.country 2 digit ISO country code. Text Two digit ISO code
details.firstLine Address line: street, house, apartment. Text
  • Must not be a PO box
  • Must not be made up of only special characters from regex `[!@#\$%^&*(),.?":{}
details.postCode Zip code Text (max 30 chars) Some country selections will check for valid post codes, e.g. Canada
details.city City name Text Is not "PO Box"
details.state State code. Required if country is US, CA, AU, BR Text Is valid state code for selected country (only required for US, BR, AU and CA)
details.occupation (Deprecated) User occupation. Required as described above. Text This is deprecated - use the occupations field below
details.occupations Array of occupations, currently one FREE_FORM occupation is supported, required as described above. Array (can be null or empty) Array
details.occupations[n].code User occupation Text Any value permitted
details.occupations[n].format Occupation type Text Always FREE_FORM

Response

Field Description Format
id Address id Integer
profile User profile id. Integer
details.country 2 digit ISO country code. Text
details.firstLine Address line: street, house, apartment. Text
details.postCode Zip code Text
details.city City name Text
details.state State code. Required if country is US, CA, AU, BR Text
details.occupation (Deprecated) User occupation. Required for US, CA, JP Text
details.occupations details.occupations Array of occupations, currently one FREE_FORM occupation is supported, required as described above.
details.occupations[n].code User occupation, any value permitted. Text
details.occupations[n].format Occupation type - always FREE_FORM Text

Get By Id

Example Request:

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

Example Response:

{
  "id": 236532,
  "profile": <your profile id>,
  "details": {
    "country": "EE",
    "firstLine": "Narva mnt 5-1",
    "postCode": "10113",
    "city": "Tallinn",
    "state": "",
    "occupation": null,
    "occupations": null
  }
}

Get address info by id.

Request

GET https://api.sandbox.transferwise.tech/v1/addresses/{addressId}

List

Example Request:

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

Example Response:

[
    {
        "id": 7099091,
        "profile": <your profile id>,
        "details": {
            "country": "EE",
            "firstLine": "Veerenni 29",
            "postCode": "12991",
            "city": "Tallinn",
            "state": null,
            "occupation": null,
            "occupations": null
        }
    }
]

List of addresses belonging to user profile.

Request

GET https://api.sandbox.transferwise.tech/v1/addresses?profile={profileId}

Requirements

Example Request:

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

Example Response:

[
  {
    "type": "address",
    "fields": [
      {
        "name": "Country",
        "group": [
          {
            "key": "country",
            "type": "select",
            "refreshRequirementsOnChange": true,
            "required": true,
            "displayFormat": null,
            "example": "Germany",
            "minLength": null,
            "maxLength": null,
            "validationRegexp": null,
            "validationAsync": null,
            "valuesAllowed": [
              {
                "key": "AX",
                "name": "Åland Islands"
              },
              ...
              {
                "key": "ZM",
                "name": "Zambia"
              }
            ]
          }
        ]
      },
      {
        "name": "City",
        "group": [
          {
            "key": "city",
            "type": "text",
            "refreshRequirementsOnChange": false,
            "required": true,
            "displayFormat": null,
            "example": "London",
            "minLength": null,
            "maxLength": null,
            "validationRegexp": null,
            "validationAsync": null,
            "valuesAllowed": null
          }
        ]
      },
      {
        "name": "Postal code",
        "group": [
          {
            "key": "postCode",
            "type": "text",
            "refreshRequirementsOnChange": false,
            "required": true,
            "displayFormat": null,
            "example": "10025",
            "minLength": null,
            "maxLength": null,
            "validationRegexp": null,
            "validationAsync": null,
            "valuesAllowed": null
          }
        ]
      }
      ...
    ]
  }
]

Request

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

GET and POST address-requirements endpoints help you to figure out which fields are required to create a valid address for different countries. You could even build a dynamic user interface on top of these endpoints. This is a step-by-step guide on how these endpoints work.

  1. Call GET /v1/address-requirements to get list of fields you need to fill with values in "details" section for creating a valid address. Response contains 4 required top level fields:
  • country (select field with list of values)
  • city (text field)
  • postCode (text field)
  • firstLine (text field)
  1. Analyze the list of fields. Because refreshRequirementsOnChange for field 'country' is marked as true then this indicates that there are additional fields required depending on the selected value.

  2. Call POST /v1/address-requirements with selected country value to expose sub fields.
    For example posting {"details": {"country" : "US"}} will also add "state" to list of fields.
    But posting {"details": {"country" : "GB"}} will not.

  3. If you choose "US" as country you will notice that "state" field also has refreshRequirementsOnChange=true. This means you would need to make another POST call to /v1/address-requirements with a specific state value.
    For example posting {"details": { "country" : "US", "state": "AZ" }} will also add "occupation" to list of fields.
    But posting {"details": { "country" : "US", "state": "AL" }} will not.

  4. So 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 an address object. For example this is a valid request to create address in US Arizona:
    POST /v1/addresses:
    { "profile" : your-profile-id,
    "details": {
    "country" : "US",
    "state": "AZ",
    "city": "Phoenix",
    "postCode": "10025",
    "firstLine": "50 Sunflower Ave.",
    "occupation": "software engineer"
    } }

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

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

Bank Account Detail

Get account details

Example Request:

curl -X GET https://api.sandbox.transferwise.tech/v1/profiles/{profile-id}/account-details \
     -H "Authorization: Bearer <your api token>"

Example Response:

[
  {
    "id": 1,
    "currency": {
      "code": "EUR",
      "name": "Euro"
    },
    "title": "Your EUR account details",
    "subtitle": "IBAN, SWIFT/BIC",
    "status": "ACTIVE",
    "deprecated": false,
    "receiveOptions": [
      {
        "type": "LOCAL",
        "title": "Inside EU and SEPA",
        "description": {
          "title": "Your EUR account details",
          "body": "<p>Use the details below to add or receive EUR from bank accounts inside EU and SEPA.</p><a href=\"https://wise.com/help/17/borderless-account/2827505/how-do-i-use-my-eur-bank-details\" rel=\"noopener\" target=\"_blank\">See how to use EUR account details</a>",
          "cta": null
        },
        "summaries": [
          {
            "type": "TIME",
            "title": "Incoming payments take 1–2 working days to be added to your account",
            "description": null
          },
          {
            "type": "INFO",
            "title": "SEPA includes countries in the EU and EEA",
            "description": {
              "title": "What’s SEPA?",
              "body": "\n<p>SEPA stands for the Single Euro Payments Area. Within this area, cross-border euro payments must cost the same as a regular, local one. It’s EU law.</p>\n<p>SEPA covers all the countries within the EU. It also includes other European countries like Monaco, Norway, and Switzerland.</p>\n<p>So if your sender is sending from a euro bank account in one of these countries, they shouldn’t have to pay much — if anything — to send money to your EUR account details.</p>\n<h5>Good to know</h5>\n<ul><li>SEPA payments to your EUR account details usually take 1–2 working days.</li><li>Just because a country uses euros, doesn’t mean it’s in SEPA. Please check the list below if you’re unsure.</li></ul>\n<p><a href=\"https://wise.com/help/15/paying-for-your-transfer/2968880/sepa-countries-and-ibans\" rel=\"noopener\" target=\"_blank\">See the full list of SEPA countries</a></p>",
              "cta": null
            }
          }
        ],
        "details": [
          {
            "type": "ACCOUNT_HOLDER",
            "title": "Account holder",
            "body": "John Doe",
            "description": null,
            "hidden": false
          },
          {
            "type": "SWIFT_CODE",
            "title": "BIC",
            "body": "TRWIBEB1XXX",
            "description": null,
            "hidden": false
          },
          {
            "type": "IBAN",
            "title": "IBAN",
            "body": "BE58 9671 0000 0000",
            "description": {
              "title": "Did they ask for an account number?",
              "body": "\n<p>For most kinds of payments, senders should use your IBAN number. But if they specifically ask for an account number, you can give them this:</p>\n<p><strong>1395167</strong></p>",
              "cta": {
                "label": "IBAN",
                "content": "BE58 9671 0000 0000"
              }
            },
            "hidden": false
          },
          {
            "type": "ADDRESS",
            "title": "Address",
            "body": "Avenue Louise 54, Room S52\nBrussels\n1050\nBelgium",
            "description": {
              "title": "Did they ask for a bank address?",
              "body": "\n<p>If your sender asks for a bank address, you can give them:</p>\n<p><strong>Avenue Louise 54, Room S52<br>Brussels<br>1050<br>Belgium</strong></p>\n<h5>What about the bank name?</h5>\n<p>You can use TransferWise as the bank name. That’s because in the Eurozone we’re directly plugged into the same payment networks as the big banks. It’s what keeps our payments fast and low-cost.</p>",
              "cta": {
                "label": "Address",
                "content": "Avenue Louise 54, Room S52\nBrussels\n1050\nBelgium"
              }
            },
            "hidden": false
          }
        ],
        "alert": null,
        "shareText": ""
      },
      {
        "type": "INTERNATIONAL",
        "title": "Outside EU and SEPA",
        "description": {
          "title": "Your EUR account details",
          "body": "<p>Use the details below to add or receive EUR from bank accounts outside EU and SEPA.</p><a href=\"https://wise.com/help/17/borderless-account/2827505/how-do-i-use-my-eur-bank-details\" rel=\"noopener\" target=\"_blank\">See how to use EUR account details</a>",
          "cta": null
        },
        "summaries": [
          {
            "type": "TIME",
            "title": "Incoming payments take 4–5 working days to be added to your account",
            "description": null
          }
        ],
        "details": [
          {
            "type": "ACCOUNT_HOLDER",
            "title": "Account holder",
            "body": "John Doe",
            "description": null,
            "hidden": false
          },
          {
            "type": "SWIFT_CODE",
            "title": "SWIFT/BIC",
            "body": "TRWIBEB1XXX",
            "description": null,
            "hidden": false
          },
          {
            "type": "IBAN",
            "title": "IBAN",
            "body": "BE58 9671 0000 0000",
            "description": {
              "title": "Did they ask for an account number?",
              "body": "\n<p>For most kinds of payments, senders should use your IBAN number. But if they specifically ask for an account number, you can give them this:</p>\n<p><strong>1395167</strong></p>",
              "cta": {
                "label": "IBAN",
                "content": "BE58 9671 0000 0000"
              }
            },
            "hidden": false
          },
          {
            "type": "ADDRESS",
            "title": "Address",
            "body": "Avenue Louise 54, Room S52\nBrussels\n1050\nBelgium",
            "description": {
              "title": "Did they ask for a bank address?",
              "body": "\n<p>If your sender asks for a bank address, you can give them:</p>\n<p><strong>Avenue Louise 54, Room S52<br>Brussels<br>1050<br>Belgium</strong></p>\n<h5>What about the bank name?</h5>\n<p>You can use TransferWise as the bank name. That’s because in the Eurozone we’re directly plugged into the same payment networks as the big banks. It’s what keeps our payments fast and low-cost.</p>",
              "cta": {
                "label": "Address",
                "content": "Avenue Louise 54, Room S52\nBrussels\n1050\nBelgium"
              }
            },
            "hidden": false
          }
        ],
        "alert": null,
        "shareText": ""
      }
    ],
    "bankFeatures": [
      {
        "key": "LOCAL_RECEIVE",
        "title": "Receive locally",
        "supported": true
      },
      {
        "key": "SWIFT",
        "title": "Receive internationally (SWIFT)",
        "supported": true
      },
      {
        "key": "DIRECT_DEBITS",
        "title": "Set up Direct Debits",
        "supported": true
      },
      {
        "key": "PLATFORM_RECEIVE",
        "title": "Receive from PayPal and Stripe",
        "supported": true
      }
    ]
  },
  {
    "id": null,
    "currency": {
      "code": "TRY",
      "name": "Turkish lira"
    },
    "title": "Your TRY account details",
    "subtitle": "IBAN",
    "status": "AVAILABLE",
    "deprecated": false,
    "receiveOptions": [],
    "bankFeatures": [
      {
        "key": "LOCAL_RECEIVE",
        "title": "Receive locally",
        "supported": true
      },
      {
        "key": "SWIFT",
        "title": "Receive internationally (SWIFT)",
        "supported": false
      },
      {
        "key": "DIRECT_DEBITS",
        "title": "Set up Direct Debits",
        "supported": false
      },
      {
        "key": "PLATFORM_RECEIVE",
        "title": "Receive from PayPal and Stripe",
        "supported": false
      }
    ]
  }
]

Purpose

This endpoint returns a list with all the AVAILABLE and ACTIVE account details for the given profile, including examples. Account receive options can also include local and international details to receive money on the currency balance.

Example bank account details are returned for any currency where bank account details have not been requested and issued. Examples will always include an id of null.

Request

GET https://api.sandbox.transferwise.tech/v1/profiles/{profile-id}/account-details

Response

Important response fields to pay attention:

status (text) AVAILABLE: Account details do not exist for the user but may be created ACTIVE: Account details are ready to be used by this user

deprecated (boolean) Important! When the value is true, Wise issued another account details for the same currency. The users should not use the deprecated account anymore, but they still need to be informed as they might have external references pointing to the old one.

receiveOptions (array) This array will contain the available receive options for the given currency. LOCAL: local bank details to receive money in the account currency INTERNATIONAL: SWIFT bank details to receive money internationally in the account currency.

receiveOptions.details (array) It returns all the details that need to be displayed to users to make transfers to this account. This array will vary from currency to currency as each one has its requirements. For example, EUR will return ACCOUNT_HOLDER, SWIFT_CODE, IBAN and ADDRESS, whereas GBP will return ACCOUNT_HOLDER, BANK_CODE, ACCOUNT_NUMBER, IBAN and ADDRESS.

Each element in this array will contain the following attributes:

type: String informing the account detail type title: Label to display in the UI body: Value to display in the UI description: When present, it has the content to show a tooltip/popup hint hidden: If the field should be displayed or not in the UI

Here is an example of how wise.com displays the GBP receiveOptions.details for local payments:

image

Create account details order

Creates an order which will issue account details. It should use the same currency as the balance previously created. Fulfilling all the requirements will complete the order. That means reaching status DONE.

The possible values for a requirement are: PENDING_USER: The requriement has some pending action from the user. PENDING_TW: The requirement has some pending action from Wise. DONE: The requirement is completed

The more common requirements are: VERIFICATION: The user needs to be fully verified before complete this requirement. TOP_UP: A fee will be charged and must be paid using through wise.com before complete this requirement.

Example Request:

curl -L -g -X POST 'https://api.sandbox.transferwise.tech/v1/profiles/{profile-id}/account-details-orders' \
  -H 'Authorization: Bearer <your api token>' \
  -H 'Content-Type: application/json' \
  --data-raw '{
      "currency": "EUR"
  }'

Example Response:

{
  "status": "PENDING_USER",
  "currency": "EUR",
  "requirements": [
    {
      "type": "VERIFICATION",
      "status": "PENDING_USER"
    }
  ]
}

Request

POST https://api.sandbox.transferwise.tech/v1/profiles/{profile-id}/account-details-orders

Field Description Format Required
currency balance currency (ISO 4217 Alphabetic Code) text true

Response

Field Description Format
status One of: PENDING_USER, PENDING_TW, DONE representing the current order status text
currency currency (ISO 4217 Alphabetic Code) text
requirements.type One of: VERIFICATION, TOP_UP text
requirement.status One of: PENDING_USER, PENDING_TW, DONE representing the current requirement status text

List bank account details orders

Example Request:

curl -X GET https://api.sandbox.transferwise.tech/v1/profiles/{{profileId}}/account-details-orders \
     -H "Authorization: Bearer {{access-token}}" \
     -H "Accept-Language: {{ISO 639-1}}" 

Example Response:

[
  {
    "status": "PENDING_USER",
    "currency": "EUR",
    "requirements": [
      {
        "type": "TOP_UP",
        "status": "PENDING_USER",
      },
      {
        "type": "VERIFICATION",
        "status": "PENDING_USER",
      }
    ]
  },
  ...
]

Purpose

This endpoint returns the bank account assignment requests for a profile and multi-currency account.

Batch Groups

A batch group is a named collection of transfers that can be managed as a single unit. Batch groups are primarily used for funding multiple transfers with a single pay in.

The Batch Group resource

Example batch group resource with bank transfer pay in details

{
    "id": "54a6bc09-cef9-49a8-9041-f1f0c654cd89",
    "version": 123,
    "name": "My batch group",
    "sourceCurrency": "GBP",
    "status": "COMPLETED",
    "transferIds": [
        123,
        456
    ],
    "payInDetails": [
        {
            "type": "bank_transfer",
            "reference": "B123",
            "amount": 123.45,
            "currency": "GBP",
            "name": "Wise",
            "bankCode": "231470",
            "accountNumber": "77643994",
            "iban": null
        }
    ]
}

Example batch group resource with additional details (USD source currency):

{
    "id": "54a6bc09-cef9-49a8-9041-f1f0c654cd89",
    "version": 123,
    "name": "My batch group",
    "sourceCurrency": "USD",
    "status": "COMPLETED",
    "transferIds": [
        123,
        456
    ],
    "payInDetails": [
        {
            "type": "bank_transfer",
            "reference": "B123",
            "amount": 123.45,
            "currency": "USD",
            "name": "Wise Inc",
            "bankCode": "091000019",
            "bankAddress": {
                "name": "Some Bank",
                "firstLine": "1 Some Street",
                "postCode": "10001",
                "city": "Some City",
                "stateCode": "NY",
                "country": "US"
            },
            "accountNumber": "123456789012",
            "accountType": "checking",
            "iban": null,
            "transferWiseAddress": {
                "name": "Wise Inc",
                "firstLine": "19 W 24th Street Floor 9",
                "postCode": "10010",
                "city": "New York",
                "country": "United States",
                "stateCode": "NY"
            }
        }
    ]
}

Example batch group resource with additional details (NOK source currency):

{
    "id": "54a6bc09-cef9-49a8-9041-f1f0c654cd89",
    "version": 123,
    "name": "My batch group",
    "sourceCurrency": "NOK",
    "status": "COMPLETED",
    "transferIds": [
        234,
        456
    ],
    "payInDetails": [
        {
            "type": "bank_transfer",
            "reference": "B5323",
            "amount": 12504.54,
            "currency": "NOK",
            "name": "TransferWise Ltd",
            "bankCode": "8301",
            "bankAddress": {
                "name": "CitiBank Europe Plc",
                "firstLine": "Bolette brygge 1",
                "postCode": "0252",
                "city": "Oslo",
                "country": "Norway",
                "stateCode": null
            },
            "transferWiseAddress": {
                "name": "TransferWise Ltd",
                "firstLine": "6th Floor, The Tea Building, 56 Shoreditch High Street",
                "postCode": "E1 6JJ",
                "city": "London",
                "country": "United Kingdom",
                "stateCode": null
            },
            "accountNumber": "9910728",
            "iban": null,
            "bban": "83019910728"
        }
    ]
}

Example batch group resource with additional details (HKD source currency):

{
    "id": "54a6bc09-cef9-49a8-9041-f1f0c654cd89",
    "version": 123,
    "name": "My batch group",
    "sourceCurrency": "HKD",
    "status": "COMPLETED",
    "transferIds": [
        234,
        456
    ],
    "payInDetails": [
        {
            "type": "bank_transfer",
            "reference": "B5323",
            "amount": 12504.54,
            "currency": "NOK",
            "name": "TransferWise Ltd",
            "bankCode": "8301",
            "bankAddress": {
                "name": "DBS Bank Hong Kong Limited",
                "firstLine": "99 Queen's Road Central",
                "postCode": null,
                "city": "Central",
                "country": "Hong Kong",
                "stateCode": null
            },
            "accountNumber": "478000216470",
            "iban": null,
            "fpsIdentifier": "hkd@wise.com"
        }
    ]
}

Many Batch Group API endpoints return a batch group resource. Batch group resources have the following properties:

Field Description Format
id Unique batch group ID. Text
version Batch version, used for concurrency control. This number is updated whenever there is a change to the batch group state (its status, the identity of the transfers in the batch, etc).

Some API operations will require this version in requests, and operations may be rejected when the requested version does not match the server’s version.

The version will be a signed integer and is not ordered with respect to any previous version.
Integer
name Descriptive name. Text
sourceCurrency Source currency as a three-character ISO 4217 currency code. This the currency expected to be used for funding the batch group. Text
status Current Batch Group Status (see below). Text
transferIds The IDs of all transfers successfully added to the group. Array
payInDetails List of pay in details (see Pay In Details below). Provided only when the batch-group is in the COMPLETED state. Array

Batch Group Status

Status Description
NEW New batch group with zero or more transfers. Able to have more transfers added to it. Any transfers in a NEW group cannot be yet be funded and paid out.
COMPLETED The batch group has had all the desired transfers added to it and is now closed to further changes. The transfers in the group are now able to be funded and paid out.

Note: COMPLETED does not imply that payouts have been successfully completed. It means that all required transfers have been created and associated with the batch group.
MARKED_FOR_CANCELLATION Cancellation of the transfers in the batch group was requested.
PROCESSING_CANCEL Transfers in the group are being cancelled. This takes time in Wise's system.
CANCELLED Transfers in the group have been cancelled.

Pay In Details

Pay In Details describe how the batch group can be funded. They are only populated when a batch group is in the COMPLETED state.

The following fields are always populated:

Field Description Format
type Method of payment. Currently supported types: bank_transfer. Text
reference The reference that should be used when funding the transfers in the batch group. This reference should be treated as an opaque value and there should be no attempt to decode or decompose it. Text
amount The total pay in amount for all transactions in the batch when paying-in with this reference and method. Decimal
currency Three-character ISO 4217 currency code. Text

These fields are populated when type is bank_transfer:

Field Description Format
name Name of the bank account holder. Text
branchName Name of the bank branch, provided only when the currency route requires it (such as JPY). Text
accountNumber Bank account number. Text
accountType The Bank Account Type, provided only when the currency route requires it. Text
bankCode Bank identifier or routing number, depending on pay in type and currency (see Pay In Details Bank Codes for details). Text
bankAddress The Pay In Details Address for the receiving bank, provided only when the currency route requires it. Object
transferWiseAddress Wise's Pay In Details Address, provided only when the currency route requires it. Object
iban ISO 13616 International Bank Account Number (when available). Text
bban Basic Bank Account Number (BBAN). Provided only when the currency route requires it (such as NOK). Text
institutionNumber Financial Institution number (3 digits). Provided only when the currency route requires it (such as CAD). Text
transitNumber Branch Transit Number (5 digits). Provided only when the currency route requires it (such as CAD). Text
beneficiaryBankBIC Beneficiary Bank Business Identifier Code (BIC). Provided only when the currency route requires it (such as CAD). Text
intermediaryBankBIC Intermediary Bank Business Identifier Code (BIC). Provided only when the currency route requires it (such as CAD). Text
fpsIdentifier Faster Payment System identifier. Provided only when the currency route requires it (such as HKD). Text
clearingNumber Clearing number. Provided only when the currency route requires it (such as SEK). Text

Pay In Details Account Type

Account type Account type Currencies
checking Checking account USD

Pay In Details Bank Codes

Pay in type Currency Bank code Example
bank_transfer GBP Sort code 565777
  USD ABA routing number 021000021
  NOK Bank code 8301
  SGD Bank code 7171
  HKD Clearing code 016
  AUD BSB (bank state branch) 182-512

Pay In Details Address

Bank transfer pay in details may contain bank and Wise's addresses for some source currencies.

These currencies include: USD, NOK.

Field Description Format
name Bank name / Wise's company name Text
firstLine Street address Text
postCode Postcode / ZIP code Text
city City Text
stateCode State, province or region code Text (format depends on country)
country Country code 2 character ISO 3316 country code

Create Batch Group

Create a new batch group.

Example Request:

curl -X POST https://api.sandbox.transferwise.tech/v3/profiles/{profileId}/batch-groups \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{
           "sourceCurrency": "GBP",
           "name": "my-batch-group"
         }'

Example Response:

{
  "id": "54a6bc09-cef9-49a8-9041-f1f0c654cd88",
  "version": 0,
  "name": "my-batch-group",
  "sourceCurrency": "GBP",
  "status": "NEW",
  "transferIds": [],
  "payInDetails": []
}

Request

POST https://api.sandbox.transferwise.tech/v3/profiles/{profileId}/batch-groups

Field Description Format
sourceCurrency ISO 4217 currency code used as the source currency for all transfers in the batch group. Text
name Descriptive name for display purposes, recommended to use a name that uniquely represents this batch. Maximum length of 100 characters. Text

Response

A batch group resource.

Error responses

See errors page for a general description of API error responses. For all requests “401 Unauthorized” and 5xx series errors are possible.

HTTP status Reason
400 Bad Request - Missing sourceCurrency
- Invalid sourceCurrency

Get Batch Group

Get an existing batch group.

Example Request:

curl -X GET https://api.sandbox.transferwise.tech/v3/profiles/{profileId}/batch-groups/{batchGroupId} \
     -H "Authorization: Bearer <your api token>"

Example Response:

{
    "id": "54a6bc09-cef9-49a8-9041-f1f0c654cd88",
    "version": 1234,
    "name": "my-batch-group",
    "sourceCurrency": "GBP",
    "status": "NEW",
    "transferIds": [
        123,
        456
    ],
    "payInDetails": []
}

Request

GET https://api.sandbox.transferwise.tech/v3/profiles/{profileId}/batch-groups/{batchGroupId}

Field Description Format
profileId The profile that the batch group is associated with. Number
batchGroupId The batch group ID. Text

Response

A batch group resource.

Error responses

See errors page for a general description of API error responses. For all requests “401 Unauthorized” and 5xx series errors are possible.

HTTP status Reason
404 Not Found Requested group does not exist or is not visible to the requesting profile

Create Batch Group Transfer

Create a transfer in the batch group, using a previously created recipient account and quote. Please see quote creation and recipient account creation documentation.

Example Request:

curl -X POST https://api.sandbox.transferwise.tech/v3/profiles/{profileId}/batch-groups/{batchGroupId}/transfers \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{
           <transfer properties>
         }'

Request

POST https://api.sandbox.transferwise.tech/v3/profiles/{profileId}/batch-groups/{batchGroupId}/transfers

For the request body format please see this documentation.

Response

Please see the documentation.

Error responses

See errors page for a general description of API error responses. For all requests “401 Unauthorized” and 5xx series errors are possible.

HTTP status Reason
400 Bad Request Missing / invalid request arguments
422 Unprocessable Entity - Attempt to create transfer using a quote already used for another transfer
- Attempt to create transfer for a missing/inaccessible target account

Complete Batch Group

Completes the batch group and allows funding to proceed. Note: this action prevents any further modification.

Example Request:

curl -X PATCH https://api.sandbox.transferwise.tech/v3/profiles/{profileId}/batch-groups/{batchGroupId} \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{
           "status": "COMPLETED",
           "version": 1234
         }'

Example Response:

{
    "id": "54a6bc09-cef9-49a8-9041-f1f0c654cd88",
    "version": 1234,
    "name": "my-batch-group",
    "sourceCurrency": "GBP",
    "status": "COMPLETED",
    "transferIds": [
        123,
        456
    ],
    "payInDetails": [
        {
            "type": "bank_transfer",
            "reference": "XYZ123",
            "amount": 123.45,
            "currency": "GBP",
            "name": "Wise",
            "bankCode": "231470",
            "accountNumber": "77643994",
            "iban": null
        }
    ]
}

Request

PATCH https://api.sandbox.transferwise.tech/v3/profiles/{profileId}/batch-groups/{batchGroupId}

Field Description Format
profileId The profile that the batch group is associated with. Number
batchGroupId The batch group ID. Text
version The expected batch group version. This is a concurrency control mechanism. For the change to be accepted by the server, the expected version of the group must match the current version held by the server.

Versions are discovered by requesting batch group resources.
UUID

Response

A batch group resource.

Error responses

See errors page for a general description of API error responses. For all requests “401 Unauthorized” and 5xx series errors are possible.

HTTP status Reason
400 Bad Request Missing / invalid request arguments
409 Conflict Group version mismatch (the group has been modified since the requested version)
422 Unprocessable Entity Invalid state transition (e.g. from COMPLETED to NEW)

Cancel Batch Group

Cancel a batch group. Cancelling closes the group to further modification and initiates the cancellation of all transfers in the batch group. Only batches that are not funded can be cancelled. Cancellation is final it cannot be undone.

Example Request:

curl -X PATCH https://api.sandbox.transferwise.tech/v3/profiles/{profileId}/batch-groups/{batchGroupId} \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{
          "status": "CANCELLED",
          "version": 1234
        }'

Example Response:

{
    "id": "54a6bc09-cef9-49a8-9041-f1f0c654cd88",
    "version": 12345,
    "name": "my-batch-group",
    "sourceCurrency": "GBP",
    "status": "MARKED_FOR_CANCELLATION",
    "transferIds": [
        123,
        456
    ],
    "payInReferences": []
}

Request

PATCH https://api.sandbox.transferwise.tech/v3/profiles/{profileId}/batch-groups/{batchGroupId}

Field Description Format
profileId The profile that the batch group is associated with. Number
batchGroupId The batch group ID. Text
version The expected batch group version. This is a concurrency control mechanism. For the change to be accepted by the server, the expected version of the group must match the current version held by the server.

Versions are discovered by requesting batch group resources.
UUID

Response

A batch group resource.

Error responses

See errors page for a general description of API error responses. For all requests “401 Unauthorized” and 5xx series errors are possible.

HTTP status Reason
400 Bad Request Missing / invalid request arguments
409 Conflict Group version mismatch (the group has been modified since the requested version)
422 Unprocessable Entity Invalid state transition

Fund Batch Group

Funds all the transfers in a batch, they are paid out immediately. Applicable when funding from a multi-currency account. The Batch Group must first be completed, and there needs to be enough funds in the account for the whole batch otherwise an insufficient funds error will be returned.

This endpoint is SCA protected when it applies, you can find more info here.

Example Request:

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

Example Response:

{
    "id": "54a6bc09-cef9-49a8-9041-f1f0c654cd88",
    "name": "my-batch-group",
    "fileName": null,
    "alreadyPaid": true,
    "shortId": 12345,
    "userId": 123,
    "profileId": 56789,
    "sourceCurrency": "GBP",
    "status": "COMPLETED",
    "groupType": "API",
    "transferIds": [
      123,
      456
    ]
}

Request

POST https://api.sandbox.transferwise.tech/v3/profiles/{profileId}/batch-payments/{batchGroupId}/payments

Field Description Format
type The method of payment to use (must always be BALANCE) Text

Response

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

Field Description Format
id Unique batch group ID. Text
name Descriptive name. Text
fileName If this batch was submitted as a file, this is the given file name Text
alreadyPaid This field is not applicable to this use case Boolean
shortId This field is not applicable to this use case Number
userId The ID of the user who initiated this payment Number
profileId The ID of the profile this payment belongs to Number
sourceCurrency The source currency of the batch (note: we will prefer this currency but if there are insufficient funds then an automatic conversion from another currency can occur) Text
status Current Batch Group Status Text
groupType Whether this batch was submitted over the "API" or as a "FILE" Text
transferIds The IDs of all transfers in the group. Array

Error responses

See errors page for a general description of API error responses. For all requests “401 Unauthorized” and 5xx series errors are possible.

HTTP status Reason
400 Bad Request Missing / invalid request arguments, or unsupported payment type
422 Unprocessable Entity There is insufficient funds in the multi-currency account

Fund Batch Group via Direct Debit

Funds all the transfers in a batch via direct debit. The Batch Group must be in the completed state. To use this funding method, you need to link an external bank account first. More info on how to create a direct debit account here.

Example Request:

curl -X POST https://api.sandbox.transferwise.tech/v1/profiles/{{profileId}}/batch-groups/{{batchGroupId}}/payment-initiations \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{
           "type": "DIRECT_DEBIT",
           "accountId": 1
         }'

Example Response:

{
  "id": 12345,
  "batchGroupId": "068e186d-9632-4937-b753-af3e53f4d0b0",
  "reference": "B1234567",
  "userId": 123,
  "profileId": 2,
  "createdTime": "2022-01-01T19:51:41.423404Z",
  "status": "NEW",
  "type": "DIRECT_DEBIT",
  "accountId": 1
}

POST https://api.sandbox.transferwise.tech/v1/profiles/{{profileId}}/batch-groups/{{batchGroupId}}/payment-initiations

Field Description Format
type The method of payment to use (must always be DIRECT_DEBIT) Text
accountId Direct debit account ID created via this API Number
reference Optional. Payment initiation reference. The current limit is 10 characters. If not provided, the reference will be generated automatically and returned in the response Text

Response

You need to save payment initiation ID for tracking its status later.

Field Description Format
id Payment initiation ID Number
type Payment type Text
accountId External bank account ID Number
batchGroupId Batch group ID Text
userId The ID of the user who initiated this payment Number
profileId The ID of the profile this payment belongs to Number
createdTime Payment initiated timestamp Timestamp
status Status of payment initiation Text
reference Payment initiation reference. This reference will be passed to the network and can be used for reconciliation Text

Get Payment Initiations status of a Batch Group

Get payment initiation info by id. In addition to webhooks, this endpoint can be used for polling the status of payment initiation.

Example Request:

curl -X GET https://api.sandbox.transferwise.tech/v1/profiles/{{profileId}}/batch-groups/{{batchGroupId}}/payment-initiations/{{paymentInitiationId}} \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" 

Example Response:

{
  "id": 12345,
  "batchGroupId": "068e186d-9632-4937-b753-af3e53f4d0b0",
  "userId": 123,
  "profileId": 2,
  "createdTime": "2022-01-01T19:51:41.423404Z" ,
  "status": "PROCESSING",
  "type": "DIRECT_DEBIT",
  "accountId": 1,
  "transferId": 12345
}

GET https://api.sandbox.transferwise.tech/v1/profiles/{{profileId}}/batch-groups/{{batchGroupId}}/payment-initiations/{{paymentInitiationId}}

Field Description Format
profileId The profile that the batch group is associated with. Number
batchGroupId The batch group ID. Text
paymentInitiationId The payment initiation ID Number

Response

You need to save payment initiation ID for tracking its status later.

Field Description Format
id Payment initiation ID Number
type Payment type Text
accountId External bank account ID Number
batchGroupId Batch group ID Text
userId The ID of the user who initiated this payment Number
profileId The ID of the profile this payment belongs to Number
createdTime Payment initiated timestamp Timestamp
status Status of payment initiation Text
transferId ID of a direct debit pull transfer. Present only after a pull transfer is initiated Number

Comparison

Request comparison quotes

Example Request:

curl -X GET https://api.transferwise.com/v3/comparisons/?sourceCurrency=GBP&targetCurrency=EUR&sendAmount=10000

Example Response:

{
  "sourceCurrency": "GBP",
  "targetCurrency": "EUR",
  "sourceCountry": null,
  "targetCountry": null,
  "providerCountry": null,
  "providerType": null,
  "sendAmount": 10000.0,
  "providers": [
    {
      "id": 39,
      "alias": "transferwise",
      "name": "Wise",
      "logo": "https://dq8dwmysp7hk1.cloudfront.net/logos/transferwise.svg",
      "type": "moneyTransferProvider",
      "partner": false,
      "quotes": [
        {
          "rate": 1.15989,
          "fee": 37.12,
          "receivedAmount": 11555.84,
          "dateCollected": "2019-10-22T14:36:43Z",
          "sourceCountry": null,
          "targetCountry": null,
          "markup": 0.0,
          "deliveryEstimation": {
            "duration": {
              "min": "PT20H8M16.305111S",
              "max": "PT20H8M16.305111S"
            },
            "providerGivesEstimate": true
          }
        }
      ]
    },
    {
      "id": 1,
      "alias": "barclays",
      "name": "Barclays",
      "logo": "https://dq8dwmysp7hk1.cloudfront.net/logos/barclays.svg",
      "type": "bank",
      "partner": false,
      "quotes": [
        {
          "rate": 1.12792426,
          "fee": 0.0,
          "receivedAmount": 11279.24,
          "dateCollected": "2019-10-22T14:00:04Z",
          "sourceCountry": "GB",
          "targetCountry": "ES",
          "markup": 2.75592858,
          "deliveryEstimation": {
            "duration": {
              "min": "PT24H",
              "max": "PT24H"
            },
            "providerGivesEstimate": true
          }
        },
        ...
        {
          "rate": 1.12792426,
          "fee": 0.0,
          "receivedAmount": 11279.24,
          "dateCollected": "2019-10-22T14:00:04Z",
          "sourceCountry": "GB",
          "targetCountry": "FI",
          "markup": 2.75592858,
          "deliveryEstimation": {
            "duration": {
              "min": "PT24H",
              "max": "PT24H"
            },
            "providerGivesEstimate": true
          },
          ...
        }
        ...
      ]
    }
  ]
}

The comparison API can be used to request price and speed information about various money transfer providers. This includes not only Wise but other providers in the market.

Price Estimation

The quotes (price / speed) provided by this API are based off of real quotes collected from 3rd party websites. We collect both the advertised exchange rate and fee for each provider for various amounts. When a comparison is requested we calculate the markup % on the collected exchange rate on the mid-market rate at the time of collection, we then apply this markup % on the current mid-market rate to provide a realistic estimate of what each provider offers. We collect data for all providers ~ once per hour to ensure we provide as accurate and up to date information as possible.

Note: Today, we only provide estimations for FX transactions with a Bank Transfer pay-in / pay-out option. This is important to stress as many providers offer significantly different fees / exchange rates when used debit / credit card, cash etc.

For more details on the data collection process please see the following page:

https://wise.com/gb/compare/disclaimer

If you have questions or suspect any data to be inaccurate or incomplete please contact us at:

comparison@wise.com

Delivery Estimation

Similar to price, we collect speed data for most (if not all) providers which we have price information for. Many providers display speed estimates to their customers in a number of different ways.

Some examples:

  • "The transfer should be complete within 2-5 days"
  • "The money should arrive in your account within 48 hours"
  • "Should arrive by 26th Aug"
  • "Could take up to 4 working days"

The below API intends to model these in a consistent format by providing a min / max range for all delivery estimations. An estimate that states "up to X" will have "max" set to a duration but "min" as null, a "from X" will have "min" set to a duration and "max" as null. Finally for those providers who offer a specific, point in time estimation (like Wise), the API will surface a duration where min/max are equal.

Quotes structure

In order to provide the most flexible and accurate data for clients, we surface a denormalised list of quotes per provider where each quote represents a unique collection of comparison "dimensions".

A single given provider may expose multiple quotes for the same currency route. The most common example is where a provider offers different pricing for one country vs another country which uses the same currency. e.g:

Provider X:

  • GBP EUR 1000 [GB -> ES] fee: 10, rate: 1.5
  • GBP EUR 1000 [GB -> DE] fee: 8, rate: 1.5
  • GBP EUR 1000 [GB -> FR] fee: 10, rate: 1.35

The same principle applies for speed. I.e a provider may have different speed estimates for different target countries and hence we expose these as discrete quotes - where a quote is a unique combination of route / country / speed / price factors.

A client may choose to reduce this set of quotes down to a single or several quotes in order to display a relevant quote to a given user. An example where we take the cheapest quote for a given currency route (and also surface the target country) can be seen at the below link:

https://wise.com/gb/compare/?sourceCurrency=GBP&targetCurrency=EUR&sendAmount=1000

Request

GET https://api.transferwise.com/v3/comparisons/?sourceCurrency=GBP&targetCurrency=EUR&sendAmount=10000

Field (Query Param) Description Format
sourceCurrency ISO 4217 source currency code Text
targetCurrency ISO 4217 target currency code Text
sendAmount Amount in source currency Decimal
sourceCountry (Optional) Filter by source country (ISO 3166-1 Alpha-2 code) Text
targetCountry (Optional) Filter by target country (ISO 3166-1 Alpha-2 code) Text
providerType (Optional) Filter by provider type One of "bank","moneyTransferProvider"

Response

Field Description Format
id Provider id Integer
alias Provider alias (lowercase slug name) Text
name Provider name (presentational / formal name) Text
logo URL pointing to provider logo (default svg format) Text
type Provider type Text
partner Whether a partner of Wise or not Boolean
quotes An array of estimated quotes per provider Array
quotes.rate The live estimated exchange for the provider for this quote Timestamp
quotes.fee The estimated fee for the provider for this quote Integer
quotes.receivedAmount The total estimated receive amount for the provider for this quote Integer
quotes.dateCollected The date of collection for the original quote Text
quotes.sourceCountry Source country (ISO 3166-1 Alpha-2 code) Timestamp
quotes.targetCountry Target country (ISO 3166-1 Alpha-2 code) Decimal
quotes.deliveryEstimation Delivery estimation details - i.e a speed estimate Object
quotes.deliveryEstimation.duration Duration range Object
quotes.deliveryEstimation.duration.min Minimum quoted time for transaction delivery ISO 8601 duration format
quotes.deliveryEstimation.duration.max Maximum quoted time for transaction delivery ISO 8601 duration format
quotes.deliveryEstimation.providerGivesEstimate Whether a provider publicly surfaces / exposes a speed estimate Boolean

Currency Pairs

Get Currency Pairs

Example Request:

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

Example Response:

{
    "sourceCurrencies": [
        {
            "currencyCode": "GBP",
            "maxInvoiceAmount": 1000000,
            "targetCurrencies": [
                {
                    "currencyCode": "EUR",
                    "minInvoiceAmount": 1,
                    "fixedTargetPaymentAllowed": true
                },
                {
                    "currencyCode": "INR",
                    "minInvoiceAmount": 1,
                    "fixedTargetPaymentAllowed": true
                },
                {
                    "currencyCode": "USD",
                    "minInvoiceAmount": 1,
                    "fixedTargetPaymentAllowed": true
                },
...
                {
                    "currencyCode": "VND",
                    "minInvoiceAmount": 1,
                    "fixedTargetPaymentAllowed": true
                },
                {
                    "currencyCode": "ZAR",
                    "minInvoiceAmount": 1,
                    "fixedTargetPaymentAllowed": true
                }
            ],
            "totalTargetCurrencies": 47
        }
    ],
    "total": 19
}

Get list of allowed currency pairs that you can setup in your transfers.

Request

GET https://api.sandbox.transferwise.tech/v1/currency-pairs

Response

Field Description Format
sourceCurrencies.currencyCode Source currency code Text
sourceCurrencies.maxInvoiceAmount Maximum allowed transfer amount in source currency Decimal
targetCurrencies.currencyCode Target currency code Text
targetCurrencies.minInvoiceAmount Minimum allowed transfer amount in source currency for this pair. Decimal
targetCurrencies.fixedTargetPaymentAllowed Can you setup fixed rate payments or not. Boolean

Multi-Currency Account

The Wise multi-currency account (MCA) enables users to hold, convert, and fund transfers (single or batches) with balances in up to 56 currencies. Please note that of the 50+ currency balances that we support, 10+ of these come with local account details.

Please refer to our multi-currency account guide for more information on the general use of the endpoints included below.

Please see the Balances APIs for more details.

Get Available Currencies

Example Request:

curl -X GET https://api.sandbox.transferwise.tech/v2/borderless-accounts-configuration/profiles/{{personal-profile-id}}/available-currencies \
     -H "Authorization: Bearer {{access-token}}" 

Example Response:

[
  "EUR",
  "GBP",
  "USD",
  ...
]

Purpose

This endpoint returns all the currencies available for balance accounts. You can use this list to create a balance account for the currency included.

Get Payin Currencies

Example Request:

curl -X GET https://api.sandbox.transferwise.tech/v2/borderless-accounts-configuration/profiles/{{personal-profile-id}}/payin-currencies \
     -H "Authorization: Bearer {{access-token}}" 

Example Response:

[
  "EUR",
  "GBP",
  "USD",
  ...
]

Purpose

This endpoint returns all the currencies available for balance accounts that are also available to have bank account details. You can use this list to create a balance account for the currency included and then subsequently create bank account details.

Get Multi-Currency Accounts

Example Request:

curl -X GET https://api.sandbox.transferwise.tech/v4/profiles/{{profileId}}/multi-currency-account \
     -H "Authorization: Bearer {{access-token}}"

Example Response - 200: Account Exists

{
    "id": < multi-currency account Id >,
    "profileId": < profile Id >,
    "recipientId": 12345678,
    "creationTime": "2020-05-20T14:43:16.658Z",
    "modificationTime": "2020-05-20T14:43:16.658Z",
    "active": true,
    "eligible": true
}

Example Response - 404: Not Found

No Content

Purpose

This endpoint returns the multi-currency account details for the specified profileId. If the user does not yet have a multi-currency account, a 404 Not Found will be returned.

Get Eligibility

Example Request - Profile Eligibility:

curl -X GET https://api.sandbox.transferwise.tech/v4/multi-currency-account/eligibility?profileId={{profile-id}} \
     -H "Authorization: Bearer {{access-token}}"

Example Request - Country/State Eligibility:

curl -X GET https://api.sandbox.transferwise.tech/v4/multi-currency-account/eligibility?country={{country-ISO-Code}}&state={{state-ISO-code}} \
     -H "Authorization: Bearer {{access-token}}"

Example Response:

{
  "eligible": true,
  "eligibilityCode": "eligible",
  "accountType": "FULL",
  "ineligibilityReason": null
}

Purpose

This endpoint checks eligibility for a multi-currency account for either a specific profile or for a location. Customers in some countries and states/provinces may not be eligible for a multi currency account.

To check a profile, the profileId should be passed as a parameter.

To check a specific location, the country the user is in should be passed as country using 2-letter ISO 3166 codes. If the country is US, a valid 2 letter state parameter must also be passed.

Ex 1: France: https://api.sandbox.transferwise.tech/v4/multi-currency-account/eligibility?country=FR Ex 2: USA, California: https://api.sandbox.transferwise.tech/v4/multi-currency-account/eligibility?country=US&state=CA

Response

Field Description Format
eligible Profile is eligible for MCA Account Boolean
eligibilityCode Reason for the ineligibility eligible, invalid.profile.type, invalid.country, or invalid.state
accountType Account type available INELIGIBLE, RECEIVE_ONLY or FULL. Generally this will be returned as FULL.
ineligibilityReason Reason the profile is not eligible String

Partner Licence Transfers

Create

Example Request (Originator Type = PRIVATE):

curl --location -g --request POST 'https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/partner-licence-transfers' \
--header 'Authorization: Bearer <user-token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "targetAccount": 99999,
    "sourceAccount": 123456,
    "quoteUuid": "daa83d36-5fad-47bf-8923-6f2e0463cd6c",
    "customerTransactionId": "b77dcbe3-53fc-423d-9c18-1aea91d0a0b9",
    "details": {
        "reference": "Holiday"
    },
    "originator": {
        "legalEntityType": "PRIVATE",
        "externalId": "123abc",
        "name": {
            "givenName": "John",
            "middleNames": [
                "Jay"
            ],
            "familyName": "Doe"
        },
        "dateOfBirth": "1977-07-01",
        "address": {
            "firstLine": "56 Shoreditch",
            "city": "Tallinn",
            "countryCode": "US",
            "postCode": "12112",
            "stateCode": "NV"
        }
    }
}'

Example Request (Originator Type = BUSINESS):

curl --location -g --request POST 'https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/partner-licence-transfers' \
--header 'Authorization: Bearer <user-token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "targetAccount": 99999,
    "sourceAccount": 123456,
    "quoteUuid": "200d42dd-defe-4b64-b8f7-872ae72c1f0b",
    "customerTransactionId": "0f330553-aba1-425e-8310-6415118d1bd9",
    "details": {
        "reference": "invoice 123"
    },
    "originator": {
        "legalEntityType": "BUSINESS",
        "externalId": "54321",
        "name": {
            "fullName": "Some Biz PLC"
        },
        "businessRegistrationCode": "00000001234",
        "address": {
            "firstLine": "56 Shoreditch",
            "city": "Tallinn",
            "countryCode": "US",
            "postCode": "12112",
            "stateCode": "NV"
        }
    }
}'

Example Response (Originator Type = PRIVATE):

{
  "id": 123456789,
  "customerTransactionId": "b77dcbe3-53fc-423d-9c18-1aea91d0a0b9",
  "user": 55555,
  "targetAccount": 99999,
  "sourceAccount": 123456,
  "quoteUuid": "daa83d36-5fad-47bf-8923-6f2e0463cd6c",
  "status": "incoming_payment_waiting",
  "rate": 0.8762,
  "details": {
    "reference": "Holiday"
  },
  "hasActiveIssues": false,
  "sourceCurrency": "EUR",
  "sourceValue": 497.46,
  "targetCurrency": "GBP",
  "targetValue": 427.16,
  "created": "2021-02-18T12:59:42.000",
  "originator": {
    "legalEntityType": "PRIVATE",
    "externalId": "123abc",
    "name": {
      "givenName": "John",
      "middleNames": [
        "Jay"
      ],
      "familyName": "Doe"
    },
    "dateOfBirth": "1977-07-01",
    "address": {
      "firstLine": "56 Shoreditch ",
      "city": "Tallinn",
      "countryCode": "EE",
      "postCode": "12112"
    }
  }
}

Example Response (Originator Type = BUSINESS):

{
  "id": 123456790,
  "customerTransactionId": "0f330553-aba1-425e-8310-6415118d1bd9",
  "user": 55555,
  "sourceAccount": 123456,
  "targetAccount": 99999,
  "quoteUuid": "200d42dd-defe-4b64-b8f7-872ae72c1f0b",
  "status": "incoming_payment_waiting",
  "rate": 0.8762,
  "details": {
    "reference": "invoice 123"
  },
  "hasActiveIssues": false,
  "sourceCurrency": "JPY",
  "sourceValue": 497.46,
  "targetCurrency": "GBP",
  "targetValue": 427.16,
  "originator": {
    "legalEntityType": "BUSINESS",
    "externalId": "54321",
    "name": {
      "fullName": "Some Biz PLC"
    },
    "businessRegistrationCode": "00000001234",
    "address": {
      "firstLine": "1 Aaa Road",
      "city": "London",
      "countryCode": "GB",
      "postCode": "N1 1AA"
    }
  },
  "created": "2019-02-18T12:59:42.000"
}

Request

POST https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/partner-licence-transfers

This is very similar to Create transfers endpoint, but please note these differences:

  • originator data block is additionally required
Field Description Format
targetAccount Recipient account id. You can create multiple transfers to same recipient account. Integer
sourceAccount (optional) Refund recipient account id. Integer
quoteUuid V2 quote id. You can only create one transfer per one quote.
You cannot use same quote ID to create multiple transfers.
UUID
customerTransactionId Unique transfer id. We use this field to perform idempotency check to avoid duplicate transfers in case of network failures or timeouts. You can only submit one transfer with same customerTransactionId. UUID
details.reference (optional) Recipient will see this reference text in their bank statement. Maximum allowed characters depends on the currency route. Tips for paying invoices 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
originator Data block to capture payment originator details. Group
originator.legalEntityType PRIVATE or BUSINESS. Payment originator legal type. Text
originator.externalId Unique customer id in your system. This allows us to uniquely identify each originator. Required. Text
originator.name.givenName Payment originator first name. Required if legalEntityType = PRIVATE. Text
originator.name.middleNames Payment originator middle name(s). Used only if legalEntityType = PRIVATE. Optional Text Array
originator.name.familyName Payment originator family name. Required if legalEntityType = PRIVATE. Text
originator.name.patronymicName Payment originator patronymic name. Used only if legalEntityType = PRIVATE. Optional Text
originator.name.fullName Payment originator full legal name. Required if legalEntityType = BUSINESS. Text
originator.dateOfBirth Payment originator date of birth. Required if legalEntityType = PRIVATE. YYYY-MM-DD
originator.businessRegistrationCode Payment originator business registry number / incorporation number. Required if legalEntityType = BUSINESS. Text
originator.address.firstLine Payment originator address first line. Required Text
originator.address.city Payment originator address city. Required Text
originator.address.stateCode Payment originator address state code. Required if address country code in (US, CA, BR, AU). Text
originator.address.countryCode Payment originator address first line. Required Text
originator.address.postCode Originator address zip code. Optional Text

Response

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

Field Description Format
id Transfer id Integer
customerTransactionId Transfer unique id provided by a caller UUID
user Your user id Integer
targetAccount Recipient account id Integer
sourceAccount Refund recipient account id. Integer
quote Not used Integer
quoteUuid v2 quote id Text
status Transfer current status Text
rate Exchange rate value Decimal
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
originator Data block to capture payment originator details Group
originator.legalEntityType Payment originator legal type. Text
originator.externalId Unique customer id in your system. Text
originator.name.givenName Payment originator first name. Text
originator.name.middleNames Payment originator middle name(s). Text Array
originator.name.familyName Payment originator family name. Text
originator.name.patronymicName Payment originator patronymic name. Text
originator.name.fullName Payment originator full legal name. Text
originator.dateOfBirth Payment originator date of birth. YYYY-MM-DD
originator.businessRegistrationCode Payment originator business registry number / incorporation number. Text
originator.address.firstLine Payment originator address first line. Text
originator.address.city Payment originator address city. Text
originator.address.stateCode Payment originator address state code. Text
originator.address.countryCode Payment originator address first line. Text
originator.address.postCode Originator address zip code. Text
created Timestamp when transfer was created Timestamp

Avoiding duplicate transfers

We use customerTransactionId field to avoid duplicate transfer requests. When your first call fails (error or timeout) then you should use the same value in customerTransactionId field that you used in the original call when you are submitting a retry message. This way we can treat subsequent retry messages as repeat messages and will not create duplicate transfers to your account. We recommend using UUID V4 to avoid collisions.

Managing transfers

Please refer to our Transfers section.

Fund

Please refer to our Transfer Fund section.

Payin deposit details

Get bank transfer deposit details for transfer

Example Request:

curl --location --request GET 'https://api.transferwise.com/v1/profiles/123456/transfers/987654/deposit-details/bank-transfer' \
--header 'Authorization: Bearer <your api token>' \
--header 'x-mock-response-name: get-deposit-details-success' \
--header 'Content-Type: application/json' \
--header 'Accept-Language: en-GB'

Example Response:

{
	"payinBank": {
		"bankName": "TransferWise Europe SA",
		"bankAddress": {
			"country": "BE",
			"firstLine": "Avenue Louise 54, Room s52",
			"postCode": "1050",
			"city": "Brussels",
			"state": null
		}
	},
	"payinBankAccount": {
		"currency": "EUR",
		"details": [
			{
				"type": "iban",
				"label": "IBAN",
				"value": "BE11111111111111"
			},
			{
				"type": "bic",
				"label": "Bank code (BIC/SWIFT)",
				"value": "TRWIBEB1XXX"
			},
			{
				"type": "recipientName",
				"label": "Recipient name",
				"value": "TransferWise Europe SA"
			}
		]
	},
	"wiseInformation": {
		"localCompanyName": "TransferWise Europe SA",
		"localAddress": {
			"country": "United Kingdom",
			"firstLine": "6th Floor, The Tea Building, 56 Shoreditch High Street",
			"postCode": "E1 6JJ",
			"city": "London",
			"state": null
		}
	}
}

The payin deposit details API allows you to get the bank details for the account that the customer should send funds to when paying for a Wise transfer via a bank transfer. These details will be provided in the local format for that currency and usually contain bank account information - like iban, swift code etc. It also includes the name and address of the receiving bank (payinBank) and the name and address of the Wise entity that owns the bank account (wiseInformation) as sometimes these are required to make a payment.

The payinBankAccount field allows the bank details to be displayed dynamically in a user interface, by displaying the label and value fields.

Currently this API supprts the following currencies:

Currency
AUD
BGN
BRL
CAD
CHF
CZK
DKK
EUR
GBP
HKD
HRK
HUF
IDR
INR
JPY
MYR
NOK
NZD
PLN
RON
SEK
SGD
TRY
USD

Request

GET https://api.transferwise.com/v1/profiles/{profileId}/transfers/{transferId}/deposit-details/bank-transfer

Field Description Format
profileId Profile id. Text
transferId Transfer id. Text

Response

Field Description Format
payinBank Information about the receiving bank. Object
payinBank.bankName Bank name. Text
payinBank.bankAddress Bank address. Object (can be null)
payinBank.bankAddress.country Country ISO 2 code Text
payinBank.bankAddress.firstLine Street address Text
payinBank.bankAddress.postCode Post code / zip code Text
payinBank.bankAddress.city City Text
payinBank.bankAddress.state State. Can be null. Text (can be null)
payinBankAccount Bank account details to use to send the payment to. Object
payinBankAccount.currency ISO 4217 source currency code Text
payinBankAccount.details Account details Array of Objects
payinBankAccount.details[n].type Account details type e.g. accountNumber, iban etc. Text
payinBankAccount.details[n].label Account details label that should be displayed in your user interface. Text
payinBankAccount.details[n].value Account details value - the value of account details (like iban, account number etc). Text
wiseInformation Information about the receiving Wise entity, the owner of the bank account. Object
wiseInformation.localCompanyName Wise local company name. Text
wiseInformation.localAddress Wise local address. Object (can be null)
wiseInformation.localAddress.country Country ISO 2 code Text
wiseInformation.localAddress.firstLine Street address Text
wiseInformation.localAddress.postCode Post code / zip code Text
wiseInformation.localAddress.city City Text
wiseInformation.localAddress.state State. Can be null. Text (can be null)

User Profiles

Create (Personal)

Example Request:

curl -X POST https://api.sandbox.transferwise.tech/v1/profiles \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "type": "personal",
          "details": {
            "firstName": "Oliver",
            "lastName": "Wilson",
            "dateOfBirth": "1977-07-01",
            "phoneNumber": "+3725064992",
            "firstNameInKana": null,
            "lastNameInKana": null
           }
        }'

Example Response (Personal):

{
  "id": <your personal profile id>,
  "type": "personal",
  "details": {
    "firstName": "Oliver",
    "lastName": "Wilson",
    "dateOfBirth": "1977-07-01",
    "phoneNumber": "+3725064992",
    "avatar": "",
    "occupation": "",
    "occupations": null,
    "primaryAddress": null,
    "firstNameInKana": null,
    "lastNameInKana": null
  }
}

Create personal user profile. One person cannot have multiple active duplicate user profiles, creating multiple profiles with the same details will fail.

Request

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

Field Description Format Validation rules (java regex)
type "personal" Text Must be "personal".
details.firstName First name (including middle names) Text (max 30 chars) Must not contain: %#^@{}"!~<>\. ((^[^%#^@{}"!~<>\\]+$))
details.lastName Last name Text (max 30 chars) Must not contain: %#^@{}"!~<>\. ((^[^%#^@{}"!~<>\\]+$))
details.dateOfBirth Date of birth YYYY-MM-DD Must be YYYY-MM-DD format.
details.phoneNumber Phone number Text Must be a valid phone number, validated through Google's phone number library.
details.firstNameInKana First name in Katakana (required for from JPY personal transfers) Text (Katakana) Must be in katakana with double width space or standard spaces only. ([\p{InKatakana} \u3000]+)
details.lastNameInKana Last name in Katakana (required for from JPY personal transfers) Text (Katakana) Must be in katakana with double width space or standard spaces only. ([\p{InKatakana} \u3000]+)

If a customer you are creating a profile for has first or last names that exceed 30 characters (e.g. they have many middle names) then you should truncate the names at length 30 characters and submit that value.

Response

Field Description Format
id profileId Integer
type "personal" Text
details.firstName First name Text
details.lastName Last name Text
details.dateOfBirth Date of birth YYYY-MM-DD
details.phoneNumber Phone number Text
details.avatar Link to person avatar image Text
details.occupation (Deprecated) Person occupation Text
details.occupations Array of occupations, currently one FREE_FORM occupation is supported, required as described above. Array (can be null or empty)
details.occupations[n].code User occupation, any value permitted. Text
details.occupations[n].format Occupation type - always FREE_FORM Text
details.primaryAddress Address object id Integer
details.firstNameInKana First name in Katakana (required for from JPY personal transfers) Text (Katakana)
details.lastNameInKana Last name in Katakana (required for from JPY personal transfers) Text (Katakana)

Create (Business)

Example Request:

curl -X POST https://api.sandbox.transferwise.tech/v1/profiles \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "type": "business",
          "details": {
            "name": "ABC Logistics Ltd",
            "registrationNumber": "12144939",
            "acn": null,
            "abn": null,
            "arbn": null,
            "companyType": "LIMITED",
            "companyRole": "OWNER",
            "webpage": "https://abc-logistics.com",
            "businessCategory":"CONSULTING_IT_BUSINESS_SERVICES",
            "businessSubCategory":"DESIGN"
          }
        }'

Example Response (Business):

{
  "id": <your business profile id>,
  "type": "business",
  "details": {
    "name": "ABC Logistics Ltd",
    "registrationNumber": "12144939",
    "acn": null,
    "abn": null,
    "arbn": null,
    "companyType": "LIMITED",
    "companyRole": "OWNER",
    "descriptionOfBusiness": "Information and communication",
    "webpage": "https://abc-logistics.com",
    "primaryAddress": 123456, //ID of placeholder
    "businessCategory": "CONSULTING_IT_BUSINESS_SERVICES",
    "businessSubCategory": "DESIGN"
   }
}

Create business user profile. You must always create a personal profile first, business profiles cannot be created without personal profile.

Request (Business)

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

Field Description Format Validation Rules (java regex)
type "business" Text Always "business"
details.name Business name Text Must not contain: %#^@{}"!~<>\. ((^[^%#^@{}"!~<>\\]+$))
details.registrationNumber Business registration number Text 1 to 30 characters.
details.acn Australian Company Number (only for Australian businesses) Text Must be valid ACN.
details.abn Australian Business Number (only for Australian businesses) Text Must be valid ABN.
details.arbn Australian Registered Body Number (only for Australian businesses) Text Must be valid ARBN.
details.companyType Company legal form. Allowed values:
  • LIMITED
  • PARTNERSHIP
  • SOLE_TRADER
  • LIMITED_BY_GUARANTEE
  • LIMITED_LIABILITY_COMPANY
  • FOR_PROFIT_CORPORATION
  • NON_PROFIT_CORPORATION
  • LIMITED_PARTNERSHIP
  • LIMITED_LIABILITY_PARTNERSHIP
  • GENERAL_PARTNERSHIP
  • SOLE_PROPRIETORSHIP
  • PRIVATE_LIMITED_COMPANY
  • PUBLIC_LIMITED_COMPANY
  • TRUST
  • OTHER
Text Must be one of the enum values.
details.companyRole Role of person. Allowed Values:
  • OWNER
  • DIRECTOR
  • OTHER
Text Must be one of the enum values.
details.descriptionOfBusiness Sector / filed of activity (DEPRECATED) Text Deprecated, use businessCategory and set this as null.
details.webpage (conditional) Business webpage. Required if companyType is OTHER Text Valid URL. (^(?i)\\b(https?://)?((?=[a-z0-9-]{1,63}\\.)[a-z0-9]+(-[a-z0-9]+)*\\.)+[a-z]{2,63}\\b(/.*)*$)
details.businessCategory Type of business, see below for permitted values Text One of the below Business Category values.
details.businessSubCategory Specific sub category of the business type, see below for permitted values Text A valid subcategory of the selected businessCategory.

Business Category

Ensure when submitting a business profile that you submit a category and associated sub-category from the list below. You should map from the information you have about the business to one of our categories and sub-categories. If this is problematic please get in touch with us to discuss alternate solutions.

The categories and their sub-categories are as follows:

  • CHARITY_NON_PROFIT
    • CHARITY_ALL_ACTIVITIES
  • CONSULTING_IT_BUSINESS_SERVICES
    • ADVERTISING_AND_MARKETING
    • ARCHITECTURE
    • COMPANY_ESTABLISHMENT_FORMATION_SERVICES
    • DESIGN
    • FINANCIAL_CONSULTING_ACCOUNTING_TAXATION_AUDITING
    • IT_DEVELOPMENT
    • IT_HOSTING_SERVICES
    • IT_CONSULTING_AND_SERVICES
    • LEGAL_SERVICES
    • MANAGEMENT_CONSULTING
    • SCIENTIFIC_AND_TECHNICAL_CONSULTING
    • SOFTWARE_AS_A_SERVICE
    • TRANSLATION_AND_LANGUAGE_SERVICES
    • CONSULTING_OTHER
    • SERVICES_OTHER
    • FREELANCE_PLATFORMS
    • RECRUITMENT_SERVICES
    • MAINTENANCE_SERVICES
    • FREELANCE_PLATFORMS
  • DESIGN_MARKETING_COMMUNICATIONS
    • ADVERTISING_AND_MARKETING
    • ARCHITECTURE
    • AUDIO_AND_VIDEO
    • DESIGN
    • PHOTOGRAPHY
    • PRINT_AND_ONLINE_MEDIA
    • TELECOMMUNICATIONS_SERVICES
    • TRANSLATION_AND_LANGUAGE_SERVICES
  • MEDIA_COMMUNICATION_ENTERTAINMENT
    • ADULT_CONTENT
    • AUDIO_AND_VIDEO
    • FINE_ARTS
    • ARTS_OTHER
    • EVENTS_AND_ENTERTAINMENT
    • GAMBLING_BETTING_AND_ONLINE_GAMING
    • NEWSPAPERS_MAGAZINES_AND_BOOKS
    • PERFORMING_ARTS
    • PHOTOGRAPHY
    • TELECOMMUNICATIONS_SERVICES
    • VIDEO_GAMING
  • EDUCATION_LEARNING
    • SCHOOLS_AND_UNIVERSITIES,
    • TEACHING_AND_TUTORING
    • ONLINE_LEARNING
  • FINANCIAL_SERVICES_PRODUCTS_HOLDING_COMPANIES
    • CROWDFUNDING
    • CRYPTOCURRENCY_FINANCIAL_SERVICES
    • FINANCIAL_CONSULTING_ACCOUNTING_TAXATION_AUDITING
    • HOLDING_COMPANIES
    • INSURANCE
    • INVESTMENTS
    • MONEY_SERVICE_BUSINESSES
    • FINANCIAL_SERVICES_OTHER
  • FOOD_BEVERAGES_TOBACCO
    • ALCOHOL
    • FOOD_MANUFACTURING_RETAIL
    • RESTAURANTS_AND_CATERING
    • SOFT_DRINKS
    • TOBACCO
    • VITAMINS_AND_DIETARY_SUPPLEMENTS
  • HEALTH_PHARMACEUTICALS_PERSONAL_CARE
    • HEALTH_AND_BEAUTY_PRODUCTS_AND_SERVICES,
    • DENTAL_SERVICES,
    • DOCTORS_AND_MEDICAL_SERVICES,
    • ELDERLY_OR_OTHER_CARE_HOME,
    • FITNESS_SPORTS_SERVICES,
    • MEDICAL_EQUIPMENT,
    • NURSING_AND_OTHER_CARE_SERVICES,
    • PHARMACEUTICALS,
    • PHARMACY,
    • VITAMINS_AND_DIETARY_SUPPLEMENTS
  • PUBLIC_GOVERNMENT_SERVICES
    • PUBLIC_ALL_SERVICES
    • MAINTENANCE_SERVICES
    • GOVERNMENT_SERVICES
    • TELECOMMUNICATIONS_SERVICES
    • UTILITY_SERVICES
  • REAL_ESTATE_CONSTRUCTION
    • ARCHITECTURE
    • CONSTRUCTION
    • REAL_ESTATE_DEVELOPMENT
    • REAL_ESTATE_SALE_PURCHASE_AND_MANAGEMENT
  • RETAIL_WHOLESALE_MANUFACTURING
    • AGRICULTURE_SEEDS_PLANTS
    • FINE_ARTS
    • ARTS_OTHER
    • AUTOMOTIVE_SALES_SPARE_PARTS_TRADE
    • AUTOMOTIVE_MANUFACTURING
    • CHEMICALS
    • CLOTHING
    • ELECTRICAL_PRODUCTS
    • FIREARMS_WEAPONS_AND_MILITARY_GOODS_SERVICES
    • HOME_ACCESSORIES_FURNITURE
    • FINE_JEWELLERY_WATCHES
    • FASHION_JEWELLERY
    • HEALTH_AND_BEAUTY_PRODUCTS_AND_SERVICES
    • LEGAL_HIGHS_AND_RELATED_ACCESSORIES
    • MACHINERY
    • PETS
    • PRECIOUS_STONES_DIAMONDS_AND_METALS
    • SPORTING_EQUIPMENT
    • MANUFACTURING_OTHER
    • RETAIL_WHOLESALE_MARKETPLACE_AUCTION
    • RETAIL_WHOLESALE_OTHER
    • TOYS_AND_GAMES
  • TRAVEL_TRANSPORT_TOUR_AGENCIES
    • ACCOMMODATION_HOTELS
    • PASSENGER_TRANSPORT
    • FREIGHT_TRANSPORT
    • RIDESHARING_TRANSPORT_SHARING_SERVICES
    • TRANSPORT
    • TRAVEL_AGENCIES
    • TOUR_OPERATORS
    • TRAVEL_OR_TOUR_ACTIVITIES_OTHER
  • OTHER
    • OTHER_NOT_LISTED_ABOVE

Response (Business)

Field Description Format
id profileId Integer
type "business" Text
details.name Business name Text
details.registrationNumber Business registration number Text
details.acn Australian Company Number (only for AUS businesses) Text
details.abn Australian Business Number (only for AUS businesses) Text
details.arbn Australian Registered Body Number (only for AUS businesses) Text
details.companyType Company legal form Text
details.companyRole Role of person Text
details.webpage Business webpage Text
details.primaryAddress Address object id Integer
details.businessCategory Type of business Text
details.businessSubCategory Specific sub category of the business type Text

Update

Example Request:

curl -X PUT https://api.sandbox.transferwise.tech/v1/profiles \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{
          "id": <your personal profile id>
          "type": "personal",
          "details": {
            "firstName": "Oliver",
            "lastName": "Wilson",
            "dateOfBirth": "1977-07-01",
            "phoneNumber": "+3725064992",
            "firstNameInKana": null,
            "lastNameInKana": null
           }
        }'

Example Response:

{
  "id": <your personal profile id>,
  "type": "personal",
  "details": {
    "firstName": "Oliver",
    "lastName": "Wilson",
    "dateOfBirth": "1977-07-01",
    "phoneNumber": "+3725064992",
    "avatar": "",
    "occupation": "",
    "occupations": null,
    "primaryAddress": null,
    "firstNameInKana": null,
    "lastNameInKana": null
  }
}

Update user profile information.

If user profile has been verified then there are restrictions on what information is allowed to change, where permitted, use the update window functionality to submit updated data.

Request

PUT https://api.sandbox.transferwise.tech/v1/profiles

Request and response is same as described in Create (Personal) and Create (Business)

Get By Id

Example Request:

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

Example Response:

{
  "id": <your personal profile id>,
  "type": "personal",
  "details": {
    "firstName": "Oliver",
    "lastName": "Wilson",
    "dateOfBirth": "1977-07-01",
    "phoneNumber": "+3725064992",
    "avatar": "",
    "occupation": "",
    "primaryAddress": null,
    "firstNameInKana": null,
    "lastNameInKana": null
  }
}

Get profile info by id.

Request

GET https://api.sandbox.transferwise.tech/v1/profiles/{profileId}

List

GET /v2/profiles

Example Request:

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

Example Response:

[
  {
    "type": "PERSONAL",
    "id": 16155137,
    "userId": 5682283,
    "address": {
      "addressFirstLine": ".......",
      "city": "London",
      "countryIso2Code": "GB",
      "countryIso3Code": "gbr",
      "postCode": "ABC123",
      "stateCode": null
    },
    "email": "",
    "createdAt": "2021-03-25T15:18:35.000Z",
    "updatedAt": "2021-03-25T15:18:35.000Z",
    "obfuscated": false,
    "currentState": "VISIBLE",
    "firstName": "Oliver",
    "lastName": "Wilson",
    "dateOfBirth": "1967-04-03",
    "phoneNumber": "+442038087139",
    "secondaryAddresses": [],
    "fullName": "Oliver Wilson"
  },
  {
    "type": "BUSINESS",
    "id": 16155138,
    "userId": 5682283,
    "address": {
      "addressFirstLine": ".......",
      "city": "London",
      "countryIso2Code": "GB",
      "countryIso3Code": "gbr",
      "postCode": "ABC123",
      "stateCode": null
    },
    "email": "",
    "createdAt": "2021-03-25T15:18:38.000Z",
    "updatedAt": "2021-03-25T15:18:38.000Z",
    "obfuscated": false,
    "currentState": "VISIBLE",
    "businessName": "ABC Logistics Ltd",
    "registrationNumber": "07209813",
    "descriptionOfBusiness": "IT_SERVICES",
    "companyType": "LIMITED",
    "companyRole": "OWNER",
    "operationalAddresses": [],
    "fullName": "ABC Logistics Ltd"
  }
]

List of all profiles belonging to user.

Please note that there might be more than one business profile returned in the response.

Request

GET https://api.sandbox.transferwise.tech/v2/profiles

GET /v1/profiles (deprecated)

Example Request:

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

Example Response:

[
    {
      "id": <your personal profile id>,
      "type": "personal",
      "details": {
        "firstName": "Oliver",
        "lastName": "Wilson",
        "dateOfBirth": "1977-07-01",
        "phoneNumber": "+3725064992",
        "avatar": "",
        "occupation": "",
        "occupations": null,
        "primaryAddress": null,
        "firstNameInKana": null,
        "lastNameInKana": null
      }
    },
    {
      "id": <your business profile id>,
      "type": "business",
      "details": {
        "name": "ABC Logistics Ltd",
        "registrationNumber": "12144939",
        "acn": null,
        "abn": null,
        "arbn": null,
        "companyType": "LIMITED",
        "companyRole": "OWNER",
        "descriptionOfBusiness": "CHARITY_AND_NOT_FOR_PROFIT",
        "webpage": "https://abc-logistics.com",
        "primaryAddress": null,
        "businessCategory": "CHARITY_AND_NOT_FOR_PROFIT",
        "businessSubCategory": "CHARITY_ALL_ACTIVITIES"
       }
    }
]

List of all profiles belonging to user.

Request

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

Create Identification Document

Example Request:

curl -X POST https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/verification-documents \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
            "firstName": "Oliver",
            "lastName": "Wilson",
            "type": "IDENTITY_CARD",
            "uniqueIdentifier": "AA299822313",
            "issueDate": "2017-12-31",
            "issuerCountry": "EE",
            "issuerState": "",
            "expiryDate": "2027-12-31"
        }'

Example Response:

{
  "errorMessage": null,
  "success": true
}

Add identification document details to user profile. Applicable to personal profiles (not business) only.
Returns empty result if successful.

When sending a social security number (SSN) only type and uniqueIdentifier (only 9 digits no letters or symbols) are required.

Request

POST https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/verification-documents

Field Description Format
firstName Person first name in document. Text
lastName Person last name in document. Text
type (conditional) Document type. Allowed Values:
  • DRIVERS_LICENCE
  • IDENTITY_CARD
  • GREEN_CARD
  • MY_NUMBER
  • PASSPORT
  • SSN
  • EMIRATES_EMPLOYER
  • EMIRATES_PLACE_OF_BIRTH
  • OTHER
Text
uniqueIdentifier (required) Document number. Only digits when SSN. Text
issueDate Document issue date. YYYY-MM-DD
issuerCountry Issued by country code. For example "US". Text
issuerState Issued by state code. For example "NY". Text
expiryDate Document expiry date. YYYY-MM-DD
nationality 2 characters ISO country code. Text
employerName The name of the employer. Type must be EMIRATES_EMPLOYER. Text
employerCity The city of the employer. Type must be EMIRATES_EMPLOYER. Text
employerCountry 2 characters ISO country code. Type must be EMIRATES_EMPLOYER. Text
birthCity The city of birth of the customer. Type must be EMIRATES_PLACE_OF_BIRTH Text
birthCountry 2 characters ISO country code. Type must be EMIRATES_PLACE_OF_BIRTH Text

Get business directors

Example Request:

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

Example Response:

[
  {
    "id": 10,
    "firstName": "John",
    "lastName": "Doe",
    "dateOfBirth": "1982-05-20",
    "countryOfResidenceIso3Code": "usa"
  },
  {
    "id": 11,
    "firstName": "Jane",
    "lastName": "Doe",
    "dateOfBirth": "1981-12-07",
    "countryOfResidenceIso3Code": "usa"
  }
]

Returns the list of all directors associated with the business profile.

Request (Business)

GET https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/directors

Add business directors

Example Request:

curl -X POST https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/directors \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '[
             {
                 "firstName": "John",
                 "lastName": "Doe",
                 "dateOfBirth": "1982-05-20",
                 "countryOfResidenceIso3Code": "usa"
             },
             {
                 "firstName": "Jane",
                 "lastName": "Doe",
                 "dateOfBirth": "1981-12-07",
                 "countryOfResidenceIso3Code": "usa"
             }
        ]'

Example Response:

[
    {
        "id": 10,
        "firstName": "John",
        "lastName": "Doe",
        "dateOfBirth": "1982-05-20",
        "countryOfResidenceIso3Code": "usa"
    },
    {
        "id": 11,
        "firstName": "Jane",
        "lastName": "Doe",
        "dateOfBirth": "1981-12-07",
        "countryOfResidenceIso3Code": "usa"
    },
    {
        "id": 7,
        "firstName": "Oliver",
        "lastName": "Wilson",
        "dateOfBirth": "2017-12-31",
        "countryOfResidenceIso3Code": "gbr"
    }
]

Adds new directors to the business profile. Returns the list of all directors associated with the business profile.

Request (Business)

POST https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/directors

Field Description Format
firstName Director first name Text
lastName Director last name Text
dateOfBirth Date of birth YYYY-MM-DD
countryOfResidenceIso3Code 3 character country code Text

Update business directors

Example Request:

curl -X PUT https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/directors \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '[
             {
                 "firstName": "John",
                 "lastName": "Doe",
                 "dateOfBirth": "1982-05-20",
                 "countryOfResidenceIso3Code": "usa"
             },
             {
                 "firstName": "Jane",
                 "lastName": "Doe",
                 "dateOfBirth": "1981-12-07",
                 "countryOfResidenceIso3Code": "usa"
             }
        ]'

Example Response:

[
    {
        "id": 14,
        "firstName": "John",
        "lastName": "Doe",
        "dateOfBirth": "1982-05-20",
        "countryOfResidenceIso3Code": "usa"
    },
    {
        "id": 15,
        "firstName": "Jane",
        "lastName": "Doe",
        "dateOfBirth": "1981-12-07",
        "countryOfResidenceIso3Code": "usa"
    }
]

Overrides directors in the business profile. Returns the list of all directors associated with the business profile.

Request (Business)

PUT https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/directors

Field Description Format
firstName Director first name Text
lastName Director last name Text
dateOfBirth Date of birth YYYY-MM-DD
countryOfResidenceIso3Code 3 character country code Text

Get business ultimate beneficial owners

Example Request:

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

Example Response:

[
    {
        "id": "013ab1c2688d0185b582ee7e0bcb28b2",
        "name": "John Doe",
        "dateOfBirth": "1982-05-20",
        "countryOfResidenceIso3Code": "usa",
        "addressFirstLine": "123 Fake St",
        "postCode": "FK 12345",
        "ownershipPercentage": 30
    },
    {
        "id": "912ce3f31c8b3a10572137e78417caa3",
        "name": "Jane Doe",
        "dateOfBirth": "1981-12-07",
        "countryOfResidenceIso3Code": "usa",
        "addressFirstLine": "125 Fake St",
        "postCode": "FK 12545",
        "ownershipPercentage": 70
    }
]

Returns the list of all ultimate beneficial owners associated with the business profile.

Request (Business)

GET https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/ubos

Add business ultimate beneficial owners

Example Request:

curl -X POST https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/ubos \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '[
             {
                 "name": "John Doe",
                 "dateOfBirth": "1982-05-20",
                 "countryOfResidenceIso3Code": "usa",
                 "addressFirstLine": "123 Fake St",
                 "postCode": "FK 12345",
                 "ownershipPercentage": 30
             },
             {
                 "name": "Jane Doe",
                 "dateOfBirth": "1981-12-07",
                 "countryOfResidenceIso3Code": "usa",
                 "addressFirstLine": "125 Fake St",
                 "postCode": "FK 12545",
                 "ownershipPercentage": 40
             }
        ]'

Example Response:

[
     {
         "id": "f3e71aa1c97448d0b1eb5bdc0bacdcce",
         "name": "John Doe",
         "dateOfBirth": "1982-05-20",
         "countryOfResidenceIso3Code": "usa",
         "addressFirstLine": "123 Fake St",
         "postCode": "FK 12345",
         "ownershipPercentage": 30
     },
     {
         "id": "c6008d58a1664413b4c4dcacec1377f4",
         "name": "Jane Doe",
         "dateOfBirth": "1981-12-07",
         "countryOfResidenceIso3Code": "usa",
         "addressFirstLine": "125 Fake St",
         "postCode": "FK 12545",
         "ownershipPercentage": 40
     },
     {
         "id": "63bbdd1cf5ec4dd587597e74dbace376",
         "name": "Oliver Wilson",
         "dateOfBirth": "2017-12-31",
         "countryOfResidenceIso3Code": "gbr",
         "addressFirstLine": "222 Fake St",
         "postCode": "FK 22222",
         "ownershipPercentage": 30
     }
]

Adds new ultimate beneficial owners to the business profile. Returns the list of all ultimate beneficial owners associated with the business profile.

Note that in some cases, we do not require the ownershipPercentage. In these cases, null should be passed as the value.

Request (Business)

POST https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/ubos

Field Description Format
name Owner full name Text
dateOfBirth Date of birth YYYY-MM-DD
countryOfResidenceIso3Code 3 character country code Text
addressFirstLine First line of address Text
postCode Address post code Text
ownershipPercentage Percentage of ownership Integer

Update business ultimate beneficial owners

Example Request:

curl -X PUT https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/ubos \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '[
             {
                 "name": "John Doe",
                 "dateOfBirth": "1982-05-20",
                 "countryOfResidenceIso3Code": "usa",
                 "addressFirstLine": "123 Fake St",
                 "postCode": "FK 12345",
                 "ownershipPercentage": 30
             },
             {
                 "name": "Jane Doe",
                 "dateOfBirth": "1981-12-07",
                 "countryOfResidenceIso3Code": "usa",
                 "addressFirstLine": "125 Fake St",
                 "postCode": "FK 12545",
                 "ownershipPercentage": 70
             }
        ]'

Example Response:

[
     {
         "id": "ff01cf3f206b40c090a14a1e51163e9e",
         "name": "John Doe",
         "dateOfBirth": "1982-05-20",
         "countryOfResidenceIso3Code": "usa",
         "addressFirstLine": "123 Fake St",
         "postCode": "FK 12545",
         "ownershipPercentage": 30
     },
     {
         "id": "c36b687d28ad44ad8c3864411f5f2612",
         "name": "Jane Doe",
         "dateOfBirth": "1981-12-07",
         "countryOfResidenceIso3Code": "usa",
         "addressFirstLine": "125 Fake St",
         "postCode": "FK 12545",
         "ownershipPercentage": 70
     }
]

Overrides ultimate beneficial owners in the business profile. Returns the list of all ultimate beneficial owners associated with the business profile.

Request (Business)

PUT https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/ubos

Field Description Format
name Owner full name Text
dateOfBirth Date of birth YYYY-MM-DD
countryOfResidenceIso3Code 3 character country code Text
addressFirstLine First line of address Text
postCode Address post code Text
ownershipPercentage Percentage of ownership Integer

Remove Trusted Verification from Profile

Example Request:

curl -X DELETE https://api.sandbox.transferwise.tech/v3/profiles/{profileId}/trusted-verification \
     -H "Authorization: Bearer {client-credentials-token}" 

Example Response (204):

No Content

This endpoint allows partners to remove the verification that was given to the profile through them creating the profile. This does not delete a profile nor archive it, it simply removes the trusted verification from that partner.

Note that this uses a client-credentials-token and not a user access_token for authentication.

Open update window

Example Request:

curl -X POST https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/update-window \
     -H "Authorization: Bearer <your api token>" 

Example Response:

Opens the update window for updating the profile information: details, addresses, directors, owners, others.

Request

POST https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/update-window

Close update window

Example Request:

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

Example Response:

Deletes the update window for updating the profile.

Request

DELETE https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/update-window

Profile extensions

Example Request:

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

Example Response:

[
  {
    "type": "profile-extensions-requirements",
    "usageInfo": null,
    "fields": [
      {
        "name": "Tell us what you're using TransferWise for",
        "group": [
          {
            "key": "accountPurpose",
            "name": "Account Purpose",
            "type": "select",
            "refreshRequirementsOnChange": false,
            "required": true,
            "displayFormat": null,
            "example": null,
            "minLength": null,
            "maxLength": null,
            "validationRegexp": null,
            "validationAsync": null,
            "valuesAllowed": [
              {
                "key": "CONTRIBUTING_TO_PERSONAL_SAVINGS",
                "name": "Contributing to personal savings"
              },
              {
                "key": "GENERAL_MONTHLY_LIVING_EXPENSES",
                "name": "General monthly living expenses"
              },
              {
                "key": "INVESTING_IN_FUNDS_STOCKS_BONDS_OPTIONS_FUTURES_OR_OTHER",
                "name": "Investing in funds stocks bonds options futures or other"
              },
              {
                "key": "PAYING_FOR_GOODS_OR_SERVICES_ABROAD",
                "name": "Paying for goods or services abroad"
              },
              {
                "key": "PAYING_RENT_MORTGAGE_BANK_LOAN_INSURANCE_CREDIT",
                "name": "Paying rent mortgage bank loan insurance credit"
              },
              {
                "key": "PAYING_RENT_UTILITIES_OR_PROPERTY_CHARGES",
                "name": "Paying rent utilities or property charges"
              },
              {
                "key": "RECEIVE_SALARY_IN_DIFFERENT_CURRENCY",
                "name": "Receive salary in different currency"
              },
              {
                "key": "RECEIVE_PENSION_IN_DIFFERENT_CURRENCY",
                "name": "Receive pension in different currency"
              },
              {
                "key": "SENDING_MONEY_REGULARLY_TO_FAMILY",
                "name": "Sending money regularly to family"
              },
              {
                "key": "SENDING_MONEY_TO_MY_OWN_ACCOUNT_TO_BENEFIT_FROM_EXHCANGE_RATE",
                "name": "Sending money to my own account to benefit from exchange rate"
              }
            ]
          }
        ]
      }
    ]
  }
]

After having a profile created, in some situations we can need more specific information about it. In order to know which fields are required for a given profile, and to send the information over, we expose a few endpoints:

GET https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/extension-requirements
POST https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/extension-requirements

and

POST https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/extensions
GET https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/extensions

The GET and POST profile extension-requirements endpoints help you to figure out which fields are required to create a valid profile for different regions. You can use this data to build a dynamic user interface on top of these endpoints.

The POST and GET profile extensions endpoints allow you to send the extra profile information and retrieve it, respectively.

This format for dynamic forms is the same as the one used for recipient creation. See Recipient.Requirements and Using account requirements

This is a step-by-step guide on how these endpoints work.

Using profile extension requirements

  1. First create a profile. See User Profiles Create (Personal) and User Profiles Create (Business)

  2. Call GET /v1/profiles/{profileId}/extension-requirements to get the list of fields you need to fill with values in the "details" section for adding information that will make a profile valid.

  3. Some fields require multiple levels of fields in the details request. This should be handled by the client based on the refreshRequirementsOnChange field. A top level field can have 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 extension-requirements endpoint. You will be returned a response similar the previously returned data from GET extension-requirements but with additional fields.

  4. Once you have built your full profile extension details object you can add it to add information to the profile.

This is a valid request to add information to a profile:

POST v1/profiles/{profileId}/extensions

{
    "details": {
        "accountPurpose": "SENDING_MONEY_REGULARLY_TO_FAMILY"
    }
}

Building an user interface

When requesting the form data from the extension-requirements endpoint, the response defines different types of extensions that can be added. Each extension 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 will also be done when a completed profile extension is submitted to POST /v1/profiles/{profileId}/extensions.

Response

Field Description Format
type "profile-extensions-requirements" 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 extension-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

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.

















































Exchange Rates

List

Example Request (Bearer token):

curl -X GET "https://api.sandbox.transferwise.tech/v1/rates?source=EUR&target=USD" \
     -H "Authorization: Bearer <your api token>"

Example Request (Basic authentication):

curl -X GET "https://api.sandbox.transferwise.tech/v1/rates?source=EUR&target=USD" \
     --user <your api client_id>:<your api client_secret> 

Example Response:

[
    {
        "rate": 1.166,
        "source": "EUR",
        "target": "USD",
        "time": "2018-08-31T10:43:31+0000"
    }
]

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

Fetch latest exchange rates of all currencies.

GET https://api.sandbox.transferwise.tech/v1/rates?source=EUR&target=USD

Fetch latest exchange rate of one currency pair.

GET https://api.sandbox.transferwise.tech/v1/rates?source=EUR&target=USD&time=2019-02-13T14:53:01

Fetch exchange rate of specific historical timestamp.

GET https://api.sandbox.transferwise.tech/v1/rates?source=EUR&target=USD&from=2019-02-13T14:53:01&to=2019-03-13T14:53:01&group=day

Fetch exchange rate history over period of time with daily interval.

GET https://api.sandbox.transferwise.tech/v1/rates?source=EUR&target=USD&from=2019-02-13T14:53:01&to=2019-03-13T14:53:01&group=hour

Fetch exchange rate history over period of time with hourly interval.

GET https://api.sandbox.transferwise.tech/v1/rates?source=EUR&target=USD&from=2019-02-13T14:53:01&to=2019-03-13T14:53:01&group=minute

Fetch exchange rate history over period of time with 1 minute interval.

Request

Note that this endpoint supports two types of authentication: Bearer token and Basic authentication (client_id/client_secret).

Field Description Format
source Source(send) currency code. Text
target Target(receive) currency code. Text
time Timestamp to get historic exchange rate. Timestamp
from Period start date/time to get exchange rate history. Timestamp or Date
to Period end date/time to get exchange rate history. Timestamp or Date
group Interval: day hour minute Text

Response

List of exchange rate values which meet your query criteria.

Field Description Format
rate Exchange rate value. Decimal
source Source(send) currency code Text
target Target(receive) currency code Text
time Timestamp for exchange rate. Timestamp

Additional notes about date/time formatting used above

The request/response field(s) below support both Timestamp (combined date and time) and Date (date only) formats:

Field Sample
from 2019-03-13T14:53:01 or 2019-03-13
to 2019-03-13T14:53:01+0100 or 2019-03-13+0100

The request/response field(s) below support only Timestamp (combined date and time):

Field Sample
time 2019-03-13T14:53:01 or 2019-03-13T14:53:01+0100

Timezone offset is supported but optional.

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

Simulation

Simulate Transfer Processing

Example Request:

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

Example Response:

{
  "id": 15574445,
  "user": 294205,
  "targetAccount": 7993919,
  "sourceAccount": null,
  "quote": 113379,
  "status": "processing",
  "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"
}

You can simulate payment processing by changing transfer statuses using these endpoints.

This feature is limited to sandbox only.

Request

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

Changes transfer status from incoming_payment_waiting to processing.

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

Changes transfer status from processing to funds_converted.

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

Changes transfer status from funds_converted to outgoing_payment_sent.

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

Changes transfer status from outgoing_payment_sent to bounced_back.

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

Changes transfer status from bounced_back to funds_refunded.

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

Triggers a webhook refund for the transfer (requires previous custom configuration on both ends, please contact support for more info). You only need to use this state if you are using a webhook based refund solution, which not all integrations require.

Response

Transfer entity with changed status.

Simulate Verification

Example Request:

curl -L -X POST 'https://api.sandbox.transferwise.tech/v1/simulation/verify-profile' \
  -H 'Authorization: Bearer <your api token>'

This endpoint verifies the user's profiles. The webhook event profiles#verification-state-change will be triggered which can help to test the integration.

Having a verified user is a requirement for MCA setup, otherwise account details will not be issued.

Request

POST https://api.sandbox.transferwise.tech/v1/simulation/verify-profile

Verify all user profiles. It also triggers the notification webhook.

Use the user api token in the request. The profiles will be fetched based on the token's authentication details.

Topup balance

Example Request:

curl -L -X POST 'https://api.sandbox.transferwise.tech/v1/simulation/balance/topup' \
  -H 'Authorization: Bearer <your api token>' \
  -H 'Content-Type: application/json' \
  -d '{
      "profileId": 2,
      "balanceId": 5,
      "currency": "EUR",
      "amount": 100
  }'

Example Response:

{
    "transactionId": 5,
    "state": "COMPLETED",
    "balancesAfter": [
        {
            "id": 5,
            "value": 100.00,
            "currency": "EUR"
        }
    ]
}

Simulates a topup so a balance can be used to fund transfers.

Request

POST https://api.sandbox.transferwise.tech/v1/simulation/balance/topup

Field Description Format
profileId User profile id Number
balanceId Balance id Number
currency Balance currency (should be the same currency as the balance) Text
amount Top up amount Number

Simulate Card Transaction

This endpoint simulates a card transaction authorisation in the sandbox environment. It can simulate ATM withdrawals and purchasing transactions.

Request

POST https://api.sandbox.transferwise.tech/v3/spend/profiles/{profileId}/cards/{cardToken}/transactions/authorisation

The transactionType field is optional. You can either set it to CASH_WITHDRAWAL for ATM withdrawals or remove it for other card transactions.

The possible pos values are:

  • CHIP_AND_PIN
  • CONTACTLESS_CARD
  • E_COMMERCE
  • MAGNETIC_STRIPE
  • MINIMAL
  • MOBILE_WALLET

The PIN checks has been removed on the card transaction authorisation simulation API endpoint. Any 4-digit number is accepted for the PIN.

The CVV1, ICVV and CVV2 values should be "123", "456" and "789" respectively.

Example request

curl --location --request POST 'https://api.sandbox.transferwise.tech/v3/spend/profiles/{profileId}/cards/{cardToken}/transactions/authorisation' \
     --header 'Authorization: Bearer <your api token>'
     --header 'Content-Type: application/json' \
     --data '{
          "pos": "CHIP_AND_PIN",
          "transactionType": "CASH_WITHDRAWAL",
          "amount": {
              "value": <transaction amount>
              "currency": "<ISO 4217 transaction currency code>"
          },
          "acquirer": {
              "institutionId": <Acquiring Institution ID>,
              "name": "<acquirer name>,
              "city": "<acquirer city>",
              "merchantCategoryCode": <merchant category code>,
              "country": "<2 letter country code using ISO 3166-1 alpha-2>",
              "acceptorTerminalId": "<Card Acceptor Terminal ID>",
              "acceptorIdCode": "<Card Acceptor ID Code>",
              "forwardingInstitutionId": "<Acquiring Institution ID>",
          },
          "cardData": {
              "pan": "<card 16-digit PAN>",
              "pin": "1234",
              "cvv1": "123" ,
              "icvv": "456",
              "cvv2": "789"
          }
     }'

Example response

{
  "reference": {
      "transaction": {
          "acquirer": {
              "institutionId": "430001",
              "name": "Test ATM withdrawal",
              "city": "Rouen",
              "merchantCategoryCode": 5999,
              "country": "FR",
              "acceptorTerminalId": "TERMID01",
              "acceptorIdCode": "CARD ACCEPTOR",
              "forwardingInstitutionId": "400050"
          },
          "card": {
              "token": "9dbf5c07-c142-4986-aa8e-2c2def9f6874",
              "schemeName": "VISA",
              "pan": "4596930008480972",
              "pin": "1234",
              "cvv1": "123",
              "icvv": "456",
              "cvv2": "789",
              "expiration": [
                  2027,
                  9
              ],
              "sequenceNumber": 1,
              "country": "AU",
              "currencies": [
                  "AUD"
              ]
          },
          "pos": {
              "type": "CHIP_AND_PIN",
              "acceptsOnlinePins": true,
              "maxPinLength": 12,
              "supports3ds": false,
              "hasChip": true
          },
          "transactionStartTime": 1667541087.047643305,
          "stan": "363054",
          "schemeTransactionId": "932290252416153",
          "retrievalReferenceNum": "230805363054"
      },
      "requestMti": "0200",
      "authorizationIdResponse": "123646"
  },
  "error": null
}

Terms and Conditions

Get Terms and Conditions

Example Request:

curl -X GET "https://api.sandbox.transferwise.tech/v1/terms/default"

Example Response:

<h2><strong>1. How to read this Agreement</strong></h2>
<p>This Agreement contains 30 sections. You may go directly to any section by selecting the appropriate link provided. The headings are for reference only. Some capitalised terms have specific definitions in section [3]. Underlined words in this Agreement contain hyperlinks to further information.</p>
<h2><strong>2. Why you should read this Agreement</strong></h2>
<p>2.1 What this Agreement cover. These are the term and conditions on which we provide our Services to you.</p>
<p>2.2 Why you should read them. Please read this Agreement carefully before you start to use our Services. This Agreement (always together with the documents referred to in it) tell you who we are, how we will provide the Services to you, how this Agreement may be changed or ended, what to do if there is a problem and other important information. If you think that there is a mistake in this Agreement or require any changes, please <u>contact us</u> to discuss.</p>
<p>2.3 Other additional documents which applies to you. This Agreement refers to the following additional documents, which also apply to your use of our Services:</p>
<ul><li>(a) <u>Our Privacy Policy</u>, which sets out the terms on which we process any personal data we collect about you, or that you provide to us. By using our Services, you consent to such processing and you promise that all data provided by you is accurate.</li>
<li>(b) <u>Our Cookie Policy</u>, which sets out information about the “cookies” on our Website.</li>
...

Get Wise terms and conditions in HTML format to show to your customers who are signing up for their Wise account. This endpoint is applicable for bank integrations and third party application integrators only.

Request

GET https://api.sandbox.transferwise.tech/v1/terms/{clientId}

Use "default" as clientId to fetch Transferwise general terms and conditions.

No authentication is required for this endpoint.

Response

Terms and conditions in HTML format.

Third-Party Transfers

Create

Example Request (Originator Type = PRIVATE):

curl -X POST https://api.sandbox.transferwise.tech/v2/profiles/{profileId}/third-party-transfers \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "targetAccount": <recipient account id>,   
          "quote": "<v2 quote id>",
          "originalTransferId": "<unique transfer id in your system>",
          "details" : {
              "reference" : "Ski trip"
          },
          "originator" : {
              "legalEntityType" : "PRIVATE",
              "reference" : "<unique customer id in your system>",
              "name" : {
                "givenName": "John",
                "middleNames": ["Ryan"],
                "familyName": "Godspeed"
              },
              "dateOfBirth": "1977-07-01",
              "address" : {
                "firstLine": "Salu tee 100, Apt 4B",
                "city": "Tallinn",
                "countryCode": "EE",
                "postCode": "12112"
              }
          } 
         }'

Example Request (Originator Type = BUSINESS):

curl -X POST https://api.sandbox.transferwise.tech/v2/profiles/{profileId}/third-party-transfers \
     -H "Authorization: Bearer <your api token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "targetAccount": <recipient account id>,   
          "quote": "<v2 quote id>",
          "originalTransferId": "<unique transfer id in your system>",
          "details" : {
              "reference" : "Payment for invoice 22092"
          },
          "originator" : {
              "legalEntityType" : "BUSINESS",
              "reference" : "<originator customer id in your system>",
              "name" : {
                "fullName": "Hot Air Balloon Services Ltd"
              },
              "businessRegistrationCode": "1999212",
              "address" : {
                "firstLine": "Aiandi tee 1431",
                "city": "Tallinn",
                "countryCode": "EE",
                "postCode": "12112"
              }
          } 
       }'

Example Response:


{
    "id": 47755772,
    "originalTransferId": "PMT-29991221",
    "user": <your user id>,
    "targetAccount": <recipient account id>,
    "quote": "<v2 quote id>",
    "status": "incoming_payment_waiting",
    "rate": 0.8762,
    "details": {
        "reference": "Ski trip"
    },
    "hasActiveIssues": false,
    "sourceCurrency": "EUR",
    "sourceValue": 0,
    "targetCurrency": "GBP",
    "targetValue": 500,
    "originator": {
        "name": {
            "givenName": "John",
            "middleNames": [
                "Ryan"
            ],
            "familyName": "Godspeed",
            "patronymicName": null,
            "fullName": "John Godspeed"
        },
        "dateOfBirth": "1977-07-01",
        "reference": "CST-2991992",
        "legalEntityType": "PRIVATE",
        "businessRegistrationCode": null,
        "address": {
            "firstLine": "Salu tee 14",
            "city": "Tallinn",
            "stateCode": null,
            "countryCode": "EE",
            "postCode": "12112"
        }
    },
    "created": "2019-02-18T12:59:42.000Z"
}

This endpoint is applicable for Third-Party Payouts use case only.

Request

POST https://api.sandbox.transferwise.tech/v2/profiles/{profileId}/third-party-transfers

This is very similar to Create transfers endpoint, but please note these differences:

  • originator datablock is additionally required
  • originalTransferId field is being used instead of customerTransactionId
Field Description Format
targetAccount Recipient account id. You can create multiple transfers to same recipient account. Integer
quote V2 quote id. You can only create one transfer per one quote.
You cannot use same quote ID to create multiple transfers.
Text
originalTransferId Unique transfer id in your system. We use this field also to perform idempotency check to avoid duplicate transfers in case of network failures or timeouts. You can only submit one transfer with same originalTransferId. Text
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
originator Data block to capture payment originator details. Group
originator.legalEntityType PRIVATE or BUSINESS. Payment originator legal type. Text
originator.reference Unique customer id in your system. This allows us to uniquely identify each originator. Required. Text
originator.name.givenName Payment originator first name. Required if legalEntityType = PRIVATE. Text
originator.name.middleNames Payment originator middle name(s). Used only if legalEntityType = PRIVATE. Optional Text Array
originator.name.familyName Payment originator family name. Required if legalEntityType = PRIVATE. Text
originator.name.patronymicName Payment originator patronymic name. Used only if legalEntityType = PRIVATE. Optional Text
originator.name.fullName Payment originator full legal name. Required if legalEntityType = BUSINESS. Text
originator.dateOfBirth Payment originator date of birth. Required if legalEntityType = PRIVATE. YYYY-MM-DD
originator.businessRegistrationCode Payment originator business registry number / incorporation number. Required if legalEntityType = BUSINESS. Text
originator.address.firstLine Payment originator address first line. Required Text
originator.address.city Payment originator address city. Required Text
originator.address.stateCode Payment originator address state code. Required if address country code in (US, CA, BR, AU). See Countries and states Text
originator.address.countryCode Payment originator address first line. Required Text
originator.address.postCode Originator address zip code. Optional Text

Response

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

Field Description Format
id Transfer id Integer
originalTransferId Transfer id Integer
user Your user id Integer
targetAccount Recipient account id Integer
sourceAccount Not used Integer
quote v2 quote id Text
status Transfer current status Text
rate Exchange rate value Decimal
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
originator Data block to capture payment originator details Group
originator.legalEntityType Payment originator legal type. Text
originator.reference Unique customer id in your system. Text
originator.name.givenName Payment originator first name. Text
originator.name.middleNames Payment originator middle name(s). Text Array
originator.name.familyName Payment originator family name. Text
originator.name.patronymicName Payment originator patronymic name. Text
originator.name.fullName Payment originator full legal name. Text
originator.dateOfBirth Payment originator date of birth. YYYY-MM-DD
originator.businessRegistrationCode Payment originator business registry number / incorporation number. Text
originator.address.firstLine Payment originator address first line. Text
originator.address.city Payment originator address city. Text
originator.address.stateCode Payment originator address state code. Text
originator.address.countryCode Payment originator address first line. Text
originator.address.postCode Originator address zip code. Text
created Timestamp when transfer was created Timestamp

Avoiding duplicate transfers

We use originalTransferId field to avoid duplicate transfer requests. When your first call fails (error or timeout) then you should use the same value in originalTransferId field that you used in the original call when you are submitting a retry message. This way we can treat subsequent retry messages as repeat messages and will not create duplicate transfers to your account.

Managing third-party transfers

Please refer to our Transfers section.

Fund

Please refer to our Transfer Fund section.

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. Upon calling the endpoint Wise will start processing your transfer and fund the transfer immediately if possible.

When using the BALANCE option, 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.

When using the TRUSTED_PRE_FUND_BULK option, Wise will count the transfer amount towards your held collateral. If there are not enough collateral funds to cover the amount of the transfer, the call will still succeed but be placed in a queue and funded when sufficient collateral is restored. For more information on this, please speak to our team.

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

  • BANK_TRANSFER - where you send the funds directly to Wise's bank account.
  • 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




































Users

Get By Id

Example Request:

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

Example Response:

{
  "id": 101,
  "name": "Example Person",
  "email": "person@example.com",
  "active": true,
  "details": {
    "firstName": "Example",
    "lastName": "Person",
    "phoneNumber": "+37111111111",
    "occupation": "",
    "address": {
      "city": "Tallinn",
      "countryCode": "EE",
      "postCode": "11111",
      "state": "",
      "firstLine": "Road 123"
    },
    "dateOfBirth": "1977-01-01",
    "avatar": "https://lh6.googleusercontent.com/photo.jpg",
    "primaryAddress": 111
  }
}

Get authenticated user details by user id. Response includes also personal user profile info.

Request

GET https://api.sandbox.transferwise.tech/v1/users/{userId}

Response

Field Description Format
id userId Integer
name User full name Text
email User email Text
active If user is active or not Boolean
details.firstName User first name Text
details.lastName User lastname Text
details.phoneNumber Phone number Text
details.dateOfBirth Date of birth YYYY-MM-DD
details.occupation Person occupation Text
details.avatar Link to person avatar image Text
details.primaryAddress Address object id to use in addesses endpoints Integer
details.address.countryCode Address country code in 2 digits. "US" for example Text
details.address.firstLine Address first line Text
details.address.postCode Address post code Text
details.address.city Address city name Text
details.address.state Address state code State code. Required if country is US, CA, AU, BR. Text
details.address.occupation User occupation. Required for US, CA, JP Text

Get the currently logged in user

Example Request:

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

Example Response:

{
  "id": 101,
  "name": "Example Person",
  "email": "person@example.com",
  "active": true,
  "details": {
    "firstName": "Example",
    "lastName": "Person",
    "phoneNumber": "+37111111111",
    "occupation": "",
    "address": {
      "city": "Tallinn",
      "countryCode": "EE",
      "postCode": "11111",
      "state": "",
      "firstLine": "Road 123"
    },
    "dateOfBirth": "1977-01-01",
    "avatar": "https://lh6.googleusercontent.com/photo.jpg",
    "primaryAddress": 111
  }
}

Get authenticated user details for the user's token submitted in the Authorization header. Response includes also personal user profile info.

Request

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

Response

Field Description Format
id userId Integer
name User full name Text
email User email Text
active If user is active or not Boolean
details.firstName User first name Text
details.lastName User lastname Text
details.phoneNumber Phone number Text
details.dateOfBirth Date of birth YYYY-MM-DD
details.occupation Person occupation Text
details.avatar Link to person avatar image Text
details.primaryAddress Address object id to use in addesses endpoints Integer
details.address.countryCode Address country code in 2 digits. "US" for example Text
details.address.firstLine Address first line Text
details.address.postCode Address post code Text
details.address.city Address city name Text
details.address.state Address state code State code. Required if country is US, CA, AU, BR. Text
details.address.occupation User occupation. Required for US, CA, JP Text

Sign Up with Registration Code

  1. Example Request: Get Client Credentials Token
curl -X "POST" "https://api.sandbox.transferwise.tech/oauth/token" \
     -H 'Content-Type: application/x-www-form-urlencoded' \
     -u '[your-api-client-id]:[your-api-client-secret]' \
     --data-urlencode "grant_type=client_credentials" 
  1. Example Response: Get Client Credentials Token
  {
    "access_token":"ba8k1234-00f2-475a-60d8-6g45377b4062",
    "token_type":"bearer",
    "expires_in": 43199,
    "scope":"transfers"
  }

















  1. Example Request: Create User
curl -X POST https://api.sandbox.transferwise.tech/v1/user/signup/registration_code \
     -H "Authorization: Bearer <your client credentials token>" \
     -H "Content-Type: application/json" \
     -d '{ 
          "email": <user email>,
          "registrationCode": <registration code>,
          "language":"PT"
        }'
  1. Example Response: Create User (Success (200) user created successfully)
      {
        "id": 12345,
        "name": null,
        "email": "new.user@domain.com",
        "active": true,
        "details": null
      }
  1. Example Response: Create User (Failure (409): User already exists)
      {
        "errors": [
          {
            "code": "NOT_UNIQUE",
            "message": "You’re already a member. Please login",
            "path": "email",
            "arguments": [
              "email",
              "class com.transferwise.fx.api.ApiRegisterCommand",
              "existing.user@domain.com"
            ]
          }
        ]
      }








  1. Example Request: Get User Tokens
curl --location --request POST 'https://api.sandbox.transferwise.tech/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--user '[your-api-client-id]:[your-api-client-secret]' \
--data-urlencode 'grant_type=registration_code' \
--data-urlencode 'client_id=[your-api-client-id]' \
--data-urlencode 'email=<user email>' \
--data-urlencode 'registration_code=<registration code used to create user>'
  1. Example Response: Get User Tokens (Success: 200)
    {
      "access_token": "01234567-89ab-cdef-0123-456789abcdef",
      "token_type": "bearer",
      "refresh_token": "01234567-89ab-cdef-0123-456789abcdef",
      "expires_in": 43199,
      "scope": "transfers"
    }
  1. Example Response: Get User Tokens (Failure: 401 - User reclaimed the account or invalid registration code used)
    {
      "error": "invalid_grant",
      "error_description": "Invalid user credentials."
    }

This feature is related to Bank Integrations product. It enables onboarding new users to Wise via backend API calls only. To get authorization from Transferwise existing users you still need to redirect them to our authorization webpage.

There are 3 steps you need to go through:

1) Get Client Credentials Token

Obtain access_token based on your API client credentials.

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 "client_credentials" Text

Response

Field Description Format
access_token Access token to be used when calling "create user" endpoint. Valid for 12 hours. Text
token_type "bearer" Text
expires_in Expiry time in seconds Integer
scope "transfers" Text

2) Create User

Wise uses email address as unique identifier for users. If email is new (there is no active user already) then new user will be created.

When you are submitting an email which already exists amongst our users then you will get a warning that "You’re already a member. Please login". If user already exists then you need to redirect to Get user authorization webpage.

Request

POST https://api.sandbox.transferwise.tech/v1/user/signup/registration_code

Use access_token obtained in first step as authentication header.

Field Description Format
email New user's email address Email
registrationCode Randomly generated registration code that is unique to this user. At least 32 characters long.
You need to store registration code to obtain access token on behalf of this
newly created user in next step.
Please apply the same security standards to handling registration code as if it was a password.
Text, min length is 32 chars
language (Optional) User default language for UI and email communication.
Allowed values EN, US, PT, ES, FR, DE, IT, JA, RU, PL, HU, TR, RO, NL, HK. Default value EN.
Text, 2 chars

Response

Field Description Format
id userId Integer
name User full name. Empty. Text
email Customer email Text
active true Boolean
details User details. Empty. Group

3) Get User Tokens

You can now use registration code to obtain user access token and refresh token. This step can be repeated as long as user does not reclaim their Wise account. If user has reclaimed the account, then redirect to Get user authorization flow should be used instead.

Refresh user access token works same way for this flow as well.

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 "registration_code" Text
email New user's email address Email
client_id Your api_client_id Text
registration_code registrationCode from step 2 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. The lifetime of refresh tokens is 20 years. Text
expires_in Expiry time in seconds Integer
scope "transfers" Text

Get access token from authorization code

Pre-requisites:

  • Get your client credentials (Client id and Client secret) from our tech support team
  • Create your account and complete profile creation and verification on https://wise.com

The standard website redirection flow is as follows:

Example Request: Get User Tokens

curl --location --request POST 'https://api.sandbox.transferwise.tech/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--user '[your-api-client-id]:[your-api-client-secret]' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'client_id=[your-api-client-id]' \
--data-urlencode 'email=<user email>' \
--data-urlencode 'code=<authorization code from the rediect uri>'

Example Response: Get User Tokens (Success: 200)

    {
      "access_token": "01234567-89ab-cdef-0123-456789abcdef",
      "token_type": "bearer",
      "refresh_token": "01234567-89ab-cdef-0123-456789abcdef",
      "expires_in": 43199,
      "scope": "transfers"
    }

Example Response: Get User Tokens (Failure: 401 - User reclaimed the account or invalid registration code used)

    {
      "error": "invalid_grant",
      "error_description": "Invalid user credentials."
    }

Get User Tokens

You can now use authorization code to obtain user access token and refresh token.

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 "authorization_code" Text
email New user's email address Email
client_id Your api_client_id Text
code authorization_Code 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. The lifetime of refresh tokens is 20 years. Text
expires_in Expiry time in seconds Integer
scope "transfers" Text

Language Support

Internationalisation support for translation of strings returned by the API is supported for the following endpoints:

Endpoint
/v1/quotes
/v1/quotes/<quoteId/quoteUuid>/account-requirements
/v1/accounts
/v1/transfers
/v1/transfer-requirements
/v1/profiles/<profileId>/transfers/<transferId>/deposit-details/bank-transfer

When calling these endpoints if you include an Accept-Language header with a supported language code as the value then strings will be returned in the requested language. The languages supported by Wise are:

Language Code
American English en_US
Arabic ar
British English en
Chinese zh
Czech cs
Dutch nl
French fr
German de
Hebrew he
Hungarian hu
Italian it
Japanese ja
Korean ko
Polish pl
Portuguese pt
Romanian ro
Russian ru
Spanish es
Turkish tr
Ukrainian uk

If you request an unsupported language then British English will be returned by default.

Application Webhooks

Application 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 by an application.

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

  • Has a valid domain name (IP addresses 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.

Client token

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 "client_credentials" Text

Response

Field Description Format
access_token Access token to be used when creating an application subscription. Valid for 12 hours. Text
token_type "bearer" Text
expires_in Expiry time in seconds Integer
scope "transfers" Text

Create

Example Request:

curl -X POST "https://api.sandbox.transferwise.tech/v3/applications/{clientKey}/subscriptions" \
  -H "Authorization: Bearer <your client level 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": "application", 
        "id": "<your client key>"
    },
    "created_by": {
        "type": "application",
        "id": "<your client ID>"  // clientId and key are not always the same
    },
    "created_at": "2019-10-10T13:55:57Z"
}

Request

POST https://api.sandbox.transferwise.tech/v3/applications/{clientKey}/subscriptions

{clientKey} can be received upon obtaining client credentials from our tech support.

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 version 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 Choose from a list of available events Text
delivery.version The event representation semantic version Text
delivery.url The URL where your server will be listening for events. Text
scope.domain Scope of this subscription, always "application" in this case Text
scope.id Client key used to create this subscription Text
created_by.type Creator type. Always application in this case Text
created_by.id Client ID of the creator. Not always the same as the client key 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.sandbox.transferwise.tech/v3/applications/{clientKey}/subscriptions/{id}" \
  -H "Authorization: Bearer <your client level token>"

Example Response:

Request

DELETE https://api.sandbox.transferwise.tech/v3/applications/{clientKey}/subscriptions/{id}

Get by ID

Retrieves a subscription by its identifier.

Example Request:

curl -X GET "https://api.sandbox.transferwise.tech/v3/applications/{clientKey}/subscriptions/{id}" \
  -H "Authorization: Bearer <your client level 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": "application", 
        "id": "<your client key>"
    },
    "created_by": {
        "type": "application",
        "id": "<your client ID>"  // clientId and key are not always the same
    },
    "created_at": "2008-09-15T15:53:00Z"
}

Request

GET https://api.sandbox.transferwise.tech/v3/applications/{clientKey}/subscriptions/{id}

Test notifications

Test notifications can be generated for existing application subscriptions using the API.

Test notifications will have the correct structure for their source subscription's event type and version, and will contain "dummy" data. These data include random UUIDs, entity IDs of zero, current dates and times, and hard-coded status codes.

Test notifications are delivered with the usual notification HTTP request headers, including a unique delivery ID for the notification, and a "test notification" flag set to true. You can check for the presence of this test flag to determine that an incoming notification is a test notification which should not be processed as real data. See the section Event HTTP requests for more information on request headers.

When test notifications are created with the API, they are queued for sending in the same way as non-test notifications. This means that there may be some delay in notification delivery, and delivery failures will result in attempts to redeliver the notification later. The API returns the delivery IDs of the notifications that have been successfully queued for sending, which can be correlated with the delivery ID header values for notifications you later receive.

Example Request:

curl -X POST "https://api.sandbox.transferwise.tech/v3/applications/{clientKey}/subscriptions/{subscriptionId}/test-notifications" \
  -H "Authorization: Bearer <your client level token>"

Example Response:

[
  {
    "delivery_id": "4a6b9810-4279-4de5-8d8d-1a6cf3b92a75",
    "created_at": "2019-03-28T11:22:33Z"
  }
]

Example Test Notification:

x-signature: bnho0q9JhjR6IPJIOZqWVP...
x-delivery-id: 4a6b9810-4279-4de5-8d8d-1a6cf3b92a75
x-test-notification: true

{
  "data": {
    "resource": {
      "id": 0,
      "profile_id": 0,
      "account_id": 0,
      "type": "transfer"
    },
    "current_state": "processing",
    "previous_state": "incoming_payment_waiting",
    "occurred_at": "2019-03-28T11:22:33Z"
  },
  "subscription_id": "39f241b7-293d-439e-beb3-4bf947bd4ff8",
  "event_type": "transfers#state-change",
  "schema_version": "2.0.0",
  "sent_at": "2019-03-28T11:22:33Z"
}

Request

POST https://api.sandbox.transferwise.tech/v3/applications/{clientKey}/subscriptions/{subscriptionId}/test-notifications

Response

List of test notifications that were scheduled for delivery.

Field Description Format
delivery_id UUID that uniquely identifies the notification Text
created_at Time the notification was created Text

List

List all your subscriptions.

Example Request:

curl -X GET "https://api.sandbox.transferwise.tech/v3/applications/{clientKey}/subscriptions" \
  -H "Authorization: Bearer <your client level 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": "application",
      "id": "<your client ID>"
    },
    "scope": {
      "domain": "application",
      "id": "<your client key>"
    }
  },
  {
    "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": "application",
      "id": "<your client ID>"
    },
    "scope": {
      "domain": "application",
      "id": "<your client key>"
    }
  }
]

Request

GET https://api.sandbox.transferwise.tech/v3/applications/{clientKey}/subscriptions

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
cards#transaction-state-change not supported 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