Il bug di integrazione più comune con la Verification of Payee è trattare un NO_MATCH come una richiesta fallita. Non lo è. Una verifica andata a buon fine che afferma «questo nome non appartiene a questo IBAN» è comunque una risposta 200 con dati utili. Confondere le due cose porta a ignorare i segnali di frode o a mostrare agli utenti errori allarmanti.
I quattro codici di schema
Ogni risposta di Verification of Payee corrisponde a uno dei quattro codici standardizzati dello schema SEPA. Ramifica sul codice, non sul testo libero:
- MTCH — MATCH: il nome corrisponde al titolare. Procedi.
- CMTC — CLOSE_MATCH: quasi esatto (manca un secondo nome, nome commerciale vs ragione sociale). Mostra il nome verificato suggerito e chiedi conferma.
- NMTC — NO_MATCH: il nome non appartiene all'IBAN. Avvisa chiaramente e blocca l'approvazione automatica.
- NOAP — NOT_APPLICABLE: la verifica non è stata completata (es. banca rispondente irraggiungibile). Lascia decidere l'utente con cautela extra.
Esito vs errore
Se lo stato HTTP è 200 hai un esito di verifica — leggi scheme_code. Se è 4xx/5xx hai un errore — leggi il codice di errore. Non mappare mai NO_MATCH sul tuo percorso di errore.
Gestire bene il CLOSE_MATCH
Il CLOSE_MATCH è dove si vince o si perde la UX. La risposta può riportare il nome verificato del titolare; mostralo come suggerimento («Intendevi…?») così chi paga conferma o corregge invece di abbandonare il pagamento. Trattare CMTC come un fallimento netto frustra gli utenti legittimi.
Codici di errore veri
Distinti dagli esiti di schema, i problemi a livello di trasporto restituiscono errori HTTP standard — ad esempio invalid_iban (400), unauthorized (401), rate_limited (429) e scheme_unavailable (503). Ognuno riporta un request id per la tracciabilità del supporto. Passa un id esterno stabile a ogni chiamata così i retry restano idempotenti e i log si riconciliano.