> ## 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.
# Bulk verify SEPA payees
> OAuth scope: `payment.write`
Verifies multiple payees information by matching IBAN and beneficiary name for each request.
Returns match results for each verification request, including success responses and error codes
for failed verifications. This endpoint allows processing multiple payee verifications in a single request.
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.
Please note the token will only be valid for the exact set of IBANs included in this request.
**Rate limits**
A verification is only intended to be used before initiating SEPA transfers. Rate limits will apply to verifications that are not followed by a transfer initiation. Please perform verification for transfers that will be initiated shortly.
## OpenAPI
````yaml POST /v2/sepa/bulk_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/bulk_verify_payee:
post:
tags:
- SEPA Transfers
summary: Bulk verify SEPA payees
description: >
OAuth scope: `payment.write`
Verifies multiple payees information by matching IBAN and beneficiary
name for each request.
Returns match results for each verification request, including success
responses and error codes
for failed verifications. This endpoint allows processing multiple payee
verifications in a single request.
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.
Please note the token will only be valid for the exact set of IBANs included in this request.
**Rate limits**
A verification is only intended to be used before initiating SEPA transfers. Rate limits will apply to verifications that are not followed by a transfer initiation. Please perform verification for transfers that will be initiated shortly.
operationId: bulkVerifyPayee
parameters:
- $ref: '#/components/parameters/X-Qonto-Staging-Token'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BulkVerifyPayeeRequest'
examples:
bulk_verification:
summary: Bulk payee verification request
value:
requests:
- id: req_001
beneficiary_name: John Doe
iban: FR1420041010050500013M02606
- id: req_002
beneficiary_name: Jane Smith
iban: GB82WEST12345698765432
- id: req_003
beneficiary_name: ACME Corp
iban: DE89370400440532013000
responses:
'200':
description: >-
Bulk verification completed (may contain mixed success/error
results)
content:
application/json:
schema:
$ref: '#/components/schemas/BulkVerifyPayeeResponse'
examples:
mixed_results:
summary: Mixed results with success and errors
value:
proof_token:
token: proof_1234567890abcdef
requests:
- id: req_001
response:
match_result: MATCH_RESULT_MATCH
- id: req_002
response:
match_result: MATCH_RESULT_CLOSE_MATCH
matched_name: J. Smith
- id: req_003
error_code: >-
SINGLE_REQUEST_ERROR_CODE_BAD_REQUEST_ERROR_RESPONDING_BANK_NOT_AVAILABLE
'400':
description: Bad request - Invalid input parameters
content:
application/json:
schema:
type: object
required:
- errors
properties:
errors:
type: array
items:
$ref: '#/components/schemas/400-Verify-Payee-BadRequestError'
minItems: 1
examples:
bad_request:
summary: Invalid request format
value:
errors:
- code: BAD_REQUEST_ERROR_FORMAT
status: '400'
detail: Repeated ID in requests
source:
parameter: requests
meta:
proof_token:
token: proof_1234567890abcdef
'500':
description: Internal server error
content:
application/json:
schema:
type: object
required:
- errors
properties:
errors:
type: array
items:
$ref: >-
#/components/schemas/500-Verify-Payee-InternalServerError
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: Responding bank returned an unexpected error
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:
$ref: >-
#/components/schemas/501-Verify-Payee-NotImplementedError
minItems: 1
examples:
not_implemented:
summary: Feature not available
value:
errors:
- code: NOT_IMPLEMENTED_ERROR_FEATURE_NOT_AVAILABLE
status: '501'
detail: Bulk verification feature is not available
'503':
description: Service unavailable - responding bank error
content:
application/json:
schema:
type: object
required:
- errors
properties:
errors:
type: array
items:
$ref: >-
#/components/schemas/503-Verify-Payee-ServiceUnavailableError
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
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
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:
BulkVerifyPayeeRequest:
type: object
required:
- requests
properties:
requests:
type: array
description: List of verification requests to be processed in bulk
items:
$ref: '#/components/schemas/BulkSingleRequest'
minItems: 1
maxItems: 400
BulkVerifyPayeeResponse:
type: object
required:
- requests
- proof_token
properties:
proof_token:
type: object
description: >-
Token ensuring verification of payee was performed for the set of
requests. This token must be used to initiate a bulk transfer to the
exact same set of payees, 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
requests:
type: array
description: List of verification request results
items:
$ref: '#/components/schemas/BulkSingleRequestResult'
400-Verify-Payee-BadRequestError:
type: object
description: Error object for 400 Bad Request responses
allOf:
- $ref: '#/components/schemas/Verify-Payee-Error'
- type: object
properties:
code:
type: string
description: >-
Error code indicating the specific type of error for 400
responses
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
status:
enum:
- '400'
500-Verify-Payee-InternalServerError:
type: object
description: Error object for 500 Internal Server Error responses
allOf:
- $ref: '#/components/schemas/Verify-Payee-Error'
- type: object
properties:
code:
type: string
description: >-
Error code indicating the specific type of error for 500
responses
enum:
- INTERNAL_SERVER_ERROR_UNSPECIFIED
- INTERNAL_SERVER_ERROR_4XX_RESPONDING_BANK
status:
enum:
- '500'
501-Verify-Payee-NotImplementedError:
type: object
description: Error object for 501 Not Implemented responses
allOf:
- $ref: '#/components/schemas/Verify-Payee-Error'
- type: object
properties:
code:
type: string
description: >-
Error code indicating the specific type of error for 501
responses
enum:
- NOT_IMPLEMENTED_ERROR_UNSPECIFIED
- NOT_IMPLEMENTED_ERROR_FEATURE_NOT_AVAILABLE
status:
enum:
- '501'
503-Verify-Payee-ServiceUnavailableError:
type: object
description: Error object for 503 Service Unavailable responses
allOf:
- $ref: '#/components/schemas/Verify-Payee-Error'
- type: object
properties:
code:
type: string
description: >-
Error code indicating the specific type of error for 503
responses
enum:
- BAD_GATEWAY_ERROR_RESPONDING_BANK
- GATEWAY_TIMEOUT_ERROR_RESPONDING_BANK
status:
enum:
- '503'
BulkSingleRequest:
type: object
required:
- id
- beneficiary_name
- iban
properties:
id:
type: string
description: >-
Unique identifier for the request per verification. This key is used
to assist in matching the response to the request.
example: req_001
beneficiary_name:
type: string
description: Beneficiary name to be verified
example: John Doe
minLength: 1
maxLength: 140
iban:
type: string
description: IBAN of the beneficiary account to be verified
pattern: ^[A-Z]{2}[0-9]{2}[A-Z0-9]{4}[0-9]{7}([A-Z0-9]?){0,16}$
example: FR1420041010050500013M02606
BulkSingleRequestResult:
type: object
required:
- id
- beneficiary_name
- iban
properties:
id:
type: string
description: Unique identifier of the request
example: req_001
beneficiary_name:
type: string
description: Beneficiary name that was verified
example: John Doe
iban:
type: string
description: IBAN that was verified
example: FR1420041010050500013M02606
response:
oneOf:
- $ref: '#/components/schemas/BulkSingleRequestVerifyPayeeResponse'
- type: 'null'
description: Response if the verification succeeded
error:
type:
- object
- 'null'
properties:
code:
description: Error code if the verification failed
enum:
- SINGLE_REQUEST_ERROR_CODE_ERROR_UNSPECIFIED
- SINGLE_REQUEST_ERROR_CODE_BAD_REQUEST_ERROR_FORMAT
- >-
SINGLE_REQUEST_ERROR_CODE_BAD_REQUEST_ERROR_RESPONDING_BANK_NOT_AVAILABLE
- SINGLE_REQUEST_ERROR_CODE_BAD_GATEWAY_ERROR_RESPONDING_BANK
- >-
SINGLE_REQUEST_ERROR_CODE_GATEWAY_TIMEOUT_ERROR_RESPONDING_BANK
- SINGLE_REQUEST_ERROR_CODE_INTERNAL_SERVER_ERROR
- >-
SINGLE_REQUEST_ERROR_CODE_BAD_REQUEST_ERROR_RESPONDING_BANK_INVALID_RESPONSE
example: >-
SINGLE_REQUEST_ERROR_CODE_BAD_REQUEST_ERROR_RESPONDING_BANK_INVALID_RESPONSE
Verify-Payee-Error:
type: object
description: |
Individual error object following the JSON API specification.
Error codes are prefixed by their corresponding HTTP status code:
- BAD_REQUEST_ERROR_* → 400 Bad Request
- INTERNAL_SERVER_ERROR_* → 500 Internal Server Error
- GATEWAY_TIMEOUT_ERROR_* → 504 Gateway Timeout
- NOT_IMPLEMENTED_ERROR_* → 501 Not Implemented
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
code:
type:
- string
- 'null'
description: |
Error code indicating the specific type of error.
The prefix indicates the HTTP status code that will be returned:
- BAD_REQUEST_ERROR_* → 400
- INTERNAL_SERVER_ERROR_* → 500
- GATEWAY_TIMEOUT_ERROR_* → 504
- NOT_IMPLEMENTED_ERROR_* → 501
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:
$ref: '#/components/schemas/Verify-Payee-ErrorSource'
meta:
type:
- object
- 'null'
description: An object containing non-standard meta-information about the error
properties:
proof_token:
type: object
description: >-
Token representing proof of a verification attempt. This token
is valid for 23 hours to initiate a transfer. This limit might
change depending on further security considerations.
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
additionalProperties: true
additionalProperties: false
BulkSingleRequestVerifyPayeeResponse:
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
Verify-Payee-ErrorSource:
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
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
````