API-referentie

Verification of Payee API-documentatie

Authenticatie, het verify-endpoint, request- en response-payloads, SEPA-schema-matchcodes en foutafhandeling — alles wat een ontwikkelaar nodig heeft om de IBAN/naam-controle te integreren, met kopieerklare JSON- en cURL-voorbeelden.

POST {BASE_URL}/vop/v1/verify
Authenticatie
Bearer token (OAuth 2.0)
Formaat
application/json

Basis-URL en API-inloggegevens worden bij de onboarding verstrekt — neem contact op om ze te krijgen.

De Verification of Payee-API is één geauthenticeerd REST-endpoint: u POST een begunstigdenaam en IBAN en ontvangt in realtime een gestandaardiseerd matchresultaat. De onderstaande voorbeelden zijn illustratief; uw exacte basis-URL en inloggegevens worden uitgegeven tijdens de onboarding.

Authenticatie

Elke aanvraag wordt geauthenticeerd met een bearer token via HTTPS. Stuur het token in de Authorization-header; tokens worden per omgeving uitgegeven (sandbox en productie).

Dezelfde inloggegevens ontgrendelen ook het RoxBusiness-dashboard, waar u ad-hocverificaties kunt uitvoeren zonder code te schrijven.

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

Aanvraag

POST een JSON-body met de naam van de begunstigde en de IBAN. Voor rechtspersonen kunt u ook een organisatie-identificatie (bijv. een Italiaanse Partita IVA / Codice Fiscale) en een optionele external_id voor reconciliatie sturen.

Aanvraag-body

Veld Type Verplicht Beschrijving
name string Verplicht Te verifiëren naam van de begunstigde, zoals de betaler die invoerde.
iban string Verplicht Bestemmings-IBAN (gevalideerd op formaat en checksum vóór de schema-oproep).
account_type enum Optioneel NATURAL_PERSON of LEGAL_PERSON. Helpt de antwoordende bank correct te matchen.
organisation_id string Optioneel Btw-nummer / fiscaal nummer voor rechtspersonen (bijv. Partita IVA). Geverifieerd tegen de geregistreerde houder.
external_id string Optioneel Uw eigen referentie-id, teruggegeven in de respons voor reconciliatie.
Aanvraag-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"
  }'

Respons

Een 200-respons geeft het genormaliseerde resultaat, de SEPA-schema-matchcode, de BIC van de antwoordende bank en de verwerkingstijd terug. Bij een gedeeltelijke overeenkomst wordt de geverifieerde naam teruggegeven in suggested_name.

Respons-body

Veld Type Beschrijving
verification_id string Unieke id voor deze verificatie, voor uw audittrail.
result enum MATCH, CLOSE_MATCH, NO_MATCH of NOT_APPLICABLE.
scheme_code string De SEPA-VoP-schemacode: MTCH, CMTC, NMTC of NOAP.
suggested_name string Bij CLOSE_MATCH de geverifieerde naam van de rekeninghouder om aan de betaler voor te stellen.
responding_bic string BIC van de instelling die de verificatie beantwoordde.
processing_time_ms integer Tijd die de antwoordende PSP nodig had, in milliseconden.
external_id string Uw referentie-id, ongewijzigd teruggegeven.
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"
}

Matchresultaatcodes

Elke respons komt overeen met een van de vier SEPA-VoP-schemacodes. Vertak op scheme_code zodat uw logica stabiel blijft.

Code Resultaat Betekenis Aanbevolen actie
MTCH MATCH De naam komt overeen met de rekeninghouder. Ga met vertrouwen door.
CMTC CLOSE_MATCH Bijna juist (bijv. handelsnaam vs. juridische naam). Toon suggested_name; vraag de betaler te bevestigen.
NMTC NO_MATCH De naam hoort niet bij de IBAN. Harde stop — waarschuw en blokkeer auto-goedkeuring.
NOAP NOT_APPLICABLE De verificatie kon niet worden voltooid. Informeer de betaler; laat hem beslissen.

Foutafhandeling

NO_MATCH is een geldig 200-resultaat, geen fout — behandel het nooit als een transportfout. Echte fouten gebruiken 4xx/5xx-statuscodes met een machineleesbare foutcode en een request_id voor support.

HTTP Foutcode Wanneer het gebeurt
400 invalid_iban De IBAN faalde de formaat- of checksumvalidatie.
400 missing_field Een verplicht veld (name of iban) ontbreekt.
401 unauthorized Ontbrekend of ongeldig bearer token.
429 rate_limited Te veel aanvragen — pas backoff toe en probeer opnieuw.
503 scheme_unavailable Het VoP-schema / de antwoordende PSP is tijdelijk onbereikbaar.
400 Bad Request 
{
  "error": "invalid_iban",
  "message": "The 'iban' field failed checksum validation.",
  "request_id": "req_8a2b1f0c"
}

Integreer in vier stappen

Een standaard REST-integratie die in uw bestaande betaalstroom past.

  1. 1

    Verkrijg inloggegevens

    Doorloop de onboarding en ontvang uw bearer token en basis-URL voor sandbox en productie.

  2. 2

    Roep /verify aan

    POST de naam van de begunstigde en de IBAN, met een optionele external_id en organisation_id.

  3. 3

    Lees scheme_code

    Vertak op MTCH / CMTC / NMTC / NOAP en sla de verification_id op.

  4. 4

    Handel in uw UI

    Toon een duidelijk signaal aan de betaler, of maak een betaalrun of mandaat afhankelijk van het resultaat.

API-referentie

Ontwikkelaars-FAQ

De eerste vragen van integratieteams.

Een JSON-body met name en iban (verplicht), plus optioneel account_type, organisation_id (btw/fiscaal nummer voor rechtspersonen) en uw external_id. Zie het aanvraagvoorbeeld hierboven.

NO_MATCH (schemacode NMTC) is een geldige 200-respons, geen fout. Behandel het als een harde stop: waarschuw de betaler, blokkeer auto-goedkeuring en eis een hercontrole vóór verzending.

Ja. Tokens worden per omgeving uitgegeven, zodat u in sandbox kunt integreren en testen voordat u de basis-URL naar productie omschakelt.

Ja — stuur organisation_id met account_type LEGAL_PERSON. Dat helpt wanneer de handelsnaam verschilt van de geregistreerde naam.

Stuur uw eigen external_id in de aanvraag; deze wordt ongewijzigd teruggegeven, en elke respons draagt ook een unieke verification_id.

Lees verder

De Verification of Payee API Overzicht, doelgroepen en use cases. RoxPay Verification of Payee Hoe de dienst op RoxPay wordt geleverd. Woordenlijst VoP-, SEPA- en schemacode-termen.

Verkrijg uw API-inloggegevens

Onboard op het SEPA-VoP-schema met één REST-integratie en ga live vóór uw deadline.

Praat met een expert Over de VoP-API