How to send a SEPA transfer to a trusted beneficiary

Automating payments, such as supplier payouts, salary payments, or refunds to eliminate manual processing time and reduces the risk of human error. In this guide, we will list beneficiaries to find the right recipient, verify the payee identity through the Verification of Payee (VoP) service, and submit the transfer.

Example: A freelance management platform automatically pays contractors every Friday based on approved timesheets, without anyone logging into Qonto manually.

Prerequisites:

At least one beneficiary with status: validated.
Scopes: organization.read, payment.write

Beneficiaries can only be trusted through the Qonto web app, unless you are are an Embed partner with the beneficary.trust scope. Learn more about sensitive scopes.

List SEPA beneficiaries

Retrieve the list of validated beneficiaries and find the one you want to pay. You can filter by IBAN or name to narrow down the results.Endpoint: List SEPA beneficiaries

OAuth scope required: organization.read

Python
Node.js

import requests

BASE_URL = "https://thirdparty.qonto.com/v2"
headers = {"Authorization": "Bearer {your_access_token}"}

response = requests.get(
    f"{BASE_URL}/sepa/beneficiaries",
    headers=headers,
    params={
        "iban[]": "FR7616798000010000005663951",  # Filter by IBAN
        "status[]": "validated",
        "per_page": 25,
    },
)
response.raise_for_status()

beneficiaries = response.json()["beneficiaries"]
beneficiary = beneficiaries[0]
beneficiary_id = beneficiary["id"]
beneficiary_name = beneficiary["name"]
print(f"Found beneficiary: {beneficiary['name']} ({beneficiary_id})")

const BASE_URL = "https://thirdparty.qonto.com/v2";
const headers = { Authorization: "Bearer {your_access_token}" };

const params = new URLSearchParams();
params.append("iban[]", "FR7616798000010000005663951"); // Filter by IBAN
params.append("status[]", "validated");
params.append("per_page", 25);

const response = await fetch(`${BASE_URL}/sepa/beneficiaries?${params}`, { headers });
if (!response.ok) throw new Error(`HTTP ${response.status}`);

const { beneficiaries } = await response.json();
const beneficiary = beneficiaries[0];
const beneficiaryId = beneficiary.id;
const beneficiaryName = beneficiary.name;
console.log(`Found beneficiary: ${beneficiaryName} (${beneficiaryId})`);

Verify the SEPA payee (VoP)

Before creating a transfer, you must verify the payee through Verification of Payee (VoP). This returns a proof_token that you will include in the transfer request.Endpoint: Verify a SEPA payee

OAuth scope required: payment.write

The proof_token is valid for 23 hours only. Always verify immediately before creating the transfer. Excessive verifications not followed by a transfer may be rate-limited.

Python
Node.js

response = requests.post(
    f"{BASE_URL}/sepa/verify_payee",
    headers={**headers, "Content-Type": "application/json"},
    json={
        "iban": "FR7616958000014849440866435",
        "beneficiary_name": beneficiary_name,
    },
)
response.raise_for_status()

data = response.json()
proof_token = data["proof_token"]["token"]
match_result = data["match_result"]

# match_result values:
# MATCH_RESULT_MATCH       → proceed with confidence
# MATCH_RESULT_CLOSE_MATCH → consider reviewing the name
# MATCH_RESULT_NO_MATCH    → caution, consider skipping transfer
# MATCH_RESULT_NOT_POSSIBLE → verification unavailable for this IBAN
print(f"Verification result: {match_result}")

const verifyResponse = await fetch(`${BASE_URL}/sepa/verify_payee`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({
    iban: "FR7616958000014849440866435",
    beneficiary_name: beneficiaryName,
  }),
});
if (!verifyResponse.ok) throw new Error(`HTTP ${verifyResponse.status}`);

const response = await verifyResponse.json();
const proofToken = response.proof_token.token;
const matchResult = response.match_result;

// match_result values:
// MATCH_RESULT_MATCH       → proceed with confidence
// MATCH_RESULT_CLOSE_MATCH → consider reviewing the name
// MATCH_RESULT_NO_MATCH    → caution, consider skipping transfer
// MATCH_RESULT_NOT_POSSIBLE → verification unavailable for this IBAN
console.log(`Verification result: ${matchResult}`);

Create the SEPA transfer

Submit the transfer using the beneficiary_id from Step 1 and the proof_token from Step 2.Endpoint: Create a SEPA transfer

OAuth scope required: payment.write

Do not forget to include the X-Qonto-Idempotency-Key header to prevent duplicate transfers in case of network errors. See Idempotent requests.

To retrieve your bank_account_id, needed in this request, call GET /v2/organization or GET /v2/banks_accounts, the responses include a bank_accounts array, each with an id field.

Transfers above €30,000 require at least one attachment. Upload the attachment first via POST /v2/attachments and include its ID in the request.

Python
Node.js

import uuid

response = requests.post(
    f"{BASE_URL}/sepa/transfers",
    headers={
        **headers,
        "Content-Type": "application/json",
        "X-Qonto-Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "vop_proof_token": proof_token,
        "transfer": {
            "bank_account_id": "{your_bank_account_id}",
            "reference": "Invoice payment INV-001",
            "amount": "1100.50",
            "beneficiary_id": beneficiary_id,
            # "scheduled_date": "2026-04-01",  # Optional: ISO 8601 date
            # "attachment_ids": ["uuid-1"],     # Required if amount > €30,000
        },
    },
)
response.raise_for_status()

transfer = response.json()["transfer"]
print(f"Transfer created: {transfer['id']} — status: {transfer['status']}")

const { randomUUID } = await import("node:crypto");

const transferResponse = await fetch(`${BASE_URL}/sepa/transfers`, {
  method: "POST",
  headers: {
    ...headers,
    "Content-Type": "application/json",
    "X-Qonto-Idempotency-Key": randomUUID(),
  },
  body: JSON.stringify({
    vop_proof_token: proofToken,
    transfer: {
      bank_account_id: "{your_bank_account_id}",
      reference: "Invoice payment INV-001",
      amount: "1100.50",
      beneficiary_id: beneficiaryId,
      // scheduled_date: "2026-04-01",  // Optional: ISO 8601 date
      // attachment_ids: ["uuid-1"],     // Required if amount > €30,000
    },
  }),
});
if (!transferResponse.ok) throw new Error(`HTTP ${transferResponse.status}`);

const { transfer } = await transferResponse.json();
console.log(`Transfer created: ${transfer.id} — status: ${transfer.status}`);

Instant transfer limits: Instant transfers fall back to standard SEPA if the amount exceeds the limit. For trusted beneficiaries: €10,000 per transfer or €50,000 within 24h.

Example output:

[Step 1] GET /sepa/beneficiaries
  Found beneficiary: Admin (0199cd7a-xxxx-xxxx-xxxx-xxxxxxxxxxxx)

[Step 2] POST /sepa/verify_payee
  Verification result: MATCH_RESULT_MATCH
  proof_token: 1|1|1773938795|MEUCI… (valid 23h)

[Step 3] POST /sepa/transfers
  Transfer created: 019d06fd-xxxx-xxxx-xxxx-xxxxxxxxxxxx — status: pending

We now have a submitted SEPA transfer. The transfer id and status in the response confirm it has been accepted for processing.

General

Business API

Onboarding API

SDKs & Libraries

How to send a SEPA transfer to a trusted beneficiary

List SEPA beneficiaries

Verify the SEPA payee (VoP)

Create the SEPA transfer