Recipient Account

These endpoints use a mixture of our v1 and v2 api - please ensure you address the right version to get the expected results. All recipient IDs are cross compatible with v1 and v2.

The Recipient Account resource V1

Fields
idinteger

accountId

profileinteger

Personal or business profile id. It is highly advised to pass the business profile id in this field if your business account is managed by multiple users so that the recipient can be accessed by all users authorized on the business account.

userinteger

User that created or owns this recipient

acccountHolderNametext

Recipient full name

currencytext

3 character country code

countrytext

2 character currency code

typetext

Recipient type

ownedByCustomertext

Whether this account is owned by the sending user. Only include and set to true if the sender is also the recipient (eg when paying themselves). Other personal details will be ignored.

detailsobject

Currency specific fields

details.legalTypetext

Recipient legal type

details.sortCodetext

Recipient bank sort code (GBP example)

details.accountNumbertext

Recipient bank account no (GBP example)

Recipient Account Object
{
"id": 13967081,
"business": null,
"profile": 33333333,
"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": 22222222,
"active": true,
"ownedByCustomer": true
}

The Recipient Account resource V2

Fields
idinteger

Id of the recipient

creatorIdinteger

Account entity that owns the recipient account

profileIdinteger

Specific profile that owns the recipient account

nameobject

Recipient name details

name.fullNametext

Recipient full name

name.givenNametext

Recipient first name

name.familyNametext

Recipient surname

name.middleNametext

Recipient middle name

currencytext

3 character currency code

countrytext

2 character country code

typetext

Recipient type

legalEntityTypetext

Entity type of recipient

statusboolean

Status of the recipient

detailstext

Account details

details.referencetext

Recipient reference (GBP example)

details.sortCodetext

Recipient bank sort code (GBP example)

details.accountNumbertext

Recipient bank account no (GBP example)

details.hashedByLooseHashAlgorithmtext

Recipient account hash

commonFieldMapobject

Map of key lookup fields on the account

commonFieldMap.bankCodeFieldtext

Bank sort code identifier field

hashtext

Account hash for change tracking

accountSummarytext

Summary of account details for ease of lookup

accountSummarytext

Summary of account details for ease of lookup

longAccountSummarytext

Account details summary

displayFieldsobject

Lookup fields

displayFields.keyobject

Account identifier key name

displayFields.labelobject

Account identifier display label

displayFields.valueobject

Account identifier value

ownedByCustomerboolean

If recipient account belongs to profile owner

Recipient Account Object
{
"id": 391559914,
"creatorId": 89062778,
"profileId": 37765245,
"name": {
"fullName": "John Doe",
"givenName": null,
"familyName": null,
"middleName": null,
"patronymicName": null,
"cannotHavePatronymicName": null
},
"currency": "GBP",
"country": "GB",
"type": "SortCode",
"legalEntityType": "PERSON",
"active": true,
"details": {
"reference": null,
"accountNumber": "37778842",
"sortCode": "040075",
"hashedByLooseHashAlgorithm": "ad245621b974efa3ef870895c3wer419a3f01af18a8a5790b47645dba6304194"
},
"commonFieldMap": {
"accountNumberField": "accountNumber",
"bankCodeField": "sortCode"
},
"hash": "666ef880f8aa6113fa112ba6531d3ed2c26dd9fgbd7de5136bfb827a6e800479",
"accountSummary": "(04-00-75) 37778842",
"longAccountSummary": "GBP account ending in 8842",
"displayFields": [
{
"key": "details/sortCode",
"label": "UK sort code",
"value": "04-00-75"
},
{
"key": "details/accountNumber",
"label": "Account number",
"value": "37778842"
}
],
"isInternal": false,
"ownedByCustomer": false
}

Create a recipient account

Recipient is a person or institution who is the ultimate beneficiary of your payment.

Recipient data includes three data blocks.

1) General Data

  • Recipient full name
  • Legal type (private/business)
  • Currency
  • Owned by customer

Owned by customer is an optional boolean to flag to record whether this recipient is the same entity (person or business) as the one sending the funds. i.e. A user sending money to their own bank account in another country/currency. This field can be used to separate these recipients in your UI, however we do not recommend this as it adds unnecessary complexity to the solution. It is safe to ignore this field and display recipients with both true and false values.

2) Bank account data

There are many different variations of bank account details needed depending on recipient target currency. For example:

  • GBP — sort code and account number
  • BGN, CHF, DKK, EUR, GEL, GBP, NOK, PKR, PLN, RON, SEK — IBAN
  • USD — routing number, account number, account type
  • INR — IFSC code, account number
  • etc.

3) Address data Recipient address data is required only if target currency is USD, PHP, THB or TRY, or if the source currency is USD or AUD.

  • Country
  • State (US, Canada, Brazil)
  • City
  • Address line
  • Zip code

When creating recipient, the following general rules should be applied to "accountHolderName" field:

  • Full names for personal recipients. They must include more than one name, and both first and last name must have more than one character. Numbers are not allowed in personal recipient names.
  • Business names must be in full, but can be just a single name. The full name cannot be just a single character but can be made up of a set of single characters. e.g. "A" is not permitted but "A 1" or "A1" is permitted.
  • Special characters _()'*,. are allowed for personal and business names.
  • In general the following regex describes our permitted characters for a name: [0-9A-Za-zÀ-ÖØ-öø-ÿ-_()'*,.\s].

Recipient requirements will vary depending on recipient type. A GBP example is provided here.
As you can see many of the fields are null, in order to know which fields are required for which currency we expose the Recipients Requirements endpoint.

Request

POST /v1/accounts

currencytext

3 character currency code

typetext

Recipient type

profileinteger

Personal or business profile id. It is highly advised to pass the business profile id in this field if your business account is managed by multiple users, so that the recipient can be accessed by all users authorized on the business account.

accountHolderNametext

Recipient full name

ownedByCustomerboolean

Whether this account is owned by the sending user

detailsobject

Currency specific fields

details.legalTypetext

Recipient legal type: PRIVATE or BUSINESS

details.sortCodetext

Recipient bank sort code (GBP example)

details.accountNumbertext

Recipient bank account no (GBP example)

Response

A complete Recipient object is returned when created.

Example Request - 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": {{profileId}},
"ownedByCustomer": true,
"accountHolderName": "Ann Johnson",
"details": {
"legalType": "PRIVATE",
"sortCode": "231470",
"accountNumber": "28821822"
}
}'

Create a refund recipient account

POST /v1/refund-accounts

Sometimes we may need to refund the transfer back to the sender - see the transfer status here for cases when this may happen.

A refund recipient is a person or institution where we will refund transfer the money back to if necessary. This is not always a mandatory resource to create. If the funds are sent over a fast local payment network we can usually infer the refund recipient from the bank transaction that funded the transfer. PLease discuss this with your Wise implementation team if you are unsure if the refund recipient is needed.

If funds are sent using a slow domestic payment network, or you are using a bulk settlement model, we may require you to share the bank details of the source bank account. In order to do this we have the following API:

Response

A complete Recipient object is returned when created.

The refund recipient account id returned here is needed when creating transfers in step 3 as the field sourceAccount in the POST /v1/transfers call.

The format of the request payload for refund recipient creation will be different depending on the currency you will send transfers from. The above example is for GBP only. We can provide the correct format for your region upon request.

Example Request - GBP Refund Recipient
curl -X POST https://api.sandbox.transferwise.tech/v1/refund-accounts \
-H 'Authorization: Bearer <your api token>' \
-H 'Content-Type: application/json' \
-d '{
"currency": "GBP",
"country": "GB",
"type": "sort_code",
"profile": {{profileId}},
"legalEntityType": "PERSON",
"name": {
"fullName": "Ann Johnson"
},
"details": {
"sortCode": "231470",
"accountNumber": "28821822"
}
}'

Create an email recipient account

POST /v1/accounts

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

Wise will email your recipient with a link to collect their bank account details securely. After the bank account details have been provided Wise will complete your transfer.

Please be aware of the following caveats:

  • Testing of transfers to email recipients in sandbox is not currently possible.
  • Recipients will be required to enter bank details every time a payment is made.
  • We highly encourage you to provide the {profileId} if your recipient is receiving a payment from your Business account, especially if you have multiple businesses, or have multiple users administrating your business account.
  • Please refer to our help page on how this works and any additional constraints not mentioned in this section.

Response

A complete Recipient object is returned when created.

Example Request - EUR 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": {{profileId}},
"accountHolderName": "Ann Johnson",
"currency": "EUR",
"type": "email",
"details": {
"email": "ann.johnson@gmail.com"
}
}'

Get Account By Id

GET /v2/accounts/{{accountId}}

Get recipient account info by id. Note here we use the v2 endpoint to get the recipient details despite using v1 to create it. The v2 endpoint provides useful features such as the accountSummary and longAccountSummary field which can be used to represent the recipient's details in your UI. Additionally, the displayFields array would allow you to build an UI containing all the dynamic fields of a recipient individually.

This response also includes a hash of a recipient, this can be used to track if the recipient details change, which they can in some scenarios. This is a security feature to allow you to re-run any checks your system does on the recipient to validate them against, for example, fraud engines. The hash will remain constant unless the recipient's name or information in the details object changes.

Response

A complete Recipient object is returned when created.

Example Request
curl -X GET https://api.sandbox.transferwise.tech/v2/accounts/{{accountId}} \
-H 'Authorization: Bearer <your api token>'
Example Response
{
"content": [
{
"id": 100,
"creatorId": 300,
"profileId": 305,
"name": {
"fullName": "Firstname Lastname",
"givenName": null,
"familyName": null,
"middleName": null,
"patronymicName": null,
"cannotHavePatronymicName": null
},
"address": {
"country": "US",
"firstLine": "1 Wall Street",
"postCode": "10025",
"city": "New York",
"state": "NY"
},
"currency": "USD",
"country": "US",
"type": "Aba",
"legalEntityType": "PERSON",
"email": "example@foobar.com",
"active": true,
"details": {
"abartn": "064000020",
"accountType": "CHECKING",
"accountNumber": "00000000001"
},
"commonFieldMap": {
"accountNumberField": "accountNumber",
"bankCodeField": "abartn"
},
"isDefaultAccount": false,
"hash": "a512e4066bd5997552d35e294d29bacda4b09a7610a7b75562767b17dddadf19",
"accountSummary": "(064000020) 0********01",
"longAccountSummary": "USD account ending in 0001",
"displayFields": [
{
"label": "E-mail",
"value": "example@foobar.com"
},
{
"label": "ACH routing number",
"value": "064000020"
},
{
"label": "Account number",
"value": "00000000001"
}
],
"ownedByCustomer": false
},
{
"id": 101,
"creatorId": 300,
"profileId": 305,
"name": {
"fullName": "Firstname Anothername",
"givenName": null,
"familyName": null,
"middleName": null,
"patronymicName": null,
"cannotHavePatronymicName": null
},
"address": {
"country": "US",
"firstLine": "1 Wall Street",
"postCode": "10025",
"city": "New York",
"state": "NY"
},
"currency": "USD",
"country": "US",
"type": "Aba",
"legalEntityType": "PERSON",
"email": "example2@foobar.com",
"active": true,
"details": {
"abartn": "064000020",
"accountType": "CHECKING",
"accountNumber": "00000000001"
},
"commonFieldMap": {
"accountNumberField": "accountNumber",
"bankCodeField": "abartn"
},
"isDefaultAccount": false,
"hash": "992ca6102a11f2055d14682e0cbacd65727fc45e98b1c42ba1292acad08302c5",
"accountSummary": "(064000020) 0********01",
"longAccountSummary": "USD account ending in 0001",
"displayFields": [
{
"label": "E-mail",
"value": "example2@foobar.com"
},
{
"label": "ACH routing number",
"value": "064000020"
},
{
"label": "Account number",
"value": "00000000002"
}
],
"ownedByCustomer": false
}
],
"sort": {
"sorted": false,
"unsorted": true,
"empty": true
},
"size": 2
}

List recipient accounts by currency for a profile

GET /v2/accounts?profile={{profileId}}&currency={{currency}}

Fetch a list of the user's recipient accounts. Use the profileId parameter to filter by the profile who created the accounts, you should do this based on the personal or business profile ID you have linked to, based on your use case. Other filters are listed below for your convenience, for example currency is a useful filter to use when presenting the user a list of recipients to chose from in the case they have already submitted the target currency of their in your flow.

Pagination

Pagination is supported for this endpoint. The response includes the seekPositionForNext and size parameters to manage this.

It works by setting size and seekPosition parameters in the call. Set the value in the seekPositionForNext of the previous response into the seekPosition parameter of your subsequent call in order to get the next page. To get the current page again, use the seekPositionForCurrent value.

Sorting

You can also set the sort parameter to control the sorting of the response, for example:

?sort=id,asc sort by id ascending.
?sort=id,desc sort by id descending.
?sort=currency,asc sort by currency ascending.

All query parameters are optional.

Query Parameters
creatorIdinteger

Creator of the account.

profileIdinteger

Filter by personal or business profile, returns only those owned by this profile. Defaults to the personal profile.

currencytext

Filter responses by currency, comma separated values are supported (e.g. USD,GBP).

activeboolean

Filter by whether this profile is active. Defaults to true.

typetext

Filter responses by account type, comma separated values are supported (e.g. iban,swift_code).

ownedByCustomerboolean

Filter to get accounts owned by the customer or not, leave out to get all accounts.

sizeinteger

Page size of the response. Defaults to a maximum of 20.

seekPositioninteger

Account ID to start the page of responses from in the response. null if no more pages.

sortinteger

Sorting strategy for the response. Comma separated options: firstly either id or currency, followed by asc or desc for direction.

Response

An array of complete Recipient objects is returned.

Example Request
curl -X GET https://api.sandbox.transferwise.tech/v2/accounts?profile={{profileId}}&currency={{currency}} \
-H 'Authorization: Bearer <your api token>'

Deactivate a recipient account

DELETE /v2/accounts/{{accountId}}

Deletes a recipient by changing its status to inactive ("active": false). Requesting to delete a recipient that is already inactive will return an HTTP status 403 (forbidden).

Response

A complete Recipient object is returned, with the value of active set to false.

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

Retrieve recipient account requirements dynamically

Request

GET /v1/quotes/{{quoteId}}/account-requirements
POST /v1/quotes/{{quoteId}}/account-requirements
GET /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 GET and POST account-requirements endpoints help you to figure out which fields are required to create a valid recipient for different currencies. This is a step-by-step guide on how these endpoints work.

Use the GET endpoint to learn what datapoints are required to send a payment to your beneficiary. As you build that form, use the POST endpoint to learn if any additional datapoints are required as a result of passing a field that has "refreshRequirementsOnChange": true' in the GET Response. You should be posting the same recipient account payload that will be posted to v1/accounts`.

An example of this would be address.country. Some countries, like the United States, have a lower level organization, "state" or "territory". After POSTing the recipient payload with address.country = "US", the list of possible states will appear in the response.

The third endpoint above is used to get account requirements for a specific currency route and amount without referring to a quote but with the amount, source and target currencies passed as URL parameters. Generally this approach is not recommended, you should have your user create a quote resource first and use this to generate the recipient account requirements. This is because some payout methods will only surface when the profile-context is known, for example (at the time of this writing), Business Payments to Chinese Yuan use a different payout method than what is revealed by GET /v1/account-requirements?source=USD&target=CNY&sourceAmount=1000.

All new integrations should use the v1.1 of GET and POST account requirements, enabled using the Accept-Minor-Version header. It enables you to fetch the requirements including both the 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 remove the need for manual name validation. Set the request header Accept-Minor-Version to 1 to use this version.

These endpoints allows use of both v1 and v2 quotes using long or UUID based IDs, supporting legacy implementations using v1 quotes.

Using account requirements

Response
typetext

"address"

fields[n].nametext

Field description

fields[n].group[n].keytext

Key is name of the field you should include in the JSON

fields[n].group[n].typetext

Display type of field. Can be text, select, radio or date

fields[n].group[n].refreshRequirementsOnChangeboolean

Tells you whether you should call POST account-requirements once the field value is set to discover required lower level fields.

fields[n].group[n].requiredboolean

Indicates if the field is mandatory or not

fields[n].group[n].displayFormattext

Display format pattern.

fields[n].group[n].exampletext

Example value.

fields[n].group[n].minLengthinteger

Min valid length of field value.

fields[n].group[n].maxLengthinteger

Max valid length of field value.

fields[n].group[n].validationRegexptext

Regexp validation pattern.

fields[n].group[n].validationAsynctext

Validator URL and parameter name you should use when submitting the value for validation

fields[n].group[n].valuesAllowed[n].keytext

List of allowed values. Value key

fields[n].group[n].valuesAllowed[n].nametext

List of allowed values. Value name.

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
}
]
}
]
},