El bug de integración más común con la Verification of Payee es tratar un NO_MATCH como una solicitud fallida. No lo es. Una verificación exitosa que dice «este nombre no pertenece a este IBAN» sigue siendo una respuesta 200 con datos útiles. Confunde ambas cosas y o te tragarás señales de fraude o mostrarás a los usuarios errores alarmantes.
Los cuatro códigos del esquema
Cada respuesta de Verification of Payee corresponde a uno de los cuatro códigos estandarizados del esquema SEPA. Ramifica sobre el código, no sobre texto libre:
- MTCH — MATCH: el nombre coincide con el titular de la cuenta. Continúa.
- CMTC — CLOSE_MATCH: casi correcto (falta un segundo nombre, nombre comercial vs razón social). Muestra el nombre verificado sugerido y pide al pagador que confirme.
- NMTC — NO_MATCH: el nombre no pertenece al IBAN. Avisa claramente y bloquea la aprobación automática.
- NOAP — NOT_APPLICABLE: la comprobación no pudo completarse (p. ej. banco receptor inaccesible). Deja decidir al usuario con precaución extra.
Resultado vs error
Si el estado HTTP es 200, tienes un resultado de verificación — lee scheme_code. Si es 4xx/5xx, tienes un error — lee el código de error. Nunca mapees NO_MATCH sobre tu ruta de error.
Gestionar bien el CLOSE_MATCH
El CLOSE_MATCH es donde se gana o se pierde la buena UX. La respuesta puede llevar el nombre verificado del titular; muéstralo como sugerencia («¿Quisiste decir…?») para que el pagador confirme o corrija en lugar de abandonar el pago. Tratar CMTC como un fallo rotundo frustra a los usuarios legítimos.
Códigos de error genuinos
Aparte de los resultados del esquema, los problemas a nivel de transporte devuelven errores HTTP estándar — por ejemplo invalid_iban (400), unauthorized (401), rate_limited (429) y scheme_unavailable (503). Cada uno lleva un request id para que soporte pueda rastrearlo. Pasa un external id estable en cada llamada para que los reintentos sigan siendo idempotentes y los logs se reconcilien.