declined en la respuesta síncrona y dispara un webhook payment.refused. Ambos llevan un objeto refusalCode que te dice por qué falló el pago y qué hacer a continuación.
El objeto refusalCode
Solo
reasonCode y recoveryAction son seguros para construir lógica. originalReasonCode / originalReason son diagnósticos de paso y su formato no es estable entre proveedores.recoveryAction
Therius clasifica cada rechazo en una de cuatro acciones de recuperación para que tu checkout pueda responder sin codificar a mano una decisión para los más de 60 códigos.
retry
El rechazo podría resolverse en un segundo intento — un mensaje mal formado o a destiempo, un mal funcionamiento del sistema, o una respuesta genérica del emisor (incluido “Do not honor”). Reintentar la misma tarjeta una vez es razonable. Limita siempre los reintentos a un número fijo pequeño — no hagas bucles.
switch_method
Reintentar esta tarjeta no ayudará (fondos insuficientes, tarjeta vencida, tarjeta restringida), pero un método de pago diferente podría tener éxito. Pídele al cliente que pruebe con otra tarjeta o un método alternativo.
terminal
Un bloqueo definitivo — tarjeta a retener/perdida/robada, cuenta cerrada, sospecha de fraude, o una orden de revocación. No ofrezcas un reintento ni un método alternativo. Muestra un mensaje de fallo neutral y detente.
update_data
Reintentar tal cual fallará hasta que se corrija un dato que ingresó el comprador, como un documento fiscal, una clave Pix, una cuenta bancaria o un nombre. Pide al comprador que corrija el dato y envía de nuevo. Lo usan los métodos de pago alternativos.
reasonCode no reconocido o ausente se reporta como switch_method — el valor predeterminado seguro, ya que reintentar a ciegas un rechazo sin clasificar arriesga penalizaciones por intentos excesivos de las redes de tarjetas.
Re-enrutamiento automático
La mayoría de los rechazos temporales los reintenta Therius antes de que los veas — el enrutamiento inteligente propaga el pago en cascada a la siguiente conexión de la ruta. Por lo tanto, el rechazo que recibes en la respuesta es el resultado después de que Therius ya agotó las alternativas de esa ruta. Los rechazos definitivos (terminal más arriba, además de algunos otros como PIN incorrecto y fallos de CVV) se devuelven de inmediato y nunca se re-enrutan, porque reintentarlos en otro adquirente solo agregaría violaciones del esquema.
Suscripciones y gestión de cobros
Para las renovaciones de suscripción, Therius aplica la misma clasificación internamente: un rechazoterminal detiene la secuencia de gestión de cobros de inmediato (la suscripción pasa a suspended y dispara subscription.suspended), en lugar de desperdiciar los intentos de reintento restantes en una tarjeta que el emisor nunca aprobará.
Referencia de códigos de rechazo
Los valores dereasonCode normalizados que Therius puede devolver, con su significado y su recoveryAction predeterminada.
}
Códigos de métodos de pago alternativos
Los rechazos de métodos de pago alternativos llevan unreasonCode APM_*. El prefijo es reservado: un valor APM_* nunca es un código de tarjeta. Un rechazo de método alternativo que Therius no puede clasificar se reporta como APM_DECLINED, y una falla técnica como APM_TECHNICAL_ERROR. El código propio del proveedor sigue disponible en originalReasonCode.
Pagos expirados y cancelados
Cuando un pago de un método alternativo termina comoexpired o canceled porque el pagador no pagó o lo abandonó, el pago lleva APM_EXPIRED o APM_PAYER_CANCELED, y GET /payment/inquiry devuelve un refusalCode con recoveryAction: retry. Una cancelación que solicitas por la API no lleva motivo.