API-Referenz

Verification-of-Payee- API-Dokumentation

Authentifizierung, der Verify-Endpunkt, Request- und Response-Payloads, SEPA-Schema-Match-Codes und Fehlerbehandlung — alles, was ein Entwickler braucht, um die IBAN/Name-Prüfung zu integrieren, mit kopierfertigen JSON- und cURL-Beispielen.

POST {BASE_URL}/vop/v1/verify
Authentifizierung
Bearer Token (OAuth 2.0)
Format
application/json

Basis-URL und API-Zugangsdaten werden beim Onboarding bereitgestellt — kontaktieren Sie uns, um sie zu erhalten.

Die Verification-of-Payee-API ist ein einzelner authentifizierter REST-Endpunkt: Sie senden per POST einen Empfängernamen und eine IBAN und erhalten in Echtzeit ein standardisiertes Match-Ergebnis. Die folgenden Beispiele sind illustrativ; Ihre genaue Basis-URL und Zugangsdaten werden beim Onboarding ausgestellt.

Authentifizierung

Jede Anfrage wird mit einem Bearer Token über HTTPS authentifiziert. Senden Sie das Token im Authorization-Header; Tokens werden pro Umgebung (Sandbox und Produktion) ausgestellt.

Dieselben Zugangsdaten schalten auch das RoxBusiness-Dashboard frei, in dem Sie Ad-hoc-Verifizierungen ohne Code durchführen können.

HTTP-Header 
Authorization: Bearer <YOUR_API_TOKEN>
Content-Type: application/json

Anfrage

Senden Sie per POST einen JSON-Body mit dem Empfängernamen und der IBAN. Für juristische Personen können Sie auch eine Organisationskennung (z. B. eine italienische Partita IVA / Codice Fiscale) und eine optionale external_id zur Abstimmung senden.

Anfrage-Body

Feld Typ Erforderlich Beschreibung
name string Erforderlich Zu verifizierender Empfängername, wie vom Zahler eingegeben.
iban string Erforderlich Ziel-IBAN (vor dem Schema-Aufruf auf Format und Prüfsumme validiert).
account_type enum Optional NATURAL_PERSON oder LEGAL_PERSON. Hilft der antwortenden Bank beim korrekten Abgleich.
organisation_id string Optional USt-IdNr. / Steuernummer für juristische Personen (z. B. Partita IVA). Gegen den eingetragenen Inhaber verifiziert.
external_id string Optional Ihre eigene Referenz-ID, in der Antwort zur Abstimmung zurückgegeben.
Anfrage-Body 
{
  "name": "ACME Trading S.r.l.",
  "iban": "IT60X0542811101000000123456",
  "account_type": "LEGAL_PERSON",
  "organisation_id": "IT01524770524",
  "external_id": "invoice-2025-00842"
}
cURL 
curl -X POST "$BASE_URL/vop/v1/verify" \
  -H "Authorization: Bearer $ROXPAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ACME Trading S.r.l.",
    "iban": "IT60X0542811101000000123456",
    "account_type": "LEGAL_PERSON",
    "organisation_id": "IT01524770524",
    "external_id": "invoice-2025-00842"
  }'

Antwort

Eine 200-Antwort gibt das normalisierte Ergebnis, den SEPA-Schema-Match-Code, den BIC der antwortenden Bank und die Verarbeitungszeit zurück. Bei einer Teilübereinstimmung wird der verifizierte Name in suggested_name zurückgegeben.

Antwort-Body

Feld Typ Beschreibung
verification_id string Eindeutige ID dieser Verifizierung, für Ihren Audit-Trail.
result enum MATCH, CLOSE_MATCH, NO_MATCH oder NOT_APPLICABLE.
scheme_code string Der SEPA-VoP-Schema-Code: MTCH, CMTC, NMTC oder NOAP.
suggested_name string Bei CLOSE_MATCH der verifizierte Kontoinhabername, der dem Zahler vorgeschlagen wird.
responding_bic string BIC des Instituts, das die Verifizierung beantwortet hat.
processing_time_ms integer Zeit, die der antwortende PSP benötigt hat, in Millisekunden.
external_id string Ihre Referenz-ID, unverändert zurückgegeben.
200 OK 
{
  "verification_id": "vop_3f9a1c2e7b",
  "result": "CLOSE_MATCH",
  "scheme_code": "CMTC",
  "suggested_name": "ACME Trading SRL",
  "responding_bic": "BCITITMMXXX",
  "processing_time_ms": 412,
  "external_id": "invoice-2025-00842"
}

Match-Ergebniscodes

Jede Antwort entspricht einem von vier SEPA-VoP-Schema-Codes. Verzweigen Sie auf scheme_code, damit Ihre Logik stabil bleibt.

Code Ergebnis Bedeutung Empfohlene Aktion
MTCH MATCH Der Name stimmt mit dem Kontoinhaber überein. Mit Zuversicht fortfahren.
CMTC CLOSE_MATCH Fast richtig (z. B. Handels- vs. Rechtsname). suggested_name anzeigen; den Zahler um Bestätigung bitten.
NMTC NO_MATCH Der Name gehört nicht zur IBAN. Hartes Stopp — warnen und Auto-Freigabe blockieren.
NOAP NOT_APPLICABLE Die Verifizierung konnte nicht abgeschlossen werden. Den Zahler informieren; ihn entscheiden lassen.

Fehlerbehandlung

NO_MATCH ist ein gültiges 200-Ergebnis, kein Fehler — behandeln Sie es nie als Transportfehler. Echte Fehler verwenden 4xx/5xx-Statuscodes mit einem maschinenlesbaren Fehlercode und einer request_id für den Support.

HTTP Fehlercode Wann es auftritt
400 invalid_iban Die IBAN hat die Format- oder Prüfsummenvalidierung nicht bestanden.
400 missing_field Ein Pflichtfeld (name oder iban) fehlt.
401 unauthorized Fehlendes oder ungültiges Bearer Token.
429 rate_limited Zu viele Anfragen — Backoff anwenden und erneut versuchen.
503 scheme_unavailable Das VoP-Schema / der antwortende PSP ist vorübergehend nicht erreichbar.
400 Bad Request 
{
  "error": "invalid_iban",
  "message": "The 'iban' field failed checksum validation.",
  "request_id": "req_8a2b1f0c"
}

In vier Schritten integrieren

Eine standardmäßige REST-Integration, die sich in Ihren bestehenden Zahlungsfluss einfügt.

  1. 1

    Zugangsdaten erhalten

    Onboarding durchführen und Bearer Token sowie Basis-URL für Sandbox und Produktion erhalten.

  2. 2

    /verify aufrufen

    Empfängername und IBAN per POST senden, mit optionaler external_id und organisation_id.

  3. 3

    scheme_code lesen

    Auf MTCH / CMTC / NMTC / NOAP verzweigen und die verification_id speichern.

  4. 4

    In Ihrer UI handeln

    Dem Zahler ein klares Signal zeigen oder einen Zahlungslauf bzw. ein Mandat vom Ergebnis abhängig machen.

API-Referenz

Entwickler-FAQ

Die ersten Fragen der Integrationsteams.

Ein JSON-Body mit name und iban (erforderlich), plus optional account_type, organisation_id (USt-IdNr./Steuernummer für juristische Personen) und Ihre external_id. Siehe das Anfragebeispiel oben.

NO_MATCH (Schema-Code NMTC) ist eine gültige 200-Antwort, kein Fehler. Behandeln Sie es als hartes Stopp: den Zahler warnen, die Auto-Freigabe blockieren und vor dem Senden eine erneute Prüfung verlangen.

Ja. Tokens werden pro Umgebung ausgestellt, sodass Sie in der Sandbox integrieren und testen können, bevor Sie die Basis-URL auf Produktion umstellen.

Ja — senden Sie organisation_id mit account_type LEGAL_PERSON. Das hilft, wenn der Handelsname vom eingetragenen Namen abweicht.

Senden Sie Ihre eigene external_id in der Anfrage; sie wird unverändert zurückgegeben, und jede Antwort trägt zudem eine eindeutige verification_id.

Weiterlesen

Die Verification-of-Payee-API Überblick, Zielgruppen und Anwendungsfälle. RoxPay Verification of Payee Wie der Dienst auf RoxPay bereitgestellt wird. Glossar VoP-, SEPA- und Schema-Code-Begriffe.

Erhalten Sie Ihre API-Zugangsdaten

Onboarden Sie auf das SEPA-VoP-Schema mit einer REST-Integration und gehen Sie vor Ihrer Frist live.

Mit einem Experten sprechen Über die VoP-API