API-referentie

De RoxPay Verification of Payee-API

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 kant-en-klare JSON- en cURL-voorbeelden.

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

Basis-URL en API-toegangsgegevens worden bij onboarding verstrekt — neem contact met ons op om ze te ontvangen.

De Verification of Payee-API is een enkel geauthenticeerd REST-endpoint: u verstuurt per POST een begunstigdenaam en een IBAN en ontvangt in realtime een gestandaardiseerd matchresultaat. De volgende voorbeelden zijn illustratief; uw exacte basis-URL en toegangsgegevens worden bij onboarding verstrekt.

Authenticatie

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

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

Stuur per POST een JSON-body met de begunstigdenaam en de IBAN. Voor rechtspersonen kunt u ook een organisatiekenmerk (bijv. een Italiaans Partita IVA-/Codice Fiscale-nummer) en een optionele external_id meesturen voor afstemming.

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 bij een correcte vergelijking.
organisation_id string Optioneel Btw-/fiscaal nummer voor rechtspersonen (bijv. Partita IVA). Wordt geverifieerd tegen de geregistreerde houder.
external_id string Optioneel Uw eigen referentie-id, in het antwoord teruggegeven voor afstemming.
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"
  }'

Antwoord

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.

Antwoord-body

Veld Type Beschrijving
verification_id string Uniek ID van deze verificatie, voor uw audittrail.
result enum MATCH, CLOSE_MATCH, NO_MATCH of NOT_APPLICABLE.
scheme_code string De SEPA-VoP-Schema-Code: 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 heeft beantwoord.
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. Met vertrouwen doorgaan.
CMTC CLOSE_MATCH Bijna juist (bijv. handelsnaam versus officiële naam). Toon suggested_name; vraag de betaler te bevestigen.
NMTC NO_MATCH De naam hoort niet bij de IBAN. Harde stop — waarschuw en blokkeer automatische 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 is niet geslaagd voor de formaat- of controlegetalvalidatie.
400 missing_field Een verplicht veld (name of iban) ontbreekt.
401 unauthorized Ontbrekend of ongeldig bearer token.
429 rate_limited Te veel verzoeken — pas backoff toe en probeer opnieuw.
503 scheme_unavailable Het VoP-schema / de antwoordende PSP is tijdelijk niet bereikbaar.
400 Bad Request 
{
  "error": "invalid_iban",
  "message": "The 'iban' field failed checksum validation.",
  "request_id": "req_8a2b1f0c"
}

In vier stappen integreren

Een standaard REST-integratie die past binnen uw bestaande betaalproces.

  1. 1

    Verkrijg inloggegevens

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

  2. 2

    /verify aanroepen

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

  3. 3

    scheme_code lezen

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

  4. 4

    Verwerk het 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 geldig 200-antwoord, geen fout. Behandel het als een harde stop: waarschuw de betaler, blokkeer automatische goedkeuring en vraag een nieuwe controle vóór verzending.

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

Ja — stuur organisation_id mee met account_type LEGAL_PERSON. Dit helpt wanneer de handelsnaam afwijkt van de geregistreerde naam.

Stuur uw eigen external_id mee in de aanvraag; deze wordt ongewijzigd teruggegeven, en elk antwoord bevat bovendien een uniek verification_id.

Verder lezen

De Verification of Payee-API Overzicht, doelgroepen en toepassingen. De Verordening instantbetalingen en de VoP Hoe de dienst bij RoxPay wordt geleverd. Woordenlijst VoP-, SEPA- en schemacode-termen.

Ontvang uw API-toegangsgegevens

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

Praat met een expert Over de VoP-API