curl --request POST \
--url https://thirdparty.qonto.com/v2/sepa/verify_payee \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"iban": "FR7616958000014849440866435",
"beneficiary_name": "Default Match Person"
}
'import requests
url = "https://thirdparty.qonto.com/v2/sepa/verify_payee"
payload = {
"iban": "FR7616958000014849440866435",
"beneficiary_name": "Default Match Person"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({iban: 'FR7616958000014849440866435', beneficiary_name: 'Default Match Person'})
};
fetch('https://thirdparty.qonto.com/v2/sepa/verify_payee', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://thirdparty.qonto.com/v2/sepa/verify_payee",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'iban' => 'FR7616958000014849440866435',
'beneficiary_name' => 'Default Match Person'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://thirdparty.qonto.com/v2/sepa/verify_payee"
payload := strings.NewReader("{\n \"iban\": \"FR7616958000014849440866435\",\n \"beneficiary_name\": \"Default Match Person\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://thirdparty.qonto.com/v2/sepa/verify_payee")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"iban\": \"FR7616958000014849440866435\",\n \"beneficiary_name\": \"Default Match Person\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://thirdparty.qonto.com/v2/sepa/verify_payee")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"iban\": \"FR7616958000014849440866435\",\n \"beneficiary_name\": \"Default Match Person\"\n}"
response = http.request(request)
puts response.read_bodyVerify 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 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
200response withMATCH_RESULT_NOT_POSSIBLEmeans the responding bank was successfully contacted but could not perform the name verification (e.g., the account type does not support Verification of Payee). Aproof_tokenis included. - A
400error with codes likeBAD_REQUEST_ERROR_RESPONDING_BANK_NOT_AVAILABLE,BAD_REQUEST_ERROR_5XX_RESPONDING_BANK, orBAD_REQUEST_ERROR_RESPONDING_BANK_INVALID_RESPONSEmeans the responding bank returned an unexpected response. Aproof_tokenis included in the errormeta. - A
503error withBAD_GATEWAY_ERROR_RESPONDING_BANKorGATEWAY_TIMEOUT_ERROR_RESPONDING_BANKmeans the responding bank could not be reached or returned a server error. This is a transient issue — retry after a short delay. Aproof_tokenis included in the errormeta.
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.
curl --request POST \
--url https://thirdparty.qonto.com/v2/sepa/verify_payee \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"iban": "FR7616958000014849440866435",
"beneficiary_name": "Default Match Person"
}
'import requests
url = "https://thirdparty.qonto.com/v2/sepa/verify_payee"
payload = {
"iban": "FR7616958000014849440866435",
"beneficiary_name": "Default Match Person"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({iban: 'FR7616958000014849440866435', beneficiary_name: 'Default Match Person'})
};
fetch('https://thirdparty.qonto.com/v2/sepa/verify_payee', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://thirdparty.qonto.com/v2/sepa/verify_payee",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'iban' => 'FR7616958000014849440866435',
'beneficiary_name' => 'Default Match Person'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://thirdparty.qonto.com/v2/sepa/verify_payee"
payload := strings.NewReader("{\n \"iban\": \"FR7616958000014849440866435\",\n \"beneficiary_name\": \"Default Match Person\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://thirdparty.qonto.com/v2/sepa/verify_payee")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"iban\": \"FR7616958000014849440866435\",\n \"beneficiary_name\": \"Default Match Person\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://thirdparty.qonto.com/v2/sepa/verify_payee")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"iban\": \"FR7616958000014849440866435\",\n \"beneficiary_name\": \"Default Match Person\"\n}"
response = http.request(request)
puts response.read_bodyAuthorizations
Bearer authorization header: Bearer <token>, where <token> is the access token received from the authorization server at the end of the OAuth 2.0 flow.
Headers
Required only for Sandbox API requests; to get one, please sign up to the Developer Portal.
Body
Response
Verification completed successfully
Result of the payee verification
MATCH_RESULT_MATCH, MATCH_RESULT_NO_MATCH, MATCH_RESULT_CLOSE_MATCH, MATCH_RESULT_NOT_POSSIBLE, MATCH_RESULT_UNSPECIFIED "MATCH_RESULT_MATCH"
The actual name associated with the account (present for close matches)
"Jon Jones"
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.
Show child attributes
Show child attributes
Was this page helpful?