Referință API

Documentație API Verification of Payee

Autentificare, endpointul de verificare, payload-urile de cerere și răspuns, codurile de potrivire din schema SEPA și gestionarea erorilor — tot ce are nevoie un dezvoltator pentru a integra verificarea IBAN/nume, cu exemple JSON și cURL gata de copiat.

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

URL-ul de bază și credențialele API sunt furnizate la onboarding — contactează-ne pentru a le obține.

API-ul Verification of Payee este un singur endpoint REST autentificat: trimiți prin POST numele beneficiarului și IBAN-ul și primești în timp real un rezultat standardizat de potrivire. Exemplele de mai jos sunt ilustrative; URL-ul de bază și credențialele exacte se emit la onboarding.

Autentificare

Fiecare cerere este autentificată cu un token bearer prin HTTPS. Trimite tokenul în headerul Authorization; tokenurile se emit separat pentru fiecare mediu (sandbox și producție).

Aceleași credențiale deblochează și dashboardul RoxBusiness, unde poți rula verificări ad-hoc fără să scrii cod.

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

Cerere

Trimite prin POST un corp JSON cu numele beneficiarului și IBAN-ul. Pentru persoanele juridice poți trimite și un identificator al organizației (de exemplu o Partita IVA / Codice Fiscale italiană) și un external_id opțional pentru reconciliere.

Corpul cererii

Câmp Tip Obligatoriu Descriere
name string Obligatoriu Numele beneficiarului de verificat, așa cum l-a introdus plătitorul.
iban string Obligatoriu IBAN-ul de destinație (validat ca format și checksum înainte de apelul către schemă).
account_type enum Opțional NATURAL_PERSON sau LEGAL_PERSON. Ajută banca respondentă să facă potrivirea corect.
organisation_id string Opțional Număr de TVA / cod fiscal pentru persoanele juridice (de exemplu Partita IVA). Se verifică față de titularul înregistrat.
external_id string Opțional Identificatorul tău de referință, returnat în răspuns pentru reconciliere.
Corpul cererii 
{
  "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"
  }'

Răspuns

Un răspuns 200 returnează rezultatul normalizat, codul de potrivire din schema SEPA, BIC-ul băncii respondente și timpul de procesare. În cazul unei potriviri apropiate, numele verificat este returnat în suggested_name.

Corpul răspunsului

Câmp Tip Descriere
verification_id string Identificator unic pentru această verificare, pentru traseul tău de audit.
result enum MATCH, CLOSE_MATCH, NO_MATCH sau NOT_APPLICABLE.
scheme_code string Codul din schema SEPA VoP: MTCH, CMTC, NMTC sau NOAP.
suggested_name string În cazul CLOSE_MATCH, numele verificat al titularului de cont, care poate fi sugerat plătitorului.
responding_bic string BIC-ul instituției care a răspuns la verificare.
processing_time_ms integer Timpul consumat de PSP-ul respondent, în milisecunde.
external_id string Identificatorul tău de referință, returnat neschimbat.
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"
}

Coduri de rezultat al potrivirii

Fiecare răspuns corespunde unuia dintre cele patru coduri din schema SEPA VoP. Ramifică logica pe scheme_code, ca să rămână stabilă.

Cod Rezultat Semnificație Acțiune recomandată
MTCH MATCH Numele corespunde titularului de cont. Continuă cu încredere.
CMTC CLOSE_MATCH Aproape corect (de exemplu numele comercial față de denumirea legală). Afișează suggested_name; cere plătitorului să confirme.
NMTC NO_MATCH Numele nu aparține acestui IBAN. Stop ferm — avertizează și blochează aprobarea automată.
NOAP NOT_APPLICABLE Verificarea nu a putut fi finalizată. Informează plătitorul; lasă-l să decidă.

Gestionarea erorilor

NO_MATCH este un rezultat 200 valid, nu o eroare — nu îl trata niciodată ca pe o defecțiune de transport. Erorile reale folosesc coduri de stare 4xx/5xx, cu un cod de eroare citibil de mașină și un request_id pentru suport.

HTTP Cod de eroare Când apare
400 invalid_iban IBAN-ul nu a trecut validarea de format sau de checksum.
400 missing_field Lipsește un câmp obligatoriu (name sau iban).
401 unauthorized Token bearer lipsă sau invalid.
429 rate_limited Prea multe cereri — reduce ritmul și reîncearcă.
503 scheme_unavailable Schema VoP / PSP-ul respondent este temporar inaccesibil.
400 Bad Request 
{
  "error": "invalid_iban",
  "message": "The 'iban' field failed checksum validation.",
  "request_id": "req_8a2b1f0c"
}

Integrează în patru pași

O integrare REST standard, care se potrivește în fluxul tău de plăți existent.

  1. 1

    Obține credențialele

    Fă onboardingul și primești tokenul bearer și URL-ul de bază pentru sandbox și producție.

  2. 2

    Apelează /verify

    Trimite prin POST numele beneficiarului și IBAN-ul, cu external_id și organisation_id opționale.

  3. 3

    Citește scheme_code

    Ramifică pe MTCH / CMTC / NMTC / NOAP și stochează verification_id.

  4. 4

    Acționează în interfață

    Afișează un semnal clar pentru plătitor sau condiționează de rezultat un lot de plăți ori un mandat.

Referință API

Întrebări frecvente pentru dezvoltatori

Întrebările pe care le pun mai întâi echipele de integrare.

Un corp JSON cu name și iban (obligatorii), plus account_type, organisation_id (număr de TVA / cod fiscal pentru persoanele juridice) și external_id opționale. Vezi exemplul de cerere de mai sus.

NO_MATCH (codul de schemă NMTC) este un răspuns 200 valid, nu o eroare. Tratează-l ca pe un stop ferm: avertizează plătitorul, blochează aprobarea automată și cere o reverificare înainte de trimitere.

Da. Tokenurile se emit separat pentru fiecare mediu, așa că poți integra și testa în sandbox înainte de a comuta URL-ul de bază pe producție.

Da — trimite organisation_id cu account_type LEGAL_PERSON. Ajută atunci când numele comercial diferă de denumirea înregistrată.

Trimite propriul external_id în cerere; acesta este returnat neschimbat, iar fiecare răspuns conține și un verification_id unic.

Continuă lectura

API-ul Verification of Payee Prezentare generală, publicuri vizate și cazuri de utilizare. RoxPay Verification of Payee Cum este livrat serviciul pe RoxPay. Glosar Termeni VoP, SEPA și coduri de schemă.

Obține credențialele API

Fă onboardingul în schema SEPA VoP cu o singură integrare REST și intră în producție înainte de termenul limită.

Discută cu un expert Despre API-ul VoP