O bug de integração mais comum com a Verification of Payee é tratar um NO_MATCH como um pedido falhado. Não é. Uma verificação bem-sucedida que diz «este nome não pertence a este IBAN» continua a ser uma resposta 200 com dados úteis. Confunda os dois e ou engole sinais de fraude ou mostra aos utilizadores erros alarmantes.
Os quatro códigos do esquema
Cada resposta Verification of Payee corresponde a um de quatro códigos padronizados do esquema SEPA. Ramifique sobre o código, não sobre texto livre:
- MTCH — MATCH: o nome corresponde ao titular da conta. Prossiga.
- CMTC — CLOSE_MATCH: quase certo (falta um nome do meio, nome comercial vs. denominação social). Mostre o nome verificado sugerido e peça ao pagador para confirmar.
- NMTC — NO_MATCH: o nome não pertence ao IBAN. Avise claramente e bloqueie a aprovação automática.
- NOAP — NOT_APPLICABLE: a verificação não pôde ser concluída (ex. banco respondente inacessível). Deixe o utilizador decidir com cautela extra.
Resultado vs erro
Se o estado HTTP for 200, tem um resultado de verificação — leia scheme_code. Se for 4xx/5xx, tem um erro — leia o código de erro. Nunca mapeie NO_MATCH no seu caminho de erro.
Tratar bem o CLOSE_MATCH
O CLOSE_MATCH é onde a boa UX se ganha ou se perde. A resposta pode transportar o nome verificado do titular; apresente-o como sugestão («Queria dizer…?») para que o pagador confirme ou corrija em vez de abandonar o pagamento. Tratar CMTC como uma falha total frustra os utilizadores legítimos.
Códigos de erro genuínos
Distintos dos resultados do esquema, os problemas ao nível do transporte devolvem erros HTTP padrão — por exemplo invalid_iban (400), unauthorized (401), rate_limited (429) e scheme_unavailable (503). Cada um transporta um request id para o suporte o poder rastrear. Passe um external id estável em cada chamada para que as repetições permaneçam idempotentes e os logs se reconciliem.