API-ul Verification of Payee API

Da. Un apel de verificare returnează răspunsul sincron, de regulă mult sub o secundă, și include BIC-ul băncii care răspunde și timpul de procesare al PSP-ului, astfel încât poți monitoriza performanța.

Apelurile sunt autentificate cu un bearer token prin HTTPS. Poți folosi și dashboard-ul RoxBusiness pentru verificări ad-hoc, fără să scrii cod.

Un rezultat normalizat (MATCH, CLOSE_MATCH, NO_MATCH, NOT_APPLICABLE), codul de tip de potrivire al schemei SEPA, un id de verificare, BIC-ul care răspunde, timpul de procesare și id-ul tău extern opțional.

Da - apelează endpoint-ul per înregistrare pentru a verifica un întreg fișier de furnizori sau beneficiari înainte de o rundă de plăți. Este construit pentru debit ridicat.

Da. Endpoint-ul este stateless, așa că îl poți apela oricând este creat un beneficiar - un pas de onboarding pentru un vânzător sau furnizor - și din nou imediat înainte de fiecare plată. Reverificarea la momentul plății prinde datele bancare modificate după onboarding, acolo unde are loc de obicei frauda prin redirecționarea facturilor și a plăților.

Verificarea este un apel REST per înregistrare, așa că un fișier de plată cu mii de beneficiari este tratat ca un lot: parcurgi fișierul, apelezi endpoint-ul per înregistrare și colectezi rezultatele înainte de a elibera runda. Pentru că API-ul este construit pentru debit ridicat, poți ritma bucla după propria fereastră de eliberare, în loc să fii limitat de onboardingul fiecărei bănci. Vorbește cu noi despre volumele tale și dimensionăm debitul împreună.

Da. Aceeași verificare este disponibilă în dashboard-ul RoxBusiness, astfel încât o echipă financiară sau de operațiuni poate verifica un singur beneficiar - o verificare „cunoaște-ți beneficiarul” înainte de a trimite bani - în timp ce dezvoltatorii folosesc API-ul pentru fluxuri automatizate.

Da. Verificarea compară numele trimis cu titularul de cont înregistrat, fie că este o persoană fizică sau o companie, și este folosită în fluxul de mandate SEPA Direct Debit al RoxPay ca verificare prealabilă.

NO_MATCH nu este o eroare de transport - este un răspuns 200 valid care îți spune că numele nu aparține IBAN-ului. Tratează-l ca o oprire fermă în interfața ta sau în runda de plăți: afișează un avertisment clar, blochează aprobarea automată și lasă utilizatorul să reverifice beneficiarul înainte de trimitere.

CLOSE_MATCH (cod de schemă CMTC) înseamnă că numele este aproape corect - lipsește un al doilea prenume, există o denumire legală diferită de numele comercial. Răspunsul include numele verificat al titularului de cont, astfel încât îl poți afișa ca sugestie și îi poți cere plătitorului să confirme, în loc să respingi plata.

Pentru persoanele juridice, schema permite verificarea față de identificatorul organizației (de exemplu Partita IVA / Codice Fiscale italian) precum și față de nume. Trimiți identificatorul în cerere, iar API-ul returnează rezultatul standard de potrivire - util când denumirea înregistrată și numele comercial diferă.

Da. Pentru o rundă de plăți, parcurge fișierul de furnizori sau de salarizare și apelează endpoint-ul de verificare per înregistrare înainte de a elibera lotul. Este construit pentru debit ridicat, astfel încât echipele financiare pot valida în masă IBAN-urile față de nume înainte de fiecare rundă de plăți.

Da. Trimiți o cerere JSON cu numele beneficiarului și IBAN-ul și primești înapoi rezultatul, numele verificat (în cazul unei potriviri apropiate) și BIC-ul care răspunde. Vezi o cerere și un răspuns complete în exemplul nostru VoP sau payload-urile și codurile de schemă în documentația API.

Tratează apelul de verificare ca pe un pas suplimentar înainte ca plata să fie autorizată. Autentifică-te cu un bearer token, trimite prin POST numele beneficiarului și IBAN-ul, citește rezultatul, apoi ramifică logica: continuă la MATCH, afișează numele sugerat și cere confirmarea la CLOSE_MATCH, blochează aprobarea automată la NO_MATCH și lasă plătitorul să decidă la NOT_APPLICABLE. Pentru că endpoint-ul este stateless, același apel se integrează în finalizarea comenzii, în onboardingul furnizorilor, într-o rundă de plăți sau într-un lot de plăți, fără să schimbi infrastructura de plăți.

Ambele, în funcție de scop. Ca verificator de beneficiari, răspunde la întrebarea „cui aparține acest IBAN?” pentru un singur beneficiar - util pentru o echipă financiară sau pentru un plătitor înainte de a trimite bani. Ca API de validare a plăților, rulează aceeași verificare într-un flux automatizat, astfel încât fiecare plată sau plată către beneficiari este validată față de titularul de cont înainte de a fi trimisă.

„Know your payee” este obiceiul practic de a confirma numele titularului de cont înainte de a plăti, în loc să ai încredere în datele de pe o factură sau dintr-un e-mail. API-ul transformă acest obicei într-un pas automatizat: numele este comparat cu IBAN-ul și primești un răspuns clar - potrivire, potrivire apropiată, fără potrivire sau verificare imposibilă - în mult mai puțin de o secundă.

Confirmation of Payee (CoP) este schema de verificare a numelui din Regatul Unit; Verification of Payee (VoP) este schema EPC folosită în toată UE și în SEPA. Dacă ai nevoie de ambele, caută un furnizor care acoperă schema SEPA VoP printr-o singură integrare și returnează rezultatele standardizate, astfel încât codul tău să nu se schimbe de la o piață la alta. RoxPay livrează VoP ca un singur API REST, cu codurile de schemă, BIC-ul care răspunde și timpul de procesare în fiecare răspuns.

Cinci lucruri. Acoperirea: la ce bănci și în ce țări ajunge furnizorul în toată SEPA. Latența: dacă rezultatele se încadrează în mod fiabil în fereastra plăților instant. Precizia: cum tratează potrivirea numelor cazurile de potrivire apropiată și denumirile legale față de cele comerciale. Direcțiile: dacă cererea și răspunsul VoP trec prin aceeași integrare. Și suportul: cine monitorizează serviciul și ce se întâmplă când un PSP care răspunde nu poate fi contactat. Cere în scris payload-ul răspunsului și codurile de eroare - îți spun mai multe decât o listă de funcții.

Ramifică logica după codul schemei, nu după eticheta afișată. În interfața ta, tratează MTCH ca o trecere silențioasă, CMTC ca un avertisment blând care afișează numele sugerat și îi cere plătitorului să confirme, iar NMTC ca un avertisment ferm care blochează aprobarea automată. NOAP nu este nici una, nici alta: înseamnă că verificarea nu a putut fi finalizată, așa că spune-i plătitorului că verificarea nu a fost disponibilă și lasă-l să decidă. Faptul că păstrezi cele patru coduri separate în cod este ceea ce face comportamentul avertismentelor previzibil.

Da, și ar trebui. Endpoint-ul este stateless, așa că același apel verifică un beneficiar când este creată înregistrarea - un pas de onboarding pentru un vânzător, furnizor sau angajat - și din nou imediat înainte ca banii să se miște. Reverificarea la momentul plății este ceea ce prinde datele bancare modificate după onboarding, acolo unde are loc de obicei frauda prin redirecționarea plăților. Un singur endpoint deservește ambele momente, așa că nu întreții două verificări.

Da. Credențialele de sandbox sunt emise separat de cele de producție, astfel încât poți rula fluxuri de potrivire, potrivire apropiată și fără potrivire împotriva API-ului înainte de a intra în producție. Testează și căile nefericite - un răspuns NOAP, un 429 și un 5xx - astfel încât logica de reîncercare și de avertismente să fie dovedită înainte ca banii reali să se miște. Aceleași credențiale deblochează și dashboard-ul RoxBusiness, unde poți rula verificări ad-hoc fără să scrii cod.

Primești NOT_APPLICABLE (cod de schemă NOAP) ca răspuns 200 valid, nu ca eroare de transport. Înseamnă că verificarea nu a putut fi finalizată pentru acel IBAN în acel moment. Tratează-l ca pe o necunoscută, nu ca pe o eroare: informează plătitorul că verificarea nu a fost disponibilă și lasă-l să decidă dacă vrea să continue. Eșecurile tehnice reale folosesc coduri de stare 4xx și 5xx, împreună cu un cod de eroare citibil de mașină.

PSP-ul solicitant este banca plătitorului - el trimite cererea de verificare. PSP-ul care răspunde este banca beneficiarului - el deține contul și răspunde cu rezultatul potrivirii. Schema EPC definește modul în care cele două fac schimbul acestui mesaj; cu API-ul tu doar trimiți cererea și citești răspunsul, așa că nu construiești singur mesageria inter-PSP.

Nu. EPC publică specificațiile API inter-PSP pentru Verification of Payee pe care PSP-urile le folosesc pentru a face schimb de cereri și răspunsuri. Un API VoP împachetează această mesagerie: trimiți un nume și un IBAN prin REST și primești rezultatul standardizat, codul schemei și BIC-ul care răspunde, fără să implementezi mesageria schemei și fără să te integrezi cu fiecare bancă care răspunde.

Ritmează bucla pe fereastra ta de eliberare, în loc să trimiți deodată un întreg fișier de plată. Dacă trimiți mai repede decât debitul convenit, primești un 429 - retrage-te și reîncearcă după o pauză. Pentru defecțiuni 5xx, reîncearcă cu același id extern, astfel încât reîncercarea să nu creeze o verificare duplicată. Pentru 4xx, corectează cererea: un IBAN malformat, un nume lipsă sau credențiale invalide nu vor reuși la o reîncercare.

API-ul răspunde la o singură întrebare - acest nume aparține acestui IBAN - și returnează rezultatul schemei. Acel rezultat este un semnal puternic pe care îl poți transmite propriilor reguli de fraudă și risc: o lipsă de potrivire la un beneficiar ale cărui date bancare au fost modificate recent este exact tiparul care merită escaladat. Păstrează separat în loguri rezultatul verificării și decizia de screening, astfel încât să vezi care dintre ele a oprit o plată.

Nu, răspund la întrebări diferite. Validarea IBAN verifică dacă IBAN-ul este corect format - formatul țării și cifrele de control - dar nu spune nimic despre cine deține contul. Verification of Payee întreabă banca beneficiarului dacă numele aparține acelui IBAN. Rulează-le pe amândouă: validarea prinde greșelile de tastare înainte de apel, iar verificarea prinde un IBAN valid care aparține altcuiva.