openapi: 3.1.0
info:
title: Wise Platform 3ds recipient API
version: ''
description: "The Wise Platform API is a REST-based interface that enables programmatic access to Wise's payment infrastructure. All endpoints return JSON-formatted responses and use standard HTTP methods and status codes.\n{% admonition type=\"success\" name=\"New to wise?\" %}\n We strongly recommend first reading our **[Getting Started Guide](/guides/developer/index.md)** to help you set up credentials and make your first call.\n{% /admonition %}\n\nBefore you begin {% .title-2 .m-t-5 %}\n\nTo use this API reference effectively, you should have:\n\n- Received Valid [API credentials from Wise](/guides/developer/auth-and-security/index.md) (Client ID and Client Secret)\n- Understand OAuth 2.0 authentication\n- Be familiar with RESTful API concepts\n\nCore API resources {% .title-2 .m-t-5 .m-b-0 %}\n\n| Resource | Purpose |\n|----------|---------|\n| **[Quote](/api-reference/quote)** | Exchange rate and fee calculations |\n| **[Recipient](/api-reference/recipient)** | Beneficiary account management |\n| **[Transfer](/api-reference/transfer)** | Payment creation and execution |\n| **[Balance](/api-reference/balance)** | Multi-currency account operations |\n| **[Profile](/api-reference/profile)** | Account ownership details |\n| **[Rate](/api-reference/rate)** | Current and historical exchange rates |\n\n**Not sure which workflow to build?**<br>\nStart with our [Integration Guides](/guides/product/send-money/use-cases/index.md) for step-by-step implementation examples.{% .m-t-3 .m-b-5 %}\n"
servers:
- url: https://api.wise.com
description: Production Environment
- url: https://api.wise-sandbox.com
description: Sandbox Environment
tags:
- name: recipient
x-displayName: Recipient Accounts
description: 'Recipient or beneficiary is the one who will receive the funds.
Recipient account endpoints use a mixture of our v1 and v2 APIs. Please ensure you address the right version to get the expected results.
{% admonition type="info" %}
All recipient IDs are cross compatible with v1 and v2.
{% /admonition %}
'
paths:
/v1/accounts:
get:
operationId: recipientListV1
summary: List recipient accounts (v1)
deprecated: true
description: '{% admonition type="warning" %}
This is a deprecated v1 endpoint. For new integrations please use the [v2 list endpoint](/api-reference/recipient/recipientlist).
{% /admonition %}
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 endpoint does not support pagination, so please filter by currency to ensure a reasonable response time.
Both query parameters are optional.
'
tags:
- recipient
security:
- UserToken: []
parameters:
- name: profileId
in: query
required: false
description: Filter by personal or business profile, returns only those owned by this profile.
schema:
type: integer
format: int64
- name: currency
in: query
required: false
description: Filter responses by currency.
schema:
type: string
- $ref: '#/components/parameters/X-External-Correlation-Id'
responses:
'200':
description: Array of v1 recipient account objects.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/recipient-v1'
headers:
X-External-Correlation-Id:
$ref: '#/components/headers/X-External-Correlation-Id'
x-trace-id:
$ref: '#/components/headers/x-trace-id'
'429':
$ref: '#/components/responses/429'
post:
operationId: recipientCreate
summary: Create a recipient account
description: "Creates a recipient account. A **recipient** is a person or institution who is the ultimate beneficiary of your payment.\n\nRecipient data includes three data blocks:\n- General data - the personal details of an individual and basic information about a business.\n- Bank details - account numbers, routing numbers, and other region-specific bank details.\n- Address details - country and street address of an individual or business.\n\nNotes:\n- Date of Birth is optional; consult the account-requirements APIs to confirm if it is needed or contact Wise Support.\n- `ownedByCustomer` is optional but strongly recommended for self-transfers.\n- Email recipients: testing transfers to email recipients in sandbox is not currently possible.\n\nRefund recipients:\n- Use `refund=true` query parameter.\n\n#### Bank account data\nThere are many different variations of bank account details needed depending on recipient target currency. For example:\n\n- **GBP** — sort code and account number\n- **BGN, CHF, DKK, EUR, GEL, GBP, NOK, PKR, PLN, RON, SEK** — IBAN\n- **USD** — routing number, account number, account type\n- **INR** — IFSC code, account number\n- etc.\n\n#### Address data\nRecipient address data is required only if target currency is **USD, PHP, THB or TRY**, or if the source currency is **USD or AUD**.\n\nAddress fields can include:\n- Country\n- State (US, Canada, Brazil)\n- City\n- Address line\n- Zip code\n\n#### accountHolderName rules\n- **Personal recipients:** Full names must include more than one name, and both first and last name must have more than one character. Numbers are not allowed.\n- **Business recipients:** Business names must be in full and can be 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).\n- Special characters `_()'*,.` are allowed for personal and business names.\n- In general the following regex describes permitted characters:\n `[0-9A-Za-zÀ-ÖØ-öø-ÿ-_()'*,.\\s]`.\n\nRecipient requirements vary depending on recipient type/currency route. A GBP example is provided here.<br>\nMany fields may be `null` in examples. To determine which fields are required for which currency, use the\n**[Recipient Requirements](/api-reference/recipient/recipientAccountRequirementsGet)** endpoint.\n\n#### Create a refund recipient account\n`POST /v1/accounts?refund=true`\n\nSometimes we may need to refund the transfer back to the sender - see the [transfer status here](/guides/product/send-money/tracking-transfers) for cases when this may happen.\n\nA 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.\n\nIf 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.\n\nThe format of the request payload for refund recipient creation will be different depending on the currency you will send transfers from. You may use the [account requirements](/api-reference/recipient/recipientaccountrequirementsget) endpoint to understand the payload requirements when creating the refund recipient for a specific currency.\n\nThe refund recipient account ID returned in the response is used as `sourceAccount` when [creating transfers](/guides/product/send-money/transfers).\n\n#### Create an email recipient account\n`POST /v1/accounts`\n\n{% admonition type=\"warning\" %}\nPlease contact us before attempting to use email recipients. We do not recommend using this feature except for certain use cases.\n{% /admonition %}\n\nIf you don't know recipient bank account details you can set up an email recipient; Wise will collect bank details directly from the recipient.\n\nWise 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.\n\nIt's best to confirm that this recipient type is available to your transaction by checking if the `\"type\": \"email\"` class is present in the response from `GET /v1/quotes/{quoteId}/account-requirements` — see **[account requirements](/api-reference/recipient/recipientAccountRequirementsGet)** for more information on how to use this endpoint.\n\nIf planning to send multiple currencies to a single recipient, you will need to create a separate email recipient resource for this beneficiary, for every currency you intend to send to them. 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.\n\nPlease be aware of the following caveats:\n- Testing of transfers to email recipients in sandbox is not currently possible.\n- Recipients will be required to enter bank details **every time a payment is made**.\n- 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.\n- Please refer to our **[help page](https://wise.com/help/articles/2932105/can-i-send-money-to-someone-with-only-their-email-address)** on how this works and any additional constraints not mentioned in this section.\n"
tags:
- recipient
security:
- UserToken: []
parameters:
- name: refund
in: query
required: false
description: When true, creates a refund recipient account.
schema:
type: boolean
default: false
- $ref: '#/components/parameters/X-External-Correlation-Id'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/recipient-create-request'
examples:
GBP recipient:
summary: GBP recipient
value:
currency: GBP
type: sort_code
profile: 30000000
ownedByCustomer: true
accountHolderName: John Doe
details:
legalType: PRIVATE
sortCode: '040075'
accountNumber: '37778842'
dateOfBirth: '1961-01-01'
Email recipient:
summary: Email recipient
value:
profile: 30000000
accountHolderName: John Doe
currency: EUR
type: email
details:
email: john.doe@transfer-world.com
responses:
'200':
description: Recipient account created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/recipient'
headers:
X-External-Correlation-Id:
$ref: '#/components/headers/X-External-Correlation-Id'
x-trace-id:
$ref: '#/components/headers/x-trace-id'
'400':
description: Bad Request — validation error.
content:
application/json:
schema:
type: object
description: Recipient creation validation error response.
properties:
timestamp:
type: string
description: Timestamp of occurrence (ISO-8601 timestamp).
example: '2024-12-06T06:43:52.472471344Z'
errors:
type: array
description: List of validation errors.
items:
type: object
properties:
code:
type: string
description: Error code (e.g. NOT_VALID).
example: NOT_VALID
message:
type: string
description: Human-readable error message.
example: Unknown bank code. Please check the sort code is correct, or contact customer support for more information.
path:
type: string
description: Field associated with the error.
example: sortCode
arguments:
type: array
description: Field with error as well as input value.
items:
type: string
example:
- sortCode
- '231479'
headers:
X-External-Correlation-Id:
$ref: '#/components/headers/X-External-Correlation-Id'
x-trace-id:
$ref: '#/components/headers/x-trace-id'
'401':
description: Unauthorized.
content:
application/json:
examples:
UnauthorizedResponse:
value:
error_description: Invalid token
error: invalid_token
headers:
X-External-Correlation-Id:
$ref: '#/components/headers/X-External-Correlation-Id'
x-trace-id:
$ref: '#/components/headers/x-trace-id'
'429':
$ref: '#/components/responses/429'
/v2/accounts:
get:
operationId: recipientList
summary: List recipient accounts
description: '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 choose from in the case they have already submitted the target currency 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.<br>
`?sort=id,desc` sort by `id` descending.<br>
`?sort=currency,asc` sort by currency ascending.
All query parameters are optional.
'
tags:
- recipient
security:
- UserToken: []
parameters:
- name: creatorId
in: query
required: false
description: Creator of the account.
schema:
type: integer
format: int64
- name: profileId
in: query
required: false
description: Filter by personal or business profile. Defaults to the personal profile.
schema:
type: integer
format: int64
- name: profile
in: query
required: false
description: Alias for `profileId`.
schema:
type: integer
format: int64
- name: currency
in: query
required: false
description: Filter responses by currency. Comma separated values supported (e.g. `USD,GBP`).
schema:
type: string
- name: active
in: query
required: false
description: Filter by whether this profile is active. Defaults to `true`.
schema:
type: boolean
default: true
- name: type
in: query
required: false
description: Filter responses by account type. Comma separated values supported (e.g. `iban,swift_code`).
schema:
type: string
- name: ownedByCustomer
in: query
required: false
description: Filter to get accounts owned by the customer or not. Leave out to get all accounts.
schema:
type: boolean
- name: size
in: query
required: false
description: Page size of the response. Defaults to a maximum of 20.
schema:
type: integer
format: int32
maximum: 20
- name: seekPosition
in: query
required: false
description: Account ID to start the page of responses from. `null` if no more pages.
schema:
type:
- integer
- 'null'
format: int64
- name: sort
in: query
required: false
description: Sorting strategy for the response. Comma separated options - firstly either `id` or `currency`, followed by `asc` or `desc` for direction.
schema:
type: string
example: id,asc
- $ref: '#/components/parameters/X-External-Correlation-Id'
responses:
'200':
description: Paginated list of recipient accounts.
content:
application/json:
schema:
type: object
properties:
content:
type: array
description: List of recipient accounts returned for this page.
items:
$ref: '#/components/schemas/recipient'
seekPositionForNext:
type: integer
format: int64
description: Seek position for the next page (use as `seekPosition` to fetch the next page).
seekPositionForCurrent:
type: integer
format: int64
description: Seek position for the current page.
sort:
type: object
description: Sort metadata.
properties:
empty:
type: boolean
sorted:
type: boolean
unsorted:
type: boolean
size:
type: integer
format: int32
description: Page size returned.
example: 20
example:
content:
- id: 40000000
creatorId: 41000000
profileId: 30000000
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
sortCode: '040075'
accountNumber: '37778842'
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
seekPositionForNext: 40000001
seekPositionForCurrent: 40000000
sort:
empty: true
sorted: false
unsorted: true
size: 20
headers:
X-External-Correlation-Id:
$ref: '#/components/headers/X-External-Correlation-Id'
x-trace-id:
$ref: '#/components/headers/x-trace-id'
'401':
description: Unauthorized.
headers:
X-External-Correlation-Id:
$ref: '#/components/headers/X-External-Correlation-Id'
x-trace-id:
$ref: '#/components/headers/x-trace-id'
'403':
description: Forbidden.
headers:
X-External-Correlation-Id:
$ref: '#/components/headers/X-External-Correlation-Id'
x-trace-id:
$ref: '#/components/headers/x-trace-id'
'429':
$ref: '#/components/responses/429'
/v1/accounts/{accountId}:
get:
operationId: recipientGetV1
summary: Get account by ID (v1)
deprecated: true
description: '{% admonition type="warning" %}
This is a deprecated v1 endpoint. For new integrations please use the [v2 get endpoint](/api-reference/recipient/recipientget).
{% /admonition %}
Get recipient account info by ID.
'
tags:
- recipient
security:
- UserToken: []
parameters:
- name: accountId
in: path
required: true
description: Recipient account ID.
schema:
type: integer
format: int64
- $ref: '#/components/parameters/X-External-Correlation-Id'
responses:
'200':
description: V1 recipient account details.
content:
application/json:
schema:
$ref: '#/components/schemas/recipient-v1'
headers:
X-External-Correlation-Id:
$ref: '#/components/headers/X-External-Correlation-Id'
x-trace-id:
$ref: '#/components/headers/x-trace-id'
'429':
$ref: '#/components/responses/429'
/v2/accounts/{accountId}:
get:
operationId: recipientGet
summary: Get account by ID
description: 'Get recipient account info by ID.
{% admonition type="info" %}
V1 and v2 versions are cross compatible, but the v2 endpoint provides additional features.
{% /admonition %}
'
tags:
- recipient
security:
- UserToken: []
parameters:
- name: accountId
in: path
required: true
description: Recipient account ID.
schema:
type: integer
format: int64
- $ref: '#/components/parameters/X-External-Correlation-Id'
responses:
'200':
description: Recipient account details.
content:
application/json:
schema:
$ref: '#/components/schemas/recipient'
headers:
X-External-Correlation-Id:
$ref: '#/components/headers/X-External-Correlation-Id'
x-trace-id:
$ref: '#/components/headers/x-trace-id'
'429':
$ref: '#/components/responses/429'
delete:
operationId: recipientDeactivate
summary: Deactivate a recipient account
description: 'Deletes a recipient by changing its status to inactive (`"active": false`).
Requesting to delete a recipient that is already inactive returns HTTP 403 (Forbidden).
{% admonition type="info" %}
Only active recipients can be deleted and a recipient cannot be reactivated, however you can create a new recipient with the same details instead if necessary.
{% /admonition %}
'
tags:
- recipient
security:
- UserToken: []
parameters:
- name: accountId
in: path
required: true
description: Recipient account ID.
schema:
type: integer
format: int64
- $ref: '#/components/parameters/X-External-Correlation-Id'
responses:
'200':
description: Recipient returned with `active=false`.
content:
application/json:
schema:
$ref: '#/components/schemas/recipient'
headers:
X-External-Correlation-Id:
$ref: '#/components/headers/X-External-Correlation-Id'
x-trace-id:
$ref: '#/components/headers/x-trace-id'
'429':
$ref: '#/components/responses/429'
/v1/quotes/{quoteId}/account-requirements:
get:
operationId: recipientAccountRequirementsGet
summary: Retrieve recipient account requirements dynamically
description: '{% admonition type="info" %}
Please note that to use v1.1 `Accept-Minor-Version: 1` request header must be set.
{% /admonition %}
`GET /v1/quotes/{quoteId}/account-requirements`<br>
`POST /v1/quotes/{quoteId}/account-requirements`<br>
`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.
These endpoints allow use of both v1 and v2 quotes using long or UUID based IDs, supporting legacy implementations using v1 quotes.
These endpoints accept an optional query parameter **originatorLegalEntityType**. When the transfer is initiated by a [Third Party Partner](/guides/product/kyc/partner-accounts) we are not aware whether the actual sender is a business or person. In such cases, this parameter should be passed to receive correct requirements. The legal entity type should be one of the following values: `BUSINESS`, `PRIVATE`. This parameter is optional and the default value is the type of the partner profile.
#### Collecting Recipient Address
Normally our account requirements will instruct when a recipient address is required. However, in some situations it''s desirable to force the requirement so that an address can be provided to Wise. To do this, add the query parameter `?addressRequired=true` to your request and address will always be returned as a required field.
{% admonition type="warning" %}
Address requirement fields are subject to change. Your integration should be built in a way to handle unrecognized or changed fields.
{% /admonition %}
'
tags:
- recipient
security:
- UserToken: []
parameters:
- name: quoteId
in: path
required: true
description: Quote ID (supports long or UUID based IDs).
schema:
type: string
- name: originatorLegalEntityType
in: query
required: false
description: Legal entity type override for the actual sender.
schema:
type: string
enum:
- BUSINESS
- PRIVATE
- name: addressRequired
in: query
required: false
description: Set to true so address is always required.
schema:
type: boolean
default: false
- name: Accept-Minor-Version
in: header
required: false
description: Set to `1` to enable v1.1.
schema:
type: integer
enum:
- 1
- $ref: '#/components/parameters/X-External-Correlation-Id'
responses:
'200':
description: Dynamic account requirements for building a recipient form.
content:
application/json:
schema:
$ref: '#/components/schemas/account-requirements-response'
headers:
X-External-Correlation-Id:
$ref: '#/components/headers/X-External-Correlation-Id'
x-trace-id:
$ref: '#/components/headers/x-trace-id'
'401':
description: Unauthorized.
headers:
X-External-Correlation-Id:
$ref: '#/components/headers/X-External-Correlation-Id'
x-trace-id:
$ref: '#/components/headers/x-trace-id'
'403':
description: Forbidden.
headers:
X-External-Correlation-Id:
$ref: '#/components/headers/X-External-Correlation-Id'
x-trace-id:
$ref: '#/components/headers/x-trace-id'
'404':
description: Not Found.
headers:
X-External-Correlation-Id:
$ref: '#/components/headers/X-External-Correlation-Id'
x-trace-id:
$ref: '#/components/headers/x-trace-id'
'429':
$ref: '#/components/responses/429'
post:
operationId: recipientAccountRequirementsPost
summary: Retrieve recipient account requirements dynamically (step-by-step)
description: 'POST the same recipient account payload that you will POST to `/v1/accounts`.
Use this endpoint after setting any field that has `refreshRequirementsOnChange=true` in the GET response,
to discover any additional required fields.
See the [GET endpoint](/api-reference/recipient/recipientaccountrequirementsget) for a full overview of how the account requirements flow works.
'
tags:
- recipient
security:
- UserToken: []
parameters:
- name: quoteId
in: path
required: true
description: Quote ID (supports long or UUID based IDs).
schema:
type: string
- name: originatorLegalEntityType
in: query
required: false
description: Legal entity type override for the actual sender.
schema:
type: string
enum:
- BUSINESS
- PRIVATE
- name: Accept-Minor-Version
in: header
required: false
description: Set to `1` to enable v1.1.
schema:
type: integer
enum:
- 1
# --- truncated at 32 KB (72 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/wise/refs/heads/main/openapi/wise-recipient-api-openapi.yml