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"
  }
}

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"
  }
}

Authentication: API key OAuth 2.0
Scope: payment.write Sensitive

Related guide: Verification of Payee

You can also use the Sandbox environment to test the endpoint with mocked IBANs.

Token requirementThe 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 limitsA 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 resultsIt 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.

The proof_token provided in error responses allows you to proceed with the transfer if needed, but the payee name was not verified. See why bank errors are not match results.

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

Introduction

Authentication

Organization & accounts

Transactions & statements

Transfers

Getting paid

Cards

Invoicing

Spend management

Cash flow

Webhooks

Partner endpoints

Verify a SEPA payee

Authorizations

Headers

Body

Response