> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qonto.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Verify a SEPA payee
> OAuth scope: `payment.write`
Verifies payee information by matching IBAN and beneficiary name for internal and external accounts.
Returns a match result indicating whether the provided information matches
the account holder's details. In the case of close matches, the matched name is returned.
You can also use the [Sandbox environment](/api-reference/business-api/payments-transfers/sepa-transfers/introduction#testing-with-sandbox) to test the endpoint with mocked IBANs.
**Token requirement**
The proof_token included in the response is required for initiating a SEPA transfer and will be valid regardless of the verification result. Please review the response, results that are not a `MATCH_RESULT_MATCH` may indicate a transfer will be sent to a wrong beneficiary.
**Rate limits**
A verification is only intended to be used before initiating a SEPA transfer. Rate limits will apply to verifications that are not followed by a transfer initiation. Please perform each individual verification before its corresponding transfer.
**Error handling — responding bank errors vs verification results**
It is important to distinguish between **verification results** (HTTP 200) and **error responses** (HTTP 4xx/5xx):
- A `200` response with `MATCH_RESULT_NOT_POSSIBLE` means the responding bank was **successfully contacted** but could not perform the name verification (e.g., the account type does not support Verification of Payee). A `proof_token` is included.
- A `400` error with codes like `BAD_REQUEST_ERROR_RESPONDING_BANK_NOT_AVAILABLE`, `BAD_REQUEST_ERROR_5XX_RESPONDING_BANK`, or `BAD_REQUEST_ERROR_RESPONDING_BANK_INVALID_RESPONSE` means the responding bank returned an unexpected response. A `proof_token` is included in the error `meta`.
- A `503` error with `BAD_GATEWAY_ERROR_RESPONDING_BANK` or `GATEWAY_TIMEOUT_ERROR_RESPONDING_BANK` means the responding bank **could not be reached** or returned a server error. This is a transient issue — retry after a short delay. A `proof_token` is included in the error `meta`.
Per the EPC Verification of Payee API Specification (EPC103-24 v1.0.1), when the responding PSP is unreachable or returns a technical error, this must be relayed as a service failure — not as a `MATCH_RESULT_NOT_POSSIBLE`. The `proof_token` provided in error responses allows you to proceed with the transfer if needed, but the payee name was not verified.
## OpenAPI
````yaml POST /v2/sepa/verify_payee
openapi: 3.1.1
info:
version: v2
title: Qonto
servers:
- url: https://thirdparty.qonto.com
description: Production URL
- url: https://thirdparty-sandbox.staging.qonto.co
description: Sandbox URL
security:
- OAuth:
- organization.read
- membership.read
- membership.write
- attachment.write
- internal_transfer.write
- payment.write
- supplier_invoice.write
- supplier_invoice.read
- client_invoices.read
- client_invoice.write
- client.read
- client.write
- product.read
- product.write
- request_review.write
- request_review.read
- team.read
- team.write
- request_transfers.write
- insurance_contract.read
- insurance_contract.write
- card.read
- card.write
- bank_account.write
- beneficiary.trust
- webhook
- payment_link.write
- payment_link.read
- sepa_direct_debit.read
- sepa_direct_debit.write
- terminal.read
- terminal.write
- SecretKey: []
paths:
/v2/sepa/verify_payee:
post:
tags:
- SEPA Transfers
summary: Verify a SEPA payee
description: >
OAuth scope: `payment.write`
Verifies payee information by matching IBAN and beneficiary name for
internal and external accounts.
Returns a match result indicating whether the provided information
matches
the account holder's details. In the case of close matches, the matched
name is returned.
You can also use the [Sandbox environment](/api-reference/business-api/payments-transfers/sepa-transfers/introduction#testing-with-sandbox) to test the endpoint with mocked IBANs.
**Token requirement**
The proof_token included in the response is required for initiating a SEPA transfer and will be valid regardless of the verification result. Please review the response, results that are not a `MATCH_RESULT_MATCH` may indicate a transfer will be sent to a wrong beneficiary.
**Rate limits**
A verification is only intended to be used before initiating a SEPA transfer. Rate limits will apply to verifications that are not followed by a transfer initiation. Please perform each individual verification before its corresponding transfer.
**Error handling — responding bank errors vs verification results**
It is important to distinguish between **verification results** (HTTP 200) and **error responses** (HTTP 4xx/5xx):
- A `200` response with `MATCH_RESULT_NOT_POSSIBLE` means the responding bank was **successfully contacted** but could not perform the name verification (e.g., the account type does not support Verification of Payee). A `proof_token` is included.
- A `400` error with codes like `BAD_REQUEST_ERROR_RESPONDING_BANK_NOT_AVAILABLE`, `BAD_REQUEST_ERROR_5XX_RESPONDING_BANK`, or `BAD_REQUEST_ERROR_RESPONDING_BANK_INVALID_RESPONSE` means the responding bank returned an unexpected response. A `proof_token` is included in the error `meta`.
- A `503` error with `BAD_GATEWAY_ERROR_RESPONDING_BANK` or `GATEWAY_TIMEOUT_ERROR_RESPONDING_BANK` means the responding bank **could not be reached** or returned a server error. This is a transient issue — retry after a short delay. A `proof_token` is included in the error `meta`.
Per the EPC Verification of Payee API Specification (EPC103-24 v1.0.1), when the responding PSP is unreachable or returns a technical error, this must be relayed as a service failure — not as a `MATCH_RESULT_NOT_POSSIBLE`. The `proof_token` provided in error responses allows you to proceed with the transfer if needed, but the payee name was not verified.
operationId: verifyPayee
parameters:
- $ref: '#/components/parameters/X-Qonto-Staging-Token'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- iban
- beneficiary_name
properties:
iban:
type: string
description: IBAN of the beneficiary account to be verified
example: FR7616958000014849440866435
pattern: ^[A-Z]{2}[0-9]{2}[A-Z0-9]{4}[0-9]{7}([A-Z0-9]?){0,16}$
beneficiary_name:
type: string
description: Name of the beneficiary to verify against the account
example: John Doe
minLength: 1
maxLength: 140
examples:
basic_verification:
summary: Basic payee verification
value:
iban: FR7616958000014849440866435
beneficiary_name: Default Match Person
responses:
'200':
description: Verification completed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/VerifyPayeeResponse'
examples:
match_result:
summary: Exact match found
value:
match_result: MATCH_RESULT_MATCH
proof_token:
token: proof_1234567890abcdef
close_match_result:
summary: Close match found
value:
match_result: MATCH_RESULT_CLOSE_MATCH
matched_name: Jon Jones
proof_token:
token: proof_1234567890abcdef
no_match_result:
summary: No match found
value:
match_result: MATCH_RESULT_NO_MATCH
proof_token:
token: proof_1234567890abcdef
not_possible_result:
summary: >
Verification not possible. The responding bank was
successfully reached but cannot perform
name verification for this account. This may happen if the
account type does not support
Verification of Payee (VoP), or the responding bank cannot
confirm or deny the match.
This is different from a 503 error, which indicates the
responding bank could not be reached at all.
value:
match_result: MATCH_RESULT_NOT_POSSIBLE
proof_token:
token: proof_1234567890abcdef
'400':
description: >
Bad request. This may indicate invalid input parameters, or an issue
with the responding bank's response.
When the error code relates to the responding bank (e.g.,
`BAD_REQUEST_ERROR_RESPONDING_BANK_NOT_AVAILABLE`,
`BAD_REQUEST_ERROR_5XX_RESPONDING_BANK`,
`BAD_REQUEST_ERROR_RESPONDING_BANK_INVALID_RESPONSE`),
a `proof_token` is included in the error `meta` field.
content:
application/json:
schema:
type: object
required:
- errors
properties:
errors:
type: array
items:
type: object
description: Error object for 400 Bad Request responses
properties:
id:
type:
- string
- 'null'
description: >-
A unique identifier for this particular occurrence
of the problem
example: 550e8400-e29b-41d4-a716-446655440000
status:
type:
- string
- 'null'
description: >-
The HTTP status code applicable to this problem,
expressed as a string value
enum:
- '400'
code:
type:
- string
- 'null'
description: >
Error code indicating the specific type of error.
- `BAD_REQUEST_ERROR_UNSPECIFIED`: An unspecified
bad request error.
- `BAD_REQUEST_ERROR_FORMAT`: The request format is
invalid.
- `BAD_REQUEST_ERROR_RESPONDING_BANK_NOT_AVAILABLE`:
The responding bank is not available for
Verification of Payee.
- `BAD_REQUEST_ERROR_5XX_RESPONDING_BANK`: The
responding bank returned a 5xx server error.
-
`BAD_REQUEST_ERROR_RESPONDING_BANK_INVALID_RESPONSE`:
The responding bank returned an invalid or
unparseable response.
enum:
- BAD_REQUEST_ERROR_UNSPECIFIED
- BAD_REQUEST_ERROR_FORMAT
- BAD_REQUEST_ERROR_RESPONDING_BANK_NOT_AVAILABLE
- BAD_REQUEST_ERROR_5XX_RESPONDING_BANK
- BAD_REQUEST_ERROR_RESPONDING_BANK_INVALID_RESPONSE
title:
type:
- string
- 'null'
description: >
A short, human-readable summary of the problem that
SHOULD NOT change from occurrence
to occurrence of the problem, except for purposes of
localization
example: Invalid Request Format
detail:
type:
- string
- 'null'
description: >
A human-readable explanation specific to this
occurrence of the problem.
Like title, this field's value can be localized
example: The request has an invalid format
source:
type: object
description: >-
Source objects provide references to the source of
an error in the request document
properties:
pointer:
type:
- string
- 'null'
description: >
A JSON Pointer [RFC6901] to the value in the
request document that caused the error.
This MUST point to a value in the request
document that exists
example: /data/attributes/iban
parameter:
type:
- string
- 'null'
description: >-
A string indicating which URI query parameter
caused the error
example: page
additionalProperties: false
meta:
type:
- object
- 'null'
description: >-
An object containing non-standard meta-information
about the error
additionalProperties: true
additionalProperties: false
minItems: 1
examples:
bad_request:
summary: Invalid response from responding bank
value:
errors:
- code: BAD_REQUEST_ERROR_RESPONDING_BANK_INVALID_RESPONSE
status: '400'
detail: Invalid response received from the responding bank
source:
parameter: source
meta:
proof_token:
token: proof_1234567890abcdef
'500':
description: Internal server error
content:
application/json:
schema:
type: object
required:
- errors
properties:
errors:
type: array
items:
type: object
description: Error object for 500 Internal Server Error responses
properties:
id:
type:
- string
- 'null'
description: >-
A unique identifier for this particular occurrence
of the problem
example: 550e8400-e29b-41d4-a716-446655440000
status:
type:
- string
- 'null'
description: >-
The HTTP status code applicable to this problem,
expressed as a string value
enum:
- '500'
code:
type:
- string
- 'null'
description: >-
Error code indicating the specific type of error for
500 responses
enum:
- INTERNAL_SERVER_ERROR_UNSPECIFIED
- INTERNAL_SERVER_ERROR_4XX_RESPONDING_BANK
title:
type:
- string
- 'null'
description: >
A short, human-readable summary of the problem that
SHOULD NOT change from occurrence
to occurrence of the problem, except for purposes of
localization
example: Invalid Request Format
detail:
type:
- string
- 'null'
description: >
A human-readable explanation specific to this
occurrence of the problem.
Like title, this field's value can be localized
example: The request has an invalid format
source:
type: object
description: >-
Source objects provide references to the source of
an error in the request document
properties:
pointer:
type:
- string
- 'null'
description: >
A JSON Pointer [RFC6901] to the value in the
request document that caused the error.
This MUST point to a value in the request
document that exists
example: /data/attributes/iban
parameter:
type:
- string
- 'null'
description: >-
A string indicating which URI query parameter
caused the error
example: page
additionalProperties: false
meta:
type:
- object
- 'null'
description: >-
An object containing non-standard meta-information
about the error
additionalProperties: true
additionalProperties: false
minItems: 1
examples:
responding_bank_error:
summary: Internal server error - responding bank error
value:
errors:
- code: INTERNAL_SERVER_ERROR_4XX_RESPONDING_BANK
status: '500'
detail: 4xx error from responding bank
source:
parameter: source
meta:
proof_token:
token: proof_1234567890abcdef
unspecified_error:
summary: Internal server error - unspecified error
value:
errors:
- code: INTERNAL_SERVER_ERROR_UNSPECIFIED
status: '500'
detail: An internal server error occurred
'501':
description: Feature not implemented
content:
application/json:
schema:
type: object
required:
- errors
properties:
errors:
type: array
items:
type: object
description: Error object for 501 Not Implemented responses
properties:
id:
type:
- string
- 'null'
description: >-
A unique identifier for this particular occurrence
of the problem
example: 550e8400-e29b-41d4-a716-446655440000
status:
type:
- string
- 'null'
description: >-
The HTTP status code applicable to this problem,
expressed as a string value
enum:
- '501'
code:
type:
- string
- 'null'
description: >-
Error code indicating the specific type of error for
501 responses
enum:
- NOT_IMPLEMENTED_ERROR_UNSPECIFIED
- NOT_IMPLEMENTED_ERROR_FEATURE_NOT_AVAILABLE
title:
type:
- string
- 'null'
description: >
A short, human-readable summary of the problem that
SHOULD NOT change from occurrence
to occurrence of the problem, except for purposes of
localization
example: Invalid Request Format
detail:
type:
- string
- 'null'
description: >
A human-readable explanation specific to this
occurrence of the problem.
Like title, this field's value can be localized
example: The request has an invalid format
source:
type: object
description: >-
Source objects provide references to the source of
an error in the request document
properties:
pointer:
type:
- string
- 'null'
description: >
A JSON Pointer [RFC6901] to the value in the
request document that caused the error.
This MUST point to a value in the request
document that exists
example: /data/attributes/iban
parameter:
type:
- string
- 'null'
description: >-
A string indicating which URI query parameter
caused the error
example: page
additionalProperties: false
meta:
type:
- object
- 'null'
description: >-
An object containing non-standard meta-information
about the error
additionalProperties: true
additionalProperties: false
minItems: 1
examples:
not_implemented:
summary: Feature not available
value:
errors:
- code: NOT_IMPLEMENTED_ERROR_FEATURE_NOT_AVAILABLE
status: '501'
detail: The requested feature is not available
source:
parameter: source
'503':
description: >
Service unavailable — the responding bank could not be reached,
returned a server error, or timed out.
This is a transient infrastructure issue. Retry the verification
after a short delay.
A `proof_token` is included in the error `meta` field, allowing you
to proceed with the transfer
if the verification cannot be completed after retries. Note: this is
distinct from a `200` response
with `MATCH_RESULT_NOT_POSSIBLE`, which indicates the bank was
reached but cannot perform the verification.
content:
application/json:
schema:
type: object
required:
- errors
properties:
errors:
type: array
items:
type: object
description: Error object for 503 Service Unavailable responses
properties:
id:
type:
- string
- 'null'
description: >-
A unique identifier for this particular occurrence
of the problem
example: 550e8400-e29b-41d4-a716-446655440000
status:
type:
- string
- 'null'
description: >-
The HTTP status code applicable to this problem,
expressed as a string value
enum:
- '503'
code:
type:
- string
- 'null'
description: >
Error code indicating the specific type of error.
- `BAD_GATEWAY_ERROR_RESPONDING_BANK`: The
responding bank returned a 5xx server error or an
invalid response.
- `GATEWAY_TIMEOUT_ERROR_RESPONDING_BANK`: The
request to the responding bank timed out.
enum:
- BAD_GATEWAY_ERROR_RESPONDING_BANK
- GATEWAY_TIMEOUT_ERROR_RESPONDING_BANK
title:
type:
- string
- 'null'
description: >
A short, human-readable summary of the problem that
SHOULD NOT change from occurrence
to occurrence of the problem, except for purposes of
localization
example: Responding Bank Unavailable
detail:
type:
- string
- 'null'
description: >
A human-readable explanation specific to this
occurrence of the problem.
Like title, this field's value can be localized
example: The responding bank is temporarily unavailable
source:
type: object
description: >-
Source objects provide references to the source of
an error in the request document
properties:
pointer:
type:
- string
- 'null'
description: >
A JSON Pointer [RFC6901] to the value in the
request document that caused the error.
This MUST point to a value in the request
document that exists
example: /data/attributes/iban
parameter:
type:
- string
- 'null'
description: >-
A string indicating which URI query parameter
caused the error
example: page
additionalProperties: false
meta:
type:
- object
- 'null'
description: >-
An object containing non-standard meta-information
about the error
additionalProperties: true
additionalProperties: false
minItems: 1
examples:
responding_bank_error:
summary: Responding bank returned an error
value:
errors:
- code: BAD_GATEWAY_ERROR_RESPONDING_BANK
status: '503'
detail: The responding bank responded with an error
source:
parameter: iban
meta:
proof_token:
token: proof_1234567890abcdef
timeout:
summary: Gateway timeout from responding bank
value:
errors:
- code: GATEWAY_TIMEOUT_ERROR_RESPONDING_BANK
status: '503'
detail: Timeout occurred while contacting the responding bank
source:
parameter: iban
meta:
proof_token:
token: proof_1234567890abcdef
security:
- OAuth:
- payment.write
components:
parameters:
X-Qonto-Staging-Token:
name: X-Qonto-Staging-Token
in: header
description: >-
Required only for Sandbox API requests; to get one, please sign up to
the [Developer Portal](https://developers.qonto.com/).
schema:
type: string
schemas:
VerifyPayeeResponse:
type: object
properties:
match_result:
type: string
description: Result of the payee verification
enum:
- MATCH_RESULT_MATCH
- MATCH_RESULT_NO_MATCH
- MATCH_RESULT_CLOSE_MATCH
- MATCH_RESULT_NOT_POSSIBLE
- MATCH_RESULT_UNSPECIFIED
example: MATCH_RESULT_MATCH
matched_name:
type:
- string
- 'null'
description: >-
The actual name associated with the account (present for close
matches)
example: Jon Jones
proof_token:
type: object
description: >-
Token ensuring verification of payee was performed for the
beneficiary in the request. This token must be used to initiate a
transfer to this beneficiary, validation will fail otherwise. The
token can be used regardless of the VOP match result.
properties:
token:
type: string
description: >-
The proof token value. This token is valid for 23 hours to
initiate a transfer. This limit might change depending on
further security considerations.
example: proof_1234567890abcdef
required:
- token
securitySchemes:
OAuth:
type: oauth2
description: >
Bearer authorization header: `Bearer `, where `` is the
access token received from the authorization server at the end of the
[OAuth 2.0
flow](/get-started/business-api/authentication/oauth/oauth-flow).
flows:
authorizationCode:
refreshUrl: https://oauth.qonto.com/oauth2/token
authorizationUrl: https://oauth.qonto.com/oauth2/auth
scopes:
attachment.read: Retrieve attachments
attachment.write: Upload attachments and remove attachments from transactions
bank_account.write: Create, update and close bank accounts
beneficiary.trust: Trust SEPA beneficiaries
card.read: Retrieve cards
card.write: Create or update cards
client.read: Retrieve clients
client.write: Create clients
client_invoice.write: Create client invoices
client_invoices.read: Retrieve client invoices and credit notes
einvoicing.read: Retrieve e-invoicing settings
embed_auth_link.write: Create Embed auth links
insurance_contract.read: Retrieve insurance contracts
insurance_contract.write: Create and update insurance contracts
internal_transfer.write: >-
Create internal transfers (between 2 Qonto accounts of the same
organization)
international_transfer.write: Create international transfers
membership.read: Retrieve the authentified membership
membership.write: Invite team members
offline_access: Retrieve a refresh token
organization.read: >-
Retrieve organization, bank accounts, transactions, transfers,
beneficiaries, labels, memberships, requests & statements
payment.write: Create external transfers and untrust beneficiaries
payment_link.read: >-
Retrieve payment links, their payments, and the available payment
methods
payment_link.write: >-
Connect to the payment links provider, create and deactivate
payment links
product.read: Retrieve products
product.write: Create products
request_cards.write: Create card requests
request_review.write: Approve or decline requests
request_transfers.write: Create transfer requests
sepa_direct_debit.read: View SEPA Direct Debit payments
sepa_direct_debit.write: Manage SEPA Direct Debit payments
supplier_invoice.read: Retrieve supplier invoices
supplier_invoice.write: Create supplier invoices
team.read: Retrieve teams
team.write: Create teams
terminal.read: View your payment terminals
terminal.write: Configure your terminals and initiate payments
webhook: >-
Receive a notification each time a particular event occurs in
Qonto
tokenUrl: https://oauth.qonto.com/oauth2/token
SecretKey:
type: apiKey
description: cf. [API key](/get-started/business-api/authentication/api-key)
name: Authorization
in: header
````