API-referencia

Verification of Payee API dokumentáció

Hitelesítés, a verify végpont, kérés- és válaszüzenetek, a SEPA séma egyezési kódjai és a hibakezelés - minden, amire egy fejlesztőnek szüksége van az IBAN/név ellenőrzés integrálásához, másolható JSON- és cURL-példákkal.

POST {BASE_URL}/vop/v1/verify
Hitelesítés
Bearer token (OAuth 2.0)
Formátum
application/json

Az alap URL-t és az API hitelesítő adatait az onboarding során adjuk át - vedd fel velünk a kapcsolatot, hogy megkapd őket.

A Verification of Payee API egyetlen hitelesített REST végpont: POST kérésben elküldöd a kedvezményezett nevét és IBAN-ját, és valós időben megkapod a szabványos egyezési eredményt. Az alábbi példák szemléltető jellegűek; a pontos alap URL-t és a hitelesítő adatokat az onboarding során kapod meg.

Hitelesítés

Minden kérést bearer token hitelesít HTTPS felett. A tokent az Authorization fejlécben küldd el; a tokenek környezetenként (sandbox és éles) külön kerülnek kiadásra.

Ugyanezek a hitelesítő adatok nyitják meg a RoxBusiness irányítópultot is, ahol kód írása nélkül futtathatsz eseti ellenőrzéseket.

HTTP fejlécek 
Authorization: Bearer <YOUR_API_TOKEN>
Content-Type: application/json

Kérés

POST kérésben küldj egy JSON törzset a kedvezményezett nevével és IBAN-jával. Jogi személyeknél elküldheted a szervezet azonosítóját is (pl. olasz Partita IVA / Codice Fiscale), valamint egy opcionális external_id mezőt az egyeztetéshez.

Kéréstörzs

Mező Típus Kötelező Leírás
name string Kötelező Az ellenőrizendő kedvezményezett neve, ahogy a fizető megadta.
iban string Kötelező A cél IBAN (a séma hívása előtt formátum és ellenőrző összeg szerint validálva).
account_type enum Opcionális NATURAL_PERSON vagy LEGAL_PERSON. Segít a válaszadó banknak a helyes egyeztetésben.
organisation_id string Opcionális Adószám / adóazonosító jogi személyeknél (pl. Partita IVA). A nyilvántartott számlatulajdonoshoz ellenőrizzük.
external_id string Opcionális A saját hivatkozási azonosítód, amelyet a válaszban visszakapsz az egyeztetéshez.
Kéréstörzs 
{
  "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"
  }'

Válasz

A 200-as válasz visszaadja a normalizált eredményt, a SEPA séma egyezési kódját, a válaszadó bank BIC-kódját és a feldolgozási időt. Közeli egyezés esetén az ellenőrzött név a suggested_name mezőben érkezik vissza.

Választörzs

Mező Típus Leírás
verification_id string Az ellenőrzés egyedi azonosítója, az auditnyomvonaladhoz.
result enum MATCH, CLOSE_MATCH, NO_MATCH vagy NOT_APPLICABLE.
scheme_code string A SEPA VoP séma kódja: MTCH, CMTC, NMTC vagy NOAP.
suggested_name string CLOSE_MATCH esetén az ellenőrzött számlatulajdonos neve, amelyet a fizetőnek javasolhatsz.
responding_bic string Az ellenőrzésre válaszoló intézmény BIC-kódja.
processing_time_ms integer A válaszadó PSP által igénybe vett idő, ezredmásodpercben.
external_id string A hivatkozási azonosítód, változatlanul visszaküldve.
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"
}

Egyezési eredménykódok

Minden válasz a SEPA VoP séma négy kódjának egyikéhez tartozik. A scheme_code alapján ágaztass, így a logikád stabil marad.

Kód Eredmény Jelentés Javasolt teendő
MTCH MATCH A név megegyezik a számlatulajdonossal. Folytasd magabiztosan.
CMTC CLOSE_MATCH Majdnem pontos (pl. kereskedelmi név a jogi név helyett). Mutasd a suggested_name értéket; kérd a fizető megerősítését.
NMTC NO_MATCH A név nem ehhez az IBAN-hoz tartozik. Kemény megállítás - figyelmeztesd a fizetőt, és blokkold az automatikus jóváhagyást.
NOAP NOT_APPLICABLE Az ellenőrzést nem sikerült elvégezni. Tájékoztasd a fizetőt; hagyd, hogy ő döntsön.

Hibakezelés

A NO_MATCH érvényes 200-as eredmény, nem hiba - soha ne kezeld átviteli hibaként. A valódi hibák 4xx/5xx állapotkódot használnak géppel olvasható hibakóddal és egy request_id azonosítóval a támogatáshoz.

HTTP Hibakód Mikor fordul elő
400 invalid_iban Az IBAN nem felelt meg a formátum- vagy ellenőrzőösszeg-validációnak.
400 missing_field Hiányzik egy kötelező mező (name vagy iban).
401 unauthorized Hiányzó vagy érvénytelen bearer token.
429 rate_limited Túl sok kérés - alkalmazz visszalépést (backoff), és próbáld újra.
503 scheme_unavailable A VoP séma / a válaszadó PSP átmenetileg nem elérhető.
400 Bad Request 
{
  "error": "invalid_iban",
  "message": "The 'iban' field failed checksum validation.",
  "request_id": "req_8a2b1f0c"
}

Integrálás négy lépésben

Szabványos REST integráció, amely beilleszthető a meglévő fizetési folyamatodba.

  1. 1

    Szerezd meg a hitelesítő adatokat

    Végezd el az onboardingot, és kapd meg a bearer tokent és az alap URL-t sandboxhoz és éles környezethez.

  2. 2

    Hívd a /verify végpontot

    POST kérésben küldd el a kedvezményezett nevét és IBAN-ját, opcionális external_id és organisation_id mezővel.

  3. 3

    Olvasd ki a scheme_code értéket

    Ágaztass MTCH / CMTC / NMTC / NOAP szerint, és tárold a verification_id azonosítót.

  4. 4

    Cselekedj a felületedben

    Mutass egyértelmű jelzést a fizetőnek, vagy tedd az eredménytől függővé a fizetési köteget vagy a felhatalmazást.

API-referencia

Fejlesztői GYIK

A kérdések, amelyeket az integrációs csapatok először tesznek fel.

Egy JSON törzs a name és iban mezővel (kötelező), valamint opcionális account_type, organisation_id (adószám / adóazonosító jogi személyeknél) és a saját external_id meződdel. Lásd a fenti kérési példát.

A NO_MATCH (NMTC sémakód) érvényes 200-as válasz, nem hiba. Kezeld kemény megállításként: figyelmeztesd a fizetőt, blokkold az automatikus jóváhagyást, és küldés előtt kérj új ellenőrzést.

Igen. A tokenek környezetenként külön kerülnek kiadásra, így a sandboxban integrálhatsz és tesztelhetsz, mielőtt az alap URL-t élesre váltod.

Igen - küldd el az organisation_id mezőt LEGAL_PERSON account_type értékkel. Ez akkor segít, ha a kereskedelmi név eltér a nyilvántartott névtől.

Küldd el a saját external_id azonosítód a kérésben; változatlanul visszakapod, és minden válasz tartalmaz egy egyedi verification_id azonosítót is.

Olvass tovább

A Verification of Payee API Áttekintés, célközönség és felhasználási esetek. RoxPay Verification of Payee Hogyan nyújtja a szolgáltatást a RoxPay. Fogalomtár VoP, SEPA és sémakód kifejezések.

Kérd az API hitelesítő adataidat

Csatlakozz a SEPA VoP sémához egyetlen REST integrációval, és indulj élesben a határidőd előtt.

Beszélj egy szakértővel A VoP API-ról