Verify a SEPA payee

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_body

{
  "match_result": "MATCH_RESULT_MATCH",
  "proof_token": {
    "token": "proof_1234567890abcdef"
  }
}

Verification of Payee

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 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.

POST

sepa

verify_payee

Verify a SEPA payee

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_body

{
  "match_result": "MATCH_RESULT_MATCH",
  "proof_token": {
    "token": "proof_1234567890abcdef"
  }
}

Authorizations

Authorization

string

header

required

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

X-Qonto-Staging-Token

string

Required only for Sandbox API requests; to get one, please sign up to the Developer Portal.

Body

application/json

iban

string

required

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:

"FR7616958000014849440866435"

beneficiary_name

string

required

Name of the beneficiary to verify against the account

Required string length: 1 - 140

Example:

"John Doe"

Response

Verification completed successfully

match_result

enum<string>

Result of the payee verification

Available options:

MATCH_RESULT_MATCH,

MATCH_RESULT_NO_MATCH,

MATCH_RESULT_CLOSE_MATCH,

MATCH_RESULT_NOT_POSSIBLE,

MATCH_RESULT_UNSPECIFIED

Example:

"MATCH_RESULT_MATCH"

matched_name

string | null

The actual name associated with the account (present for close matches)

Example:

"Jon Jones"

proof_token

object

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

Delete a SEPA beneficiary Bulk verify SEPA payees

⌘I