Base URL Sandbox
https://api.sandbox.transferwise.tech
Base URL LIVE
https://api.transferwise.com
Welcome to the Wise Platform API documentation. You can explore the different ways to use our API and choose the right one for you below.
This lets you automate how you use your Wise account. You can automate payments, connect your business tools, and create ways to manage your finances.
What are the benefits associated with automating your payouts and third party payments?
Third-Party Payouts allows marketplaces and financial institutions (banks and payment service providers) to use Wise as a payout option for their customers. It’s different from Payouts since it doesn’t require your company to be the originator of payments. Instead, Wise will act as a third-party to your customers when they initiate a payment through your site.
In addition there will also be a dedicated account manager who will be your primary contact to solve all questions and support issues should these arise.
Please note that subscribing to third party payouts service requires your company to complete enhanced due diligence process performed by Wise compliance team. Please contact our sales team for more info how to get started.
Our Payouts and third party payments guide will help you get started with the technical integration.
Our bank integration lets banks build Wise payments seamlessly into their own desktop and mobile apps. Banks can also build their own native user experience directly onto our API, co-branded with Wise.
Please visit our Postman collection for more details and examples of how to use our API, including how to implement payment initiation, user linking, creation and others.
What are the benefits for my bank?
How does it work?
See what some of our bank partners have to say
An example native user experience based on the Wise Platform API
Please contact banks@wise.com to get started.
Take a look at our technical integration here – Bank Integration Guide.
When you apply to the Wise affiliates program you can get access to our API to help you build your own valuable content for your customers or readers.
The Wise Platform API lets you to:
The Affiliates Integration Guide helps you get started with the technical integration.
Please visit our Postman collection for more details and examples of how to use our API, including how to get comparison, rates as well as pricing and speed data.
With Connected Applications, you can let your customers connect their Wise accounts to your product. Say you’re an accounting software – doing this could let your customers automate reconciliation. If you’re a payroll company, you could push customer payments right into Wise. You could even push Wise notifications through your app. Whatever you want to build, you likely could!
The Connected Apps Integration Guide helps you get started with the technical integration.
You can receive money to the local bank details that come with your Wise account (USD, EUR, GBP, AUD, NZD and PLN) and reconcile these incoming payments via the API.
You’re also able to create a webhook subscription to receive event callbacks to your server when payments are received. Here’s more information about the webhooks.
Please note that we don't send any information over webhook calls that might contain personally identifiable information (PII) about the sender (including the payment reference).
To reconcile incoming payments you might also need to match the information received via webhooks with the information that can be obtained from the statements.
Please visit our Postman collection for more details and examples of how to use our API, including how to set up webhook subscritions and get the account statements for reconciliation.
We currently don’t offer the option to build Wise into your checkout flow as a payment option to receive money. Note though that Wise can be added as a payout option on your site for beneficiaries to choose to receive their payout through to an email address, directly to a bank account or any other mechanism we support in our standard product.
Under the Second Payment Services Directive (PSD2) we are opening up the standardized version of our API to the rest of the world. Find out more about our Open Banking Guide.
We support the Australian Government's Consumer Data Right (CDR) legislation to give Australians greater control over their data. As a CDR participant, we are established as a Data Holder. In order to provide data to other participants, we have provided Banking APIs as per the standards. Find out more about our Consumer Data Right initiative.
The Wise Platform API is continuously evolving as we offer new features and coverage to our API customers. Here we explain how our API versioning is maintained so you know what to expect.
It's important to us that third-party integrations are not adversely affected by changes and we endeavor to uphold these standards as part of making convenience and transparency part of our company's mission. We are regularly reviewing our policies to make sure we're delivering the best possible API developer experience.
These policies apply to both our REST API and our webhooks (push-based event API).
A breaking change refers to any change that would require a client to update their application in order to continue working with the API as originally intended. If an API field or resource is removed or renamed, then a breaking change has taken place. In this case we will increment the version of the affected API endpoints to prevent breaking existing customer integrations.
Under our current policy API endpoints are not all versioned together, if API endpoint compatibility has changed in the new version as a result of a breaking change we will provide clear instructions in our documentation on which API calls must be used together.
Wise reserves the right to make additive changes to our API without incrementing the version number or notifying clients. We may add new resources, fields, and relationships to an existing version of the API and these will not be considered breaking changes.
For example, if we add a new relationship to the Transfer resource for a “parent_order”, we will neither bump the API version nor notify our customers before releasing the update. We will, however, update our API documentation explaining the purpose of the changes.
As such, clients should design their applications to be flexible enough to not break when new fields are added to resources.
It is not standard policy for Wise to remove or disable API versions, and we will not take this action lightly. However in some cases it may be necessary; for example if the affected API does not meet new regulatory requirements and there is no alternative to making a breaking change and disabling an old API.
In the extremely rare case that this is necessary we will not remove API endpoints without notice to clients who may be affected, and formal warning of at least 6 months as long as this complies with our regulatory obligations.
Having issues while calling our API endpoints? Check our API status at https://status.transferwise.com/ If you would like to receive status change notifications, feel free to sign up here.
Have a technical question about API? Send email to api@wise.com
Making lots of payments? We have a dedicated team to talk to you. Get in touch
Have a question about how Wise works?
Search Wise Help Centre. https://wise.com/help
Want more information about your payments?
Lookup Wise Support Centre details. https://wise.com/contact
The payouts and third party payments API guide/documentation is available here: Payouts guide
The payouts and third party payments API guide/documentation is available here: Payouts and third party payments guide
The bank integration documentation is available here: Wise for Banks API documentation
The multi-currency accounts guide is available here: Multi-Currency Accounts Guide
The affiliates integration guide is available here: Affiliates Integration Guide.
The connected apps integration guide is available here: Connected Apps Integration Guide.
The open banking guide is available here: Open Banking Guide.
The Australian CDR API guide is available here: Australian CDR API Guide.
The global currencies guide is available here: Global Currencies Guide.
The card issuance documentation is available here: Wise for Card issuance documentation
The SWIFT Receive integration documentation is available here: SWIFT Receive Implementation Guide
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.
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 |
|
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 |
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 |
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.
GET https://api.sandbox.transferwise.tech/v1/addresses/{addressId}
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.
GET https://api.sandbox.transferwise.tech/v1/addresses?profile={profileId}
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
}
]
}
...
]
}
]
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.
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: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.
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.
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.
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"
}
}
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 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.
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 |
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,
}
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.
Field | Description | Format |
---|---|---|
currency | balance currency (ISO 4217 Alphabetic Code) | text |
type | Type of Balance. Accepts STANDARD or SAVINGS |
text |
name | balance name | text |
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,
},
...
]
Retrieve the user's multi-currency account balance accounts. It returns all balance accounts the profile has in the types specified.
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
.
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,
}
This endpoint returns a balance based on the specified balance ID.
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,
}
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.
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
}
}
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).
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 |
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 |
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
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 |
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:
STANDARD
to SAVINGS
balance without conversion, amount
is provided as request parameter);amount
is determined by provided quoteId
);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
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 |
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.
GET https://api.sandbox.transferwise.tech/v1/borderless-accounts?profileId={profileId}
Use profile id obtained earlier to make this call.
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 |
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).
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.
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 |
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".
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 |
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
}
]
}
]
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
.
GET https://api.sandbox.transferwise.tech/v1/profiles/{profile-id}/account-details
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:
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"
}
]
}
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 |
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 |
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",
}
]
},
...
]
This endpoint returns the bank account assignment requests for a profile and multi-currency account.
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.
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 |
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 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 |
Account type | Account type | Currencies |
---|---|---|
checking |
Checking account | USD |
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 |
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 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": []
}
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 |
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 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": []
}
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 |
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 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>
}'
POST https://api.sandbox.transferwise.tech/v3/profiles/{profileId}/batch-groups/{batchGroupId}/transfers
For the request body format please see this documentation.
Please see the documentation.
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 |
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
}
]
}
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 |
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 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": []
}
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 |
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 |
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
]
}
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 |
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 |
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 |
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 |
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 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 |
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 |
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.
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:
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 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.
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:
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
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" |
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 |
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.
GET https://api.sandbox.transferwise.tech/v1/currency-pairs
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 |
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.
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",
...
]
This endpoint returns all the currencies available for balance accounts. You can use this list to create a balance account for the currency included.
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",
...
]
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.
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
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.
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
}
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
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 |
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",
"countryIso2Code": "BE",
"countryName": "Belgium",
"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",
"countryIso2Code": "GB",
"countryName": "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 |
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 |
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 (Deprecated) | Country ISO 2 code | Text |
payinBank.bankAddress.countryIso2Code | Country ISO 2 code | Text |
payinBank.bankAddress.countryName | Country name | 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 (Deprecated) | Country ISO 2 code | Text |
wiseInformation.localAddress.countryIso2Code | Country ISO 2 code | Text |
wiseInformation.localAddress.countryName | name | 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) |
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.
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.
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) |
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.
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:
|
Text | Must be one of the enum values. |
details.companyRole | Role of person. Allowed Values:
|
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 . |
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:
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 |
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.
PUT https://api.sandbox.transferwise.tech/v1/profiles
Request and response is same as described in Create (Personal) and Create (Business)
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.
GET https://api.sandbox.transferwise.tech/v1/profiles/{profileId}
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.
GET https://api.sandbox.transferwise.tech/v2/profiles
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.
GET https://api.sandbox.transferwise.tech/v1/profiles
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.
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:
|
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 |
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.
GET https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/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.
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 |
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.
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 |
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.
GET https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/ubos
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.
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 |
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.
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 |
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.
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.
POST https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/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.
DELETE https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/update-window
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.
First create a profile. See User Profiles Create (Personal) and User Profiles Create (Business)
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.
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.
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"
}
}
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
.
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 |
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": [
{
"reason": "sample reason"
}
],
"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.
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.
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.
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.
The option.estimatedDeliveryDelays
contains the reason
of the delay in a string format.
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 object with reason for delivery delays to display to users. | [EstimatedDeliveryDelays] |
option.estimatedDeliveryDelays.reason | Reason of delay | |
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 |
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": [
{
"reason": "sample reason"
}
],
"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.
PATCH https://api.sandbox.transferwise.tech/v3/profiles/{profileId}/quotes/{quoteId}
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": [
{
"reason": "sample reason"
}
],
"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.
GET https://api.sandbox.transferwise.tech/v3/profiles/{profileId}/quotes/{quoteId}
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": [
{
"reason": "sample reason"
}
],
"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": []
}
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 |
See Create quote's response field information.
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.
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 |
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 |
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.
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
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:
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.
When creating recipient, the following general rules should be applied to "accountHolderName" field:
_()'*,.
are allowed for personal and business names.[]%#^@&{}"~<>
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.
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 |
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 |
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.
GET https://api.sandbox.transferwise.tech/v1/accounts/{accountId}
Example Request:
curl -X GET https://api.sandbox.transferwise.tech/v1/accounts?profile=<profileId>¤cy=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.
GET https://api.sandbox.transferwise.tech/v1/accounts?profile=<profileId>¤cy=<currencyCode>
Both query parameters are optional.
Field | Description | Format |
---|---|---|
profileId | Personal or business profile id | Integer |
currency | Currency code | Text |
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).
DELETE https://api.sandbox.transferwise.tech/v1/accounts/{accountId}
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
}
]
}
]
},
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.
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
}
]
}
]
},
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.
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:
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.
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:
refreshRequirementsOnChange
.refreshRequirementsOnChange
.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 |
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
Validate Canadian bank account number
SEK Validate Bank Giro number
https://api.transferwise.com/v1/validators/bankgiro-number?bankgiroNumber=12345674
HUF
Validate Hungarian bank account number
PLN
Validate Polish bank account number
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
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
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>
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
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
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)
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
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.
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
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.
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)
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
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).
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.
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
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
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
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
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
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
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
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.
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.
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
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
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.
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
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.
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.
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
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
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.
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.
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
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
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.
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
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.
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
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.
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
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
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
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.
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
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.
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.
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
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:
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:
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",
"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.
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.
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
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.
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).
The transfer needs to be in INCOMING_PAYMENT_WAITING
state to trigger a webhook refund, so please refrain from using any of the transfer status change APIs above before this.
You only need to use this state if you are using a webhook based refund solution, which not all integrations require.
Transfer entity with changed status.
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.
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.
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.
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 |
This endpoint simulates a card transaction authorisation in the sandbox environment. It can simulate ATM withdrawals and purchasing transactions.
POST https://api.sandbox.transferwise.tech/v1/simulation/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/v1/simulation/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": "<card 16-digit PAN>",
"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
}
This endpoint simulates a clearing request in the sandbox environment.
POST https://api.sandbox.transferwise.tech/v1/simulation/spend/profiles/{profileId}/cards/{cardToken}/transactions/clearing
The ref
field should be set to the same value as reference
from authorisation response.
Example request
curl --location --request POST 'https://api.sandbox.transferwise.tech/v1/simulation/spend/profiles/{profileId}/cards/{cardToken}/transactions/clearing' \
--header 'Authorization: Bearer <your api token>'
--header 'Content-Type: application/json' \
--data '{
"amount": {
"value": <clearing amount>
"currency": "<ISO 4217 transaction currency code>"
},
"ref": {
"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": "<card 16-digit PAN>",
"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"
}
}'
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": "<card 16-digit PAN>",
"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
}
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.
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.
Terms and conditions in HTML format.
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.
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:
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 |
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 |
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.
Please refer to our Transfers section.
Please refer to our Transfer Fund section.
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.
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:
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 |
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.
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:
If you are unsure if you need this please contact your Wise implementation team to clarify.
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 |
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 |
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.
PUT https://api.sandbox.transferwise.tech/v1/transfers/{transferId}/cancel
Use transfer id that you obtained when creating a transfer.
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 |
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.
GET https://api.sandbox.transferwise.tech/v1/transfers/{transferId}
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 |
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.
GET https://api.sandbox.transferwise.tech/v1/delivery-estimates/{transferId}
Field | Description | Format |
---|---|---|
estimatedDeliveryDate | Estimated time when funds will arrive to recipient's bank account | Timestamp |
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.
GET https://api.sandbox.transferwise.tech/v1/transfers/{transferId}/receipt.pdf
Transfer confirmation receipt in PDF format.
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:
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 |
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 |
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.
POST https://api.sandbox.transferwise.tech/v1/transfer-requirements
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.
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.
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": <recipient account id>,
"quote": <quote id>,
"details": {
"reference": "good times",
"sourceOfFunds": "verification.source.of.funds.other",
"sourceOfFundsOther": "Trust funds"
},
"customerTransactionId": "6D9188CF-FA59-44C3-87A2-4506CE9C1EA3"
}
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 |
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.
GET https://api.sandbox.transferwise.tech/v1/users/{userId}
Field | Description | Format |
---|---|---|
id | userId | Integer |
name | User full name | Text |
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 |
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.
GET https://api.sandbox.transferwise.tech/v1/me
Field | Description | Format |
---|---|---|
id | userId | Integer |
name | User full name | Text |
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 |
- 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"
- Example Response: Get Client Credentials Token
{
"access_token":"ba8k1234-00f2-475a-60d8-6g45377b4062",
"token_type":"bearer",
"expires_in": 43199,
"scope":"transfers"
}
- 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"
}'
- Example Response: Create User (Success (200) user created successfully)
{
"id": 12345,
"name": null,
"email": "new.user@domain.com",
"active": true,
"details": null
}
- 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"
]
}
]
}
- 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>'
- 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."
}
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:
Obtain access_token based on your API client credentials.
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 |
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 |
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.
POST https://api.sandbox.transferwise.tech/v1/user/signup/registration_code
Use access_token obtained in first step as authentication header.
Field | Description | Format |
---|---|---|
New user's email address | ||
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 |
Field | Description | Format |
---|---|---|
id | userId | Integer |
name | User full name. Empty. | Text |
Customer email | Text | |
active | true | Boolean |
details | User details. Empty. | Group |
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.
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 |
New user's email address | ||
client_id | Your api_client_id | Text |
registration_code | registrationCode from step 2 | Text |
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 |
Pre-requisites:
The standard website redirection flow is as follows:
Your app redirects the user to Wise authorization web page.
The user logs in to Wise.
The user selects the profile and agrees to provide access.
Wise authorization page then redirects user back to your pre-configured redirect_uri, including an authorization code which should be used to generate user tokens. e.g. https://www.your_firm.com/transferwise-link-page/?code=[CODE]&profileID=123
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."
}
You can now use authorization code to obtain user access token and refresh token.
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 |
New user's email address | ||
client_id | Your api_client_id | Text |
code | authorization_Code | Text |
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 |
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 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:
443
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.
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 |
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 |
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"
}
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 |
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 |
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:
DELETE https://api.sandbox.transferwise.tech/v3/applications/{clientKey}/subscriptions/{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"
}
GET https://api.sandbox.transferwise.tech/v3/applications/{clientKey}/subscriptions/{id}
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"
}
POST https://api.sandbox.transferwise.tech/v3/applications/{clientKey}/subscriptions/{subscriptionId}/test-notifications
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 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>"
}
}
]
GET https://api.sandbox.transferwise.tech/v3/applications/{clientKey}/subscriptions
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:
443
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:
Create a profile subscription.
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"
}
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 |
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 |
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:
DELETE https://api.transferwise.com/v3/profiles/{profileId}/subscriptions/{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"
}
GET https://api.transferwise.com/v3/profiles/{profileId}/subscriptions/{id}
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>"
}
}
]
GET https://api.transferwise.com/v3/profiles/{profileId}/subscriptions
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.
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 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:
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.
X-Delivery-Id
Each outgoing notification is assigned a unique delivery UUID.
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.
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"
}
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 |
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 |
balances#update | not supported | 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 |
Event type: transfers#state-change
This event will be triggered every time a transfer's status is updated. Each event contains a timestamp.
As we do not guarantee the order of events, please use data.occurred_at
to reconcile the order.
If you would like to subscribe to transfer state change events, please use transfers#state-change
when creating your subscription.
Example v2.0.0
transfers#state-change
event:
{
"data": {
"resource": {
"type": "transfer",
"id": 111,
"profile_id": 222,
"account_id": 333
},
"current_state": "processing",
"previous_state": "incoming_payment_waiting",
"occurred_at": "2020-01-01T12:34:56Z"
},
"subscription_id": "01234567-89ab-cdef-0123-456789abcdef",
"event_type": "transfers#state-change",
"schema_version": "2.0.0",
"sent_at": "2020-01-01T12:34:56Z"
}
2.0.0
(latest)Field | Description | Format |
---|---|---|
data.resource.type | Transfer resource type (always transfer ) |
String |
data.resource.id | ID of the transfer | Integer |
data.resource.profile_id | ID of the profile that owns the transfer | Integer |
data.resource.account_id | ID of transfer's recipient account | Integer |
data.current_state | Current transfer state (see transfer statuses) | String |
data.previous_state | Previous transfer state (see transfer statuses) | String |
data.occurred_at | When the state change occurred | Datetime |
Event type: transfers#active-cases
This event will be triggered every time a transfer's list of active cases is updated. Active cases indicate potential problems with transfer processing.
If you would like to subscribe to transfer active cases events, please use transfers#active-cases
when creating
your subscription.
Example v2.0.0
transfers#active-cases
event:
{
"data": {
"resource": {
"type": "transfer",
"id": 111,
"profile_id": 222,
"account_id": 333
},
"active_cases": ["deposit_amount_less_invoice"]
},
"subscription_id": "01234567-89ab-cdef-0123-456789abcdef",
"event_type": "transfers#active-cases",
"schema_version": "2.0.0",
"sent_at": "2020-01-01T12:34:56Z"
}
2.0.0
(latest)Field | Description | Format |
---|---|---|
data.resource.type | Transfer resource type (always transfer ) |
String |
data.resource.id | ID of the transfer | Integer |
data.resource.profile_id | ID of the profile that owns the transfer | Integer |
data.resource.account_id | ID of transfer's recipient account | Integer |
data.active_cases | Ongoing issues related to the transfer | List of strings |
Event type: balances#credit
This event will be triggered every time a multi-currency account is credited.
If you would like to subscribe to balance credit events, please use balances#credit
when creating your subscription.
Please note: This event is not currently delivered to application subscriptions.
Example v2.0.0
balances#credit
event:
{
"data": {
"resource": {
"type": "balance-account",
"id": 111,
"profile_id": 222
},
"transaction_type": "credit",
"amount": 1.23,
"currency": "EUR",
"post_transaction_balance_amount": 2.34,
"occurred_at": "2020-01-01T12:34:56Z"
},
"subscription_id": "01234567-89ab-cdef-0123-456789abcdef",
"event_type": "balances#credit",
"schema_version": "2.0.0",
"sent_at": "2020-01-01T12:34:56Z"
}
Schema version 2.0.0
(latest)
Field | Description | Format |
---|---|---|
data.resource.type | Resource type (always balance-account ) |
String |
data.resource.id | ID of the account | Integer |
data.resource.profile_id | ID of the profile that owns the account | Integer |
data.transaction_type | Always credit |
String |
data.amount | Deposited amount | Decimal |
data.currency | Currency code | String |
data.post_transaction_balance_amount | Balance after the credit was applied | Decimal |
data.occurred_at | When the credit occurred | Datetime |
Event type: balances#update
This event will be triggered every time a multi-currency account is credited or debited.
If you would like to subscribe to balance update events, please use balances#update
when creating your subscription.
Please note: This event is only available for application subscriptions.
Example v2.0.0
balances#update
event:
{
"data": {
"resource": {
"id": 2,
"profile_id": 2,
"type": "balance-account"
},
"amount": 9.6,
"currency": "GBP",
"transaction_type": "debit",
"occurred_at": "2023-03-08T15:26:07Z",
"transfer_reference": "47500002"
},
"subscription_id": "f2264fe5-a0f5-4dab-a1b4-6faa87761425",
"event_type": "balances#update",
"schema_version": "2.0.0",
"sent_at": "2023-03-08T15:26:07Z"
}
{
"data": {
"resource": {
"id": 2,
"profile_id": 2,
"type": "balance-account"
},
"amount": 70,
"currency": "GBP",
"transaction_type": "credit",
"occurred_at": "2023-03-08T14:55:38Z",
"transfer_reference": "BNK-1234567"
},
"subscription_id": "f2264fe5-a0f5-4dab-a1b4-6faa87761425",
"event_type": "balances#update",
"schema_version": "2.0.0",
"sent_at": "2023-03-08T14:55:39Z"
}
Schema version 2.0.0
(latest)
Field | Description | Format |
---|---|---|
data.resource.type | Resource type (always balance-account ) |
String |
data.resource.id | ID of the account | Integer |
data.resource.profile_id | ID of the profile that owns the account | Integer |
data.transaction_type | Either credit or debit |
String |
data.amount | Transaction amount | Decimal |
data.currency | Currency code | String |
data.transfer_reference | Link to the original transfer | String |
data.occurred_at | When the transaction occurred | Datetime |
Event type: profiles#verification-state-change
This event will be triggered when the verification state of a connected profile changes.
A profile's verification state can be verified
or not_verified
.
If the state is verified
, then the user is ready to make payments using Wise.
If the state is not_verified
, then we advise not to initiate any transfers with the user's access token as the
payments will not be processed until the verification is completed.
There is a more in-depth discussion of verification state in our Connected Apps Integration Guide.
Please note: This event is currently delivered only to application subscriptions.
If you would like to subscribe to verification state change events, please use profiles#verification-state-change
when creating your subscription.
Example v2.0.0
profiles#verification-state-change
event:
{
"data": {
"resource": {
"type": "profile",
"id": 111
},
"current_state": "verified",
"occurred_at": "2020-01-01T12:34:56Z"
},
"subscription_id": "01234567-89ab-cdef-0123-456789abcdef",
"event_type": "profiles#verification-state-change",
"schema_version": "2.0.0",
"sent_at": "2020-01-01T12:34:56Z"
}
Schema version 2.0.0
(latest)
Field | Description | Format |
---|---|---|
data.resource.type | Profile resource type (always profile ) |
String |
data.resource.id | ID of the profile | Integer |
data.current_state | Current verification state of the profile (see discussion above) | String |
data.occurred_at | When the verification state change occurred | Datetime |
Event type: batch-payment-initiations#state-change
This event will be triggered when the payment initiation state of a batch group payment changes.
The expected state of a batch payment initiation can be one of: NEW
, PROCESSING
, COMPLETED
, FAILED
, CHARGED_BACK
.
If you would like to subscribe to batch payment initiation state change events, please use batch-payment-initiations#state-change
when creating your subscription.
Example v2.0.0
batch-payment-initiations#state-change
event:
{
"data": {
"resource": {
"id": 12345,
"batchGroupId": "068e186d-9632-4937-b753-af3e53f4d0b0",
"profileId": 2
},
"previousStatus": "NEW",
"newStatus": "PROCESSING",
"occurredAt": "2021-04-13T19:51:41.423404Z" ,
"returnCode": "200"
},
"subscription_id": "01234567-89ab-cdef-0123-456789abcdef",
"event_type": "batch-payment-initiations#state-change",
"schema_version": "2.0.0",
"sent_at": "2020-01-01T12:34:56Z"
}
Schema version 2.0.0
(latest)
Field | Description | Format |
---|---|---|
data.resource.id | Payment initiation ID | Number |
data.resource.batchGroupId | Batch group ID | Text |
data.resource.profileId | The ID of the profile this payment belongs to | Number |
data.previousStatus | Previous payment initiation state | Text |
data.currentStatus | Current payment initiation state | Text |
data.occurredAt | When the payment initiation state change occurred | Timestamp |
data.returnCode | Return code of the underlying payment system | Text |
Event type: transfers#payout-failure
This event will be triggered every time a payout fails. The event can be used to get further information about a failed payment.
transfers#state-change
event provides high level information about the state of transfers. But it doesn't provide details about payout failures.
While the transfers#state-change
event is in outgoing_payment_sent
state, the payout could fail for certain reasons listed below.
Using this event, you can understand the reason behind the failure and even ask your customers to fix the problem by themselves. If the failure reason code is WRONG_ACCOUNT_NUMBER
for example.
Please note that not every payout failure will trigger a transfers#state-change
. For example a payout might fail with MANDATE_NOT_FILLED_IN
code but the corresponding transfer might stay in the same state.
We recommend to process both event types(transfers#payout-failure
and transfers#state-change
) separate from each other.
If you would like to subscribe to payout failure events, please use transfers#payout-failure
when creating your subscription.
Example v2.0.0
transfers#payout-failure
event:
{
"data": {
"transfer_id": 111,
"failure_reason_code": "WRONG_ID_NUMBER",
"failure_description": "Invalid recipient's ID document number",
"occurred_at": "2020-01-01T12:34:56Z"
},
"subscription_id": "01234567-89ab-cdef-0123-456789abcdef",
"event_type": "transfers#payout-failure",
"schema_version": "2.0.0",
"occured_at": "2020-01-01T12:34:56Z"
}
2.0.0
(latest)Field | Description | Format |
---|---|---|
data.transfer_id | ID of the transfer | Integer |
data.failure_reason_code | Code of the failure error | String |
data.failure_description | Description of the failure code | String |
data.occurred_at | When the state change occurred | Datetime |
Code | Description |
---|---|
ACCOUNT_CLOSED | The recipient details are correct, but beneficiary account is closed |
ACCOUNT_FROZEN | The recipient details are correct, but beneficiary account is frozen |
ACCOUNT_BLOCKED | The recipient details are correct, but beneficiary account is blocked |
ACCOUNT_LIMIT_REACHED | The recipient details are correct, but beneficiary account has a limit that can be unblocked by the recipient |
WRONG_ACCOUNT_NUMBER | Invalid account number |
WRONG_CARD_NUMBER | Invalid card number |
WRONG_ACCOUNT_DETAILS | Invalid account number AND/OR invalid bank code |
WRONG_ACCOUNT_TYPE | Incorrect account type |
WRONG_BANK_CODE | Invalid sort/BIC/routing/etc number |
WRONG_BRANCH_CODE | Invalid branch code |
WRONG_NAME | Account number matches, but the name is not 100% correct |
WRONG_PHONE_NUMBER | Recipient phone number is incorrect |
WRONG_ID_NUMBER | Invalid recipient's ID document number |
WRONG_RUT_NUMBER | Invalid recipient's RUT (Rol Único Tributario) number |
TAX_ID_NOT_MATCHING | Tax ID doesn't match recipient's name |
TAX_ID_SUSPENDED | Tax ID is suspended |
WRONG_REFERENCE | Invalid payment reference |
WRONG_PAYMENT_PURPOSE | Invalid or not accepted payment purpose |
ACCOUNT_DOES_NOT_EXIST | Format is correct but this account does not exist in recipient bank |
WRONG_CURRENCY | Recipient account is in different currency |
WRONG_CARD_TYPE | Recipient account doesn't support payments to this card type |
CANNOT_ACCEPT_FROM_3RD_PARTY | Recipient bank can't accept the payments from 3rd party |
CREDITING_ACCOUNT_FORBIDDEN | Terms and Conditions of Account do not permit crediting of these funds |
DUPLICATE_ENTRY | Recipient bank informs that there has been another payment in the same amount |
FUNDS_NOT_EXPECTED_RETURNED | Beneficiary not expecting funds/instructed return |
MANDATE_NOT_FILLED_IN | Recipient didn't fill out the mandate form on time or the email address is incorrect |
BUSINESS_PAYMENTS_FORBIDDEN | Payment to business accounts are not allowed |
DUPLICATE_ENTRY | Recipient bank informs that there has been another payment in the same amount |
REASON_NOT_SPECIFIED | Reason not specified |
Wise could add new failure codes to this list and your system should be able to handle the events even if the failure reason code is not recognised.
Event type: swift-in#credit
This event will be triggered every time a SWIFT message is received and deposited into a balance account.
Please note: It is recommended that you do not subscribe to balances#credit
or transfers#state-change
on the same profile to avoid duplication of webhook details.
Example
swift-in#credit
event:
{
"data": {
"action": {
"type": "credit",
"id": 12345,
"profile_id": 222,
"account_id": 333
},
"resource": {
"id": "55555",
"type": "103",
"message": "
{1:F21TRWIGB22AXXX123456789}{4:{177:0123456789}{451:0}}{1:F01TRWIGB22AXXX12345678}{2:O1030727211112LHVBEE22AXXX15007123456789912345WN}{3:{108:ASW86540/12112FA}{119:STP}{111:001}{121:f875814b-7d44-4d1b-a499-123456789abcde}}{4:
:20:ASW86540/123456
:23B:CRED
:26T:K90
:32A:211112EUR3,54
:33B:EUR3,54
:50F:/EE947700771111111111
1/SMITH#JOHN
2/EVERGREEN STREET, 10
3/BE/BRUSSELS
4/12345678
:52A:ZYABEE20
:57A:AGRNMD2XXXX
:59F:/BE1234567891234
1/SMITH#JOHN
2/EVERGREEN AVE, 6
3/BE/BRUSSELS
:70:/RFB/BET072
:70:/INV/abc/SDF-96//1234-234///ROC/98I
U87
:70:/TSU/00000089963-0820-01/ABC-15/256
214,
:71A:SHA
-}
"
}
"occurred_at": "2020-01-01T12:34:56Z"
},
"subscription_id": "01234567-89ab-cdef-0123-456789abcdef",
"event_type": "swift-in#credit",
"schema_version": "2.0.0",
"sent_at": "2020-01-01T12:34:56Z"
}
Schema version 2.0.0
(latest)
Field | Description | Format |
---|---|---|
data.action.type | Type of action (always credit ) |
String |
data.action.id | TransferID of the credit | Integer |
data.action.profile_id | ProfileID for the transfer | Integer |
data.action.account_id | AccountID for the transfer | Integer |
data.resource.type | SWIFT message type | String |
data.resource.id | ID of webhook | Integer |
data.resource.message | Complete SWIFT Message as received | String |
data.occurred_at | When the credit occurred | Datetime |
Event type: cards#transaction-state-change
This event will be triggered every time a new card transaction is made or the transaction state changes.
Example
cards#transaction-state-change
event:
{
"data": {
"resource": {
"profile_id": 14547571,
"client_id": "tw-test-connected-apps",
"card_token": "590b5b72-223d-45f9-b840-0ad4a4f80937",
"card_last_digits": "3086",
"type": "card"
},
"transaction_id": 342672,
"transaction_type": "ECOM_PURCHASE",
"decline_reason": null,
"transaction_state": "IN_PROGRESS",
"transaction_amount": {
"value": 1.5,
"currency": "SGD"
},
"fees": [],
"transaction_amount_with_fees": {
"value": 1.5,
"currency": "SGD"
},
"authorisation_method": "MANUAL_ENTRY",
"balance_transaction_id": 2598421,
"debits": [
{
"balance_id": 52832,
"debited_amount": {
"value": 1.06,
"currency": "EUR"
},
"for_amount": {
"value": 1.5,
"currency": "SGD"
},
"rate": 1.43144,
"fee": {
"value": 0.01,
"currency": "EUR"
}
}
],
"occurred_at": "2022-11-28T08:23:57Z"
},
"subscription_id": "91ab6a71-f282-4239-b276-d7d7324e5769",
"event_type": "cards#transaction-state-change",
"schema_version": "2.0.0",
"sent_at": "2022-11-28T08:23:58Z"
}
Schema version 2.0.0
(latest)
Field | Description | Format |
---|---|---|
data.resource.profile_id | ID of the profile that owns the card | Integer |
data.resource.client_id | Your api_client_id | String |
data.resource.card_token | Unique identifier of the card | String |
data.resource.card_last_digits | The last four digits of the card | String |
data.resource.type | Resource type (always card ) |
String |
data.transaction_id | ID of the transaction | Integer |
data.transaction_type | Type of the transaction | String |
data.decline_reason | Code of the decline reason if applicable | String |
data.transaction_state | The current state of the transaction | String |
data.transaction_amount.value | Transaction amount | Decimal |
data.transaction_amount.currency | Currency code | String |
data.fees[0].amount | Fee amount | Decimal |
data.fees[0].currency | Currency code | String |
data.fees[0].fee_type | Fee type | String |
data.transaction_amount_with_fees.value | Transaction amount including fees | Decimal |
data.transaction_amount_with_fees.currency | Currency code | String |
data.authorisation_method | Authorisation method | String |
data.balance_transaction_id | Balance transaction ID | Integer |
data.debits.balance_id | ID of balance that is debited | Integer |
data.debits.debited_amount | Amount debited from balance | Decimal/String |
data.debits.for_amount | Transaction amount debited | Decimal/String |
data.debits.rate | Conversion rate used | Decimal |
data.debits.fee | Conversion fee debited | Decimal/String |
data.occurred_at | When transaction or transaction state change occurred | Datetime |
Code | Description |
---|---|
IN_PROGRESS | The transaction is still in progress |
COMPLETED | The transaction is completed |
DECLINED | The transaction has been declined |
CANCELLED | The transaction has been cancelled |
UNKNOWN | Default fallback status |
Code | Description |
---|---|
ATM_WITHDRAWAL | Fee charged by Wise |
ATM_MACHINE | Fee charged by the ATM owner |
You can use profile webhooks or application webhooks instead.
Example Request:
curl -X GET https://api.sandbox.transferwise.tech/v1/subscriptions?channelId=webhook \
-H "Authorization: Bearer <your api token>"
Example Response:
[
{
"id": "abcde123-abcd-abcd-abcd-abcde1234567",
"name": "Webhook Subscription #1",
"channel_id": "WEBHOOK",
"user_id": "TW::<your user ID>",
"status": "ENABLED",
"created_on": "2019-03-10T09:32:15.663Z",
"url": "<URL of your server>",
"profile_id": <ID of the profile you want to receive notifications from>,
"enabled_notifications": [
"balance"
]
},
{
"id": "abcde123-abcd-abcd-abcd-abcde1234568",
"name": "Webhook Subscription #2",
"channel_id": "WEBHOOK",
"user_id": "TW::<your user ID>",
"status": "ENABLED",
"created_on": "2019-03-11T09:32:15.663Z",
"url": "<URL of your server>",
"profile_id": <ID of the profile you want to receive notifications from>,
"enabled_notifications": [
"transfers"
]
}
]
List all created webhook subscriptions.
Field | Description | Format |
---|---|---|
id | Subscription ID | Text |
name | Custom name of your webhook | String |
channel_id | ID of the channel through which you're receiving notifications, always equal to WEBHOOK |
String |
user_id | Your user ID | Integer |
status | Status of the subscription | String |
created_on | Timestamp when subscription was created | Timestamp |
url | URL of your server | String |
profile_id | ID of the profile you want to receive notifications from | Integer |
enabled_notifications | List of resources you would like to receive notifications about | [String] |
Example Request:
curl -X GET https://api.sandbox.transferwise.tech/v1/subscriptions/{subscriptionId}/ \
-H "Authorization: Bearer <your api token>"
Example Response:
{
"id": "abcde123-abcd-abcd-abcd-abcde1234567",
"name": "Webhook Subscription #1",
"channel_id": "WEBHOOK",
"user_id": "TW::<your user ID>",
"status": "ENABLED",
"created_on": "2019-03-10T09:32:15.663Z",
"url": "<URL of your server>",
"profile_id": <ID of the profile you want to receive notifications from>,
"enabled_notifications": [
"balance",
"transfers"
]
}
Get subscription information by ID.
Field | Description | Format |
---|---|---|
id | Subscription ID | Text |
name | Custom name of your webhook | String |
channel_id | ID of the channel through which you're receiving notifications, always equal to WEBHOOK |
String |
user_id | Your user ID | Integer |
status | Status of the subscription | String |
created_on | Timestamp when subscription was created | Date |
url | URL of your server | String |
profile_id | ID of the profile you want to receive notifications from | Integer |
enabled_notifications | List of resources you would like to receive notifications about | [String] |
Example Request:
curl -X DELETE https://api.sandbox.transferwise.tech/v1/subscriptions/{subscriptionId}/ \
-H "Authorization: Bearer <your api token>"
Example Response:
{
}
Delete a subscription.
Events are messages that will be sent to your server as HTTP POST
requests.
They will not contain any personally identifiable information.
To acknowledge that you have successfully processed an event, make sure your server answers with a 2xx
-series HTTP status
code within 5 seconds. Otherwise, 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.
Wise public key for production environment:
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvO8vXV+JksBzZAY6GhSO
XdoTCfhXaaiZ+qAbtaDBiu2AGkGVpmEygFmWP4Li9m5+Ni85BhVvZOodM9epgW3F
bA5Q1SexvAF1PPjX4JpMstak/QhAgl1qMSqEevL8cmUeTgcMuVWCJmlge9h7B1CS
D4rtlimGZozG39rUBDg6Qt2K+P4wBfLblL0k4C4YUdLnpGYEDIth+i8XsRpFlogx
CAFyH9+knYsDbR43UJ9shtc42Ybd40Afihj8KnYKXzchyQ42aC8aZ/h5hyZ28yVy
Oj3Vos0VdBIs/gAyJ/4yyQFCXYte64I7ssrlbGRaco4nKF3HmaNhxwyKyJafz19e
HwIDAQAB
How to verify signatures (in Java):
public boolean verifySignature(String encodedPublicKey, String signature, String payload) {
X509EncodedKeySpec publicKeySpec = new X509EncodedKeySpec(Base64.getMimeDecoder().decode(encodedPublicKey));
KeyFactory keyFactory = KeyFactory.getInstance("RSA");
PublicKey publicKey = keyFactory.generatePublic(publicKeySpec);
Signature sign = Signature.getInstance("SHA256WithRSA");
sign.initVerify(publicKey);
sign.update(payload.getBytes());
byte[] signatureBytes = Base64.getDecoder().decode(signature);
return sign.verify(signatureBytes);
}
Each outgoing webhook request is signed. Whilst event payloads do not contain any sensitive information, you may want to verify if the request is coming from Wise (however this is optional). We advise you not to process any requests where signature appears to be forged.
Each POST
request includes X-Signature
header, which contains a signature.
Example Request:
curl -X POST https://api.sandbox.transferwise.tech/v1/webhooks/ping \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '{
"callback_url": "<URL of your server>"
}'
Example Response:
{
"status": "SUCCESS",
"code": 200,
"elapsed": 228
}
You can trigger a test event to be delivered to your server to check the connection between systems.
Field | Description | Format |
---|---|---|
callback_url | URL of your server | String |
Field | Description | Format |
---|---|---|
status | Status of test notification delivery | String |
code | HTTP status code we have received from your server | Integer |
elapsed | Time taken to deliver notification, in ms | Integer |
Example event:
{
"subscriptionId": "abcde123-abcd-abcd-abcd-abcde1234567",
"profileId": 123456,
"resourceId": {transferId},
"newState": "outgoing_payment_sent",
"eventTime": 1481713589566
}
Event will be triggered every time transfer status is updated. Each event contains a timestamp. As we do not guarantee the order of events, please use that eventTime
to reconcile the order.
Field | Description | Format |
---|---|---|
subscriptionId | ID of subscription that triggers this notification | String |
profileId | ID of the profile that owns the resource | Integer |
resourceId | ID of the resource that got updated | Integer |
newState | New status of the resource, possible values are same as transfer statuses | String |
eventTime | Timestamp when update happened | Timestamp |
Example event:
{
"subscriptionId": "abcde123-abcd-abcd-abcd-abcde1234567",
"profileId": 123456,
"amount": 1000,
"currency": "GBP",
"eventType": "balance-deposit-received"
}
Event will be triggered every time a multi-currency account is credited.
Field | Description | Format |
---|---|---|
subscriptionId | ID of subscription that triggers this notification | String |
profileId | ID of the profile that owns the multi-currency account | Integer |
amount | Deposit amount | Decimal |
currency | Currency that was updated | String |
eventType | Type of update | String |
Strong Customer Authentication (SCA) is a new European regulatory requirement as part of the second Payment Services Directive (PSD2) for authenticating online payments and make them more secure.
There are some actions such as funding a transfer from your multi-currency account or viewing the statement that require SCA within the UK and EEA. SCA builds additional authentication by asking two of the following three elements: something the customer knows, something the customer has and something the customer is. If you don't integrate with it and make a request to an SCA protected endpoint, your request will be rejected.
Following those regulations, we need our API to be more secured by ensuring multi-factor authentication from the end-user of the Wise account. Two mechanisms are in place depending on the product you are using:
When making a request to an SCA protected endpoint, a 403 Forbidden HTTP status code is returned together with a one-time token (OTT) value which needs to be signed and the resulting signature included in the retry of the original request.
Below is a sequence diagram showing this flow.
We use a digital signature scheme based on public-key cryptography. It involves creating a signature using a private key on the client side and verifying the signature authenticity on the server side using the corresponding public key the client has uploaded.
To call the endpoints requiring additional authentication:
Creating the key pair
Keys can be generated with the OpenSSL toolkit:
$ openssl genrsa -out private.pem 2048
$ openssl rsa -pubout -in private.pem -out public.pem
The following requirements apply:
.pem
file extensionManaging uploaded public keys
The public keys management page can be accessed via the "Manage public keys" button under the API tokens section of your Wise account settings.
You will be prompted to perform 2FA when uploading new public keys.
The maximum number of public keys you can store is limited to 5.
Signing the data
We will only accept the signatures created with SHA256 with RSA (SHA256 hash of the data is signed with RSA) algorithm. There are different ways of creating the required digital signature, for example:
The shell one-liner to sign a string, encode it with Base64 and print to standard output:
$ printf '<string to sign>' | openssl sha256 -sign <path to private key.pem> | base64 -w 0
OpenSSL
The CLI toolkit command is openssl sha256 -sign private.pem data.bin
(consult the openssl man pages for additional info if required).
Note that the signature returned by OpenSSL (to standard output in the example above) is in a binary format and to
send it over HTTP it should be encoded to Base64 (RFC 4648)).
There is also an extensive C API available.
Detailed workflow
Here is a step-by-step workflow with example commands (which may vary slightly depending on the exact versions of utilities used).
$ curl -i -X POST 'https://api.sandbox.transferwise.tech/v3/profiles/{profileId}/transfers/{transferId}/payments' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your api token>' \
-d '{"type": "BALANCE"}'
HTTP/1.1 403 Forbidden
Date: Fri, 03 Jan 2020 12:34:56 GMT
Content-Type: application/json;charset=UTF-8
x-2fa-approval-result: REJECTED
x-2fa-approval: be2f6579-9426-480b-9cb7-d8f1116cc8b9
...
{
"timestamp": "2020-01-03T12:34:56.789+0000",
"status": 403,
"error": "Forbidden",
"message": "You are forbidden to send this request",
"path": "/v3/profiles/{profileId}/transfers/{transferId}/payments"
}
403 / Forbidden
with the following response headers
X-2FA-Approval-Result
: REJECTED
X-2FA-Approval
containing the one-time token (OTT) value which is what needs to be signed$ printf 'be2f6579-9426-480b-9cb7-d8f1116cc8b9' | openssl sha256 -sign private.pem | base64 -w 0
1ZCN1MIDdmonOJvNQvsCxRHMXihsqZ/xNvybhb3oYNQgRkyj2P0hCVVaWUbr313LicFGwRTW8kcxTwvpXQdeurGtcN2zGoweVTopI06dmJ8vQMfTkrqjMZG3UUX0EcU+tJaDlBemvS7gv2aNGyHDMiRPZOZRPA6TH0LPJvLdVRMsEbXrbj8HqEopczmf1jChRxftmg2XoeQUMhhlOiSjSbJmlyAIegioI40/BTii+Q7f/HWZqk6N2vmHWPomwHQMz8Hy6frLYJb5tchjg/i+RRvZjEVbUH53QfG8Tbmx4JM/wN1LYeR8rebSdGEpLOd8QRcjuDur54qHNWXvKRM8aQ==
with
private.pem
private key:
-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEA3qfjPkhbTPKJQqLm+KfHP14wJ2U318Rh/4TV8xLi605xFW7r
ApzXzLLxBb7zSkBc9wFIEH7wU7/BaFivg440R7ktYR07/QXZi+i0grKbfhEBW1nU
jkI2eZxT3vE4VIK7Yt2jr84JiCYmjL2b/w1DatXZM9Xoa3j9YHda5cKLOfCCIeTs
I3beYI9UmSnidYaXpX7q4gfHME+A/1F/19L8jFvX+c7MXapdCdY/NUHXBCJFfBzg
OBlXbPKhdjtEnx+Hg5Sq/Frsld6dKwF1CDMO96YoeXBdi58JkLL/CLyy1i7UcXTb
SRy0Gbd3NWSAamWdpJDDg51UR6yRJdXjtnhpdQIDAQABAoIBAGs3/4bzgvvH428y
UPU2ng0WxyuBY2XEzMgl6H04AAv95xjCI+tLKeQJ22S/8ho0alALzu8aoZJCydj8
s/Au32AWfRLB6CxMz9i+w4YYiiYn/DZISMIEgoUHUaAPGugfWCsgvf0fw5lLfc7S
U7d7ZJaiyghbHqP6TFFSyHPRvge0so+8eRvPMxIGdfJR3gagJqKB5JbTGAnQ5Kn2
eb5flDOobmCfpLDfIYH9u94Yj671xymtNYXwWxic4gA+aqWJKaqkI8JL7bFdjvjn
Jer5RHeXmY9UZtDhSrZWSEKniw3m02QPpgqhhhPr8xToNA/7G1/P9994fuDKKnRk
edn3FEECgYEA8iTPuaNGswyx/3zCkOPHHu82CSoWRZQapegN0YoXKsCyEWcHgQJV
jZlF39OK14+y4PWWPJ3AlkhrchAJbUbgpw0P+G1uiRmXVpqcaEI4xIFd8oSOG+Vr
s06YZYUrb7C73mi8x3sXdOpmehMYdnSbuxrRXyk0MwpLO2PkC0wXzEUCgYEA62WY
RuZMAHR4PEZA+sDBG6XzjZGw1QQvF7H6u+JOfgPbRgZ+NnLQ/ZpYiDvrJGqAp1B1
NIj69zVBN0p7PuRg2v9I4tHlmWC4eyYnVCf3dM6Fhsyb7RC3MHXVNOErxRoHVNqL
4iywSUnboJyvdyKc7S5wQ5gdM14HogD/i1FHs3ECgYBMuMcsfYRgJOydE82eFN25
ene3jaNC5ntPB+ig9M0EWcvR4cAp6zBqTh8qnR9Hz5sQ1h+FE0K7GzUYDea+vg9e
PrBJuXqla/tckF5wVlMgSBEZT1CrnBR02rlEqV4q5GeSP8NYvTKgc8iGc1hz59yT
+xpNuYN1jJRru+m8fp6ntQKBgQDd7Iglv5TDkQqR+MHmJbdpM4lsXIBUM3+aXUc/
vtm1YDlnyVNQTerOTKdOuP609FuaYfY9sy63xVNYpzWOU40kqiyy+qP1eAQ0xgGq
C4v2aYXlUh1m4K10WILLOcYkKqfiza+3ad5BGgqfX1jlfpJn4bIhZ9WPygR0LXC+
jcCFYQKBgQCelF/LIocwZ1ZW/Cx2OqMi/lkI56nLeBl7jRNiBSNIs0deN0cw4sHp
BN9459NojAKBKJK1pyqajzrHae66V+8/2Zz2/gmTK1dDjznyw6TZmV3QyHTFhUtY
NI7wvIG9K8gFaoSiGD/OLlLRaGiAdejKBsBx2hK73M58YQsgqIpdIQ==
-----END RSA PRIVATE KEY-----
$ curl -i -X POST 'https://api.sandbox.transferwise.tech/v3/profiles/{profileId}/transfers/{transferId}/payments' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your api token>' \
-H 'x-2fa-approval: be2f6579-9426-480b-9cb7-d8f1116cc8b9' \
-H 'X-Signature: RjXBO5SpAuMGdgTyqPryOt8AyIKY0t5gHqj36MzR2UwH9SvSY1V1wKIQCqXRvLMLyWBGXDkLvv9JdAni+H87k3hsClRiyfpdzcg3uOP+d/jSagNDSjHixPh4/rWQh+eEhBRo4V+pPBH+r5APtIwFY/fvvdMbZ/QnnmcPHxi/t7uS7+qvRZCC17q47T0ZpSwEK9x+nG/wcJ4S4Yrk0E2yQlLz8F35C+E2gt/KGTt6Tf5z6GonM1H2gJWoHpxuOUomh09b/k3teLjIfEirWmnO2XuOe0oDCUH8i10dokzk+QrM4t/Yv/Rb18JvTeugDAKMydGo7KTgqKGCXZauicX0Ew==' \
-d '{"type": "BALANCE"}'
X-2FA-Approval
request header and the signed OTT in the X-Signature
request header.HTTP/1.1 200 OK
Date: Fri, 03 Jan 2020 12:34:56 GMT
Content-Type: application/json;charset=UTF-8
x-2fa-approval-result: APPROVED
{
"type": "BALANCE",
"status": "COMPLETED",
"errorCode": null
}
x-2fa-approval-result
status APPROVED
in headers.If you use the authorization code integration to integrate with our API, then this is the right place.
When making a request to an SCA protected endpoint, a 403 Forbidden HTTP status code is returned together with a one-time token (OTT). Your customer will now expect to authenticate themselves by entering their Wise password as well as an OTP code. Our library was created by our team to make your integration easier.
Below is a sequence diagram showing this flow.
Here is a step-by-step workflow with example commands to process a payment (which may vary slightly depending on the exact versions of utilities used).
import { create, Mode } from '@transferwise/approve-api-action-helpers';
...
const request = create({ mode: Mode.PRODUCTION });
const res = await request('/tw-fund-payment', { method: 'POST', data: { ... } });
$ curl -i -X POST 'https://api.sandbox.transferwise.tech/v3/profiles/{profileId}/transfers/{transferId}/payments' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your api token>' \
-d '{"type": "BALANCE"}'
HTTP/1.1 403 Forbidden
Date: Fri, 03 Jan 2020 12:34:56 GMT
Content-Type: application/json;charset=UTF-8
x-2fa-approval-result: REJECTED
x-2fa-approval: be2f6579-9426-480b-9cb7-d8f1116cc8b9
...
{
"timestamp": "2020-01-03T12:34:56.789+0000",
"status": 403,
"error": "Forbidden",
"message": "You are forbidden to send this request",
"path": "/v3/profiles/{profileId}/transfers/{transferId}/payments"
}
403 / Forbidden
with the following response headersx-2fa-approval-result
: REJECTED
x-2fa-approval
containing the one-time token (OTT) valueYour server reflects the response status and the header x-2fa-approval
back to your frontend.
Our frontend library now understands that SCA is required and asks the customer to pass challenges (such as password).
When customer has completed challenges, our frontend library automatically triggers the initial call (1) again, but this time it includes the OTT (x-2fa-approval
header) and sends it to your backend.
$ curl -i -X POST 'https://api.sandbox.transferwise.tech/v3/profiles/{profileId}/transfers/{transferId}/payments' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your api token>' \
-H 'x-2fa-approval: be2f6579-9426-480b-9cb7-d8f1116cc8b9' \
-d '{"type": "BALANCE"}'
HTTP/1.1 200 OK
Date: Fri, 03 Jan 2020 12:34:56 GMT
Content-Type: application/json;charset=UTF-8
x-2fa-approval-result: APPROVED
{
"type": "BALANCE",
"status": "COMPLETED",
"errorCode": null
}
x-2fa-approval-result
status APPROVED
in headers.We use common HTTP status codes included in the response header to indicate success or failure.
Code | Description |
---|---|
200 | OK. Successful request. |
201 | OK. Resource created. |
400 | Bad request. Request message data did not pass validation. |
401 | Unauthorised. Not authorised to access requested data. |
403 | Forbidden. Access to requested data is forbidden. |
404 | Not Found. Requested resource does not exist. |
408 | Timeout. Operation timed out. |
422 | Unprocessable entity. Request message data did not pass validation. |
500 | Server error. |
Example Validation Error:
{
"errors": [
{
"code": "error.route.not.supported",
"message": "This route is not supported",
"arguments": [
"CNY-EUR"
]
}
]
}
Data validation or violation of business rules related errors. Response could contain multiple errors.
Example Authentication Error:
{
"error": "unauthorized",
"error_description": "Full authentication is required to access this resource"
}
Security related errors.
Example System Error:
{
"timestamp": "2017-02-02T13:07:39.644+0000",
"status": 500,
"error": "Internal Server Error",
"exception": "java.lang.NullPointerException",
"message": "No message available",
"path": "/v1/quotes/0b63b0cb-2041-4bc4-b3fc-1e51a1454a1b/account-requirements"
}
Something went wrong in our side.