Cea mai frecventă eroare de integrare la Verification of Payee este să tratezi un NO_MATCH ca pe o cerere eșuată. Nu este. O verificare reușită care spune „acest nume nu aparține acestui IBAN” rămâne un răspuns 200 cu date utile. Dacă le confunzi pe cele două, fie ignori semnalele de fraudă, fie le arăți utilizatorilor erori înfricoșătoare.
Cele patru coduri de schemă
Fiecare răspuns Verification of Payee corespunde unuia dintre cele patru coduri standardizate ale schemei SEPA. Ramifică pe cod, nu pe text liber:
- MTCH - MATCH: numele corespunde titularului de cont. Continuă.
- CMTC - CLOSE_MATCH: aproape corect (lipsește un al doilea prenume, nume comercial vs. denumire legală). Afișează numele verificat sugerat și cere plătitorului să confirme.
- NMTC - NO_MATCH: numele nu aparține IBAN-ului. Avertizează clar și blochează aprobarea automată.
- NOAP - NOT_APPLICABLE: verificarea nu a putut fi finalizată (de ex. banca respondentă nu poate fi contactată). Lasă utilizatorul să decidă cu prudență suplimentară.
Rezultat vs. eroare
Dacă statusul HTTP este 200, ai un rezultat de verificare - citește scheme_code. Dacă este 4xx/5xx, ai o eroare - citește codul de eroare. Nu mapa niciodată NO_MATCH pe traseul tău de eroare.
Cum tratezi corect CLOSE_MATCH
La CLOSE_MATCH se câștigă sau se pierde o experiență bună pentru utilizator. Răspunsul poate conține numele verificat al titularului de cont; afișează-l ca sugestie („Ai vrut să spui…?”), astfel încât plătitorul să confirme sau să corecteze, în loc să abandoneze plata. Dacă tratezi CMTC ca pe un eșec total, frustrezi utilizatorii legitimi.
Coduri de eroare reale
Separat de rezultatele schemei, problemele de la nivel de transport returnează erori HTTP standard - de exemplu invalid_iban (400), unauthorized (401), rate_limited (429) și scheme_unavailable (503). Fiecare include un request id, astfel încât suportul să îl poată urmări. Trimite un external id stabil la fiecare apel, ca reîncercările să rămână idempotente și jurnalele să se poată reconcilia.