Najczęstszym błędem integracyjnym z Verification of Payee jest traktowanie NO_MATCH jako nieudanego żądania. To nieprawda. Udana weryfikacja, która mówi „ta nazwa nie należy do tego numeru IBAN”, to wciąż odpowiedź 200 z przydatnymi danymi. Pomyl te dwie rzeczy, a albo zignorujesz sygnały oszustwa, albo pokażesz użytkownikom przerażające błędy.
Cztery kody schematu
Każda odpowiedź Verification of Payee odpowiada jednemu z czterech standaryzowanych kodów schematu SEPA. Rozdzielaj logikę na podstawie kodu, nie wolnego tekstu:
- MTCH - MATCH: nazwa zgadza się z posiadaczem rachunku. Kontynuuj.
- CMTC - CLOSE_MATCH: prawie zgodne (brakujące drugie imię, nazwa handlowa a nazwa prawna). Pokaż sugerowaną zweryfikowaną nazwę i poproś płatnika o potwierdzenie.
- NMTC - NO_MATCH: nazwa nie należy do numeru IBAN. Ostrzeż wyraźnie i zablokuj automatyczną akceptację.
- NOAP - NOT_APPLICABLE: weryfikacji nie udało się zakończyć (np. bank odpowiadający nieosiągalny). Pozwól użytkownikowi zdecydować z dodatkową ostrożnością.
Wynik a błąd
Jeśli status HTTP to 200, masz wynik weryfikacji - odczytaj scheme_code. Jeśli to 4xx/5xx, masz błąd - odczytaj kod błędu. Nigdy nie mapuj NO_MATCH na swoją ścieżkę błędu.
Dobra obsługa CLOSE_MATCH
CLOSE_MATCH to miejsce, w którym wygrywa się lub przegrywa dobre UX. Odpowiedź może przenosić zweryfikowaną nazwę posiadacza rachunku; pokaż ją jako sugestię („Czy miałeś na myśli…?”), aby płatnik potwierdził lub poprawił dane, a nie rezygnował z płatności. Traktowanie CMTC jako całkowitej porażki frustruje legalnych użytkowników.
Rzeczywiste kody błędów
W odróżnieniu od wyników schematu, problemy na poziomie transportu zwracają standardowe błędy HTTP - na przykład invalid_iban (400), unauthorized (401), rate_limited (429) i scheme_unavailable (503). Każdy niesie identyfikator żądania, dzięki czemu wsparcie może go wyśledzić. Przekazuj stabilny zewnętrzny identyfikator w każdym wywołaniu, aby powtórzenia pozostały idempotentne, a logi się zgadzały.