Fallos de transacciones

Comprende cada código de fallo de transacción <Card title="Handle Payment Failures" icon="screwdriver-wrench" href="/developer-resources/handle-payment-failures">, ya sea un rechazo suave o definitivo, y la acción recomendada para recuperar el pago.

​

Descripción general

Dodo Payments devuelve un motivo detallado del fallo cada vez que un intento de pago no se completa correctamente. Estos motivos están estandarizados en los distintos métodos y proveedores de pago, por lo que puedes implementar una gestión coherente en tu aplicación.

Cuando falla un pago, el webhook payment.failed y el objeto de pago exponen:

• error_code — un motivo de fallo estandarizado de la tabla siguiente.
• error_message — una explicación legible para las personas.
• retry_attempt — 0 para el cargo original, 1 o superior para cada reintento programado de renovación de la suscripción.

Comprender estos motivos de fallo te permite ofrecer a los clientes información clara, decidir si vale la pena reintentar y recuperar más ingresos.

Handle Payment Failures

Una guía paso a paso para desarrolladores sobre cómo leer estos códigos desde los webhooks y la API, mostrarlos a los clientes y decidir cuándo reintentar.

​

Rechazos suaves y definitivos

Cada código de fallo pertenece a una de dos categorías. Esta distinción determina si debes reintentar con el mismo método de pago o pedir al cliente que use uno nuevo.

Tipo de rechazo	Qué significa	Qué hacer	Ejemplos
Soft decline	Temporal o corregible: la misma tarjeta puede funcionar en un intento posterior o cuando el cliente corrija los datos introducidos.	Es seguro reintentar (después de un tiempo de espera o cuando el cliente corrija sus datos).	INSUFFICIENT_FUNDS, GENERIC_DECLINE, CARD_VELOCITY_EXCEEDED, PROCESSING_ERROR, NETWORK_ERROR, NETWORK_TIMEOUT, TRY_AGAIN_LATER
Hard decline	Definitivo: reintentar con la misma tarjeta no cambiará el resultado.	No reintentes con la misma tarjeta. Pide al cliente que utilice otro método de pago o se ponga en contacto con su banco.	STOLEN_CARD, LOST_CARD, PICKUP_CARD, DO_NOT_HONOR, FRAUDULENT, INVALID_ACCOUNT

Para las renovaciones de suscripciones, Dodo Payments aplica esta distinción automáticamente: los rechazos suaves se vuelven a intentar mediante Reintentos de pago de suscripciones, mientras que los rechazos definitivos finalizan inmediatamente la cadena de reintentos y se gestionan mejor con Dunning de suscripciones.

Nunca reveles al cliente el motivo real de STOLEN_CARD, LOST_CARD, PICKUP_CARD o FRAUDULENT. Mostrar estos motivos puede alertar a un actor fraudulento. Muestra siempre al cliente un mensaje de rechazo genérico (por ejemplo, “Se rechazó tu tarjeta. Ponte en contacto con tu banco o utiliza otra tarjeta.”) y registra únicamente el código específico de forma interna.

​

Motivos de fallo de transacciones

La tabla siguiente enumera cada código de fallo, su tipo de rechazo, si el cliente puede resolverlo, una descripción y la acción recomendada.

Código de fallo	Tipo	Error del usuario	Descripción	Acción recomendada
AUTHENTICATION_FAILURE	Soft	Sí	La autenticación falló durante la transacción	Pide al cliente que reintente y complete la autenticación 3DS, o que utilice otra tarjeta
AUTHENTICATION_REQUIRED	Soft	Sí	Se necesita autenticación adicional para completar la transacción	Solicita al cliente que complete la autenticación 3DS. Para las renovaciones de suscripciones, pídele que vuelva y se autentique
AUTHENTICATION_TIMEOUT	Soft	Sí	El proceso de autenticación agotó el tiempo de espera	Pide al cliente que reintente y complete la autenticación rápidamente
CARD_DECLINED	Soft	No	El banco emisor rechazó la tarjeta sin indicar un motivo específico (rechazo genérico)	Pide al cliente que reintente, se ponga en contacto con su banco o utilice otra tarjeta
CARD_NOT_ACTIVATED	Soft	Sí	El titular no ha activado la tarjeta	Pide al cliente que active la tarjeta con su banco y vuelva a intentarlo
CARD_VELOCITY_EXCEEDED	Soft	Sí	Se intentaron demasiadas transacciones en un periodo corto	Pide al cliente que espere y vuelva a intentarlo más tarde, o que consulte a su banco sobre los límites
CUSTOMER_CANCELLED	Soft	Sí	El cliente canceló la transacción	Permite que el cliente reinicie el proceso de checkout cuando esté listo
DO_NOT_HONOR	Hard	No	El banco emisor rechazó explícitamente la transacción (código ISO 8583 05 — no aceptar); las redes lo consideran un rechazo definitivo	Pide al cliente que se ponga en contacto con su banco; no reintentes con la misma tarjeta
EXPIRED_CARD	Hard	Sí	La tarjeta ha caducado	Pide al cliente que utilice una tarjeta con una fecha de caducidad válida
FRAUDULENT	Hard	Sí	La transacción se marcó como potencialmente fraudulenta	Muestra al cliente un mensaje de rechazo genérico; no reveles el motivo. Pídele que utilice otra tarjeta
GENERIC_DECLINE	Soft	No	La transacción se rechazó por un motivo no especificado	Pide al cliente que se ponga en contacto con su banco o pruebe con otra tarjeta
INCORRECT_CVC	Soft	Sí	El código CVC proporcionado era incorrecto	Pide al cliente que vuelva a introducir el CVC correcto
INCORRECT_NUMBER	Soft	Sí	El número de tarjeta se introdujo incorrectamente	Pide al cliente que vuelva a introducir el número de tarjeta correcto
INSUFFICIENT_FUNDS	Soft	Sí	La cuenta no tiene fondos suficientes para completar la transacción	Pide al cliente que utilice otro método de pago o vuelva a intentarlo cuando haya fondos disponibles
INVALID_ACCOUNT	Hard	Sí	Los datos de la cuenta proporcionados no son válidos	Pide al cliente que se ponga en contacto con su banco o utilice otra tarjeta
INVALID_AMOUNT	Soft	Sí	El importe de la transacción no es válido	Verifica el importe y los límites de compra con el cliente
INVALID_CARD_NUMBER	Soft	Sí	El formato del número de tarjeta no es válido	Pide al cliente que vuelva a introducir un número de tarjeta válido
INVALID_CARD_OWNER	Soft	Sí	La información del titular de la tarjeta no es válida	Pide al cliente que corrija el nombre del titular de la tarjeta
INVALID_CVC	Soft	Sí	El formato del CVC no es válido	Pide al cliente que vuelva a introducir un CVC válido
INVALID_EXPIRY_YEAR	Soft	Sí	El año de caducidad de la tarjeta no es válido	Pide al cliente que introduzca una fecha de caducidad válida
INVALID_PIN	Soft	Sí	El PIN proporcionado es incorrecto	Pide al cliente que vuelva a introducir el PIN correcto
INVALID_REQUEST	Soft	Sí	La solicitud de transacción contiene datos no válidos	Comprueba los campos de la solicitud de pago y vuelve a enviarla con datos válidos
INVALID_UPI_ID	Soft	Sí	El UPI ID proporcionado no es válido	Pide al cliente que introduzca un UPI ID válido
LIMIT_EXCEEDED	Soft	Sí	La transacción supera el límite de la tarjeta o de la cuenta	Pide al cliente que consulte a su banco sobre los límites o utilice otro método
LIVE_MODE_TEST_CARD	Hard	Sí	Se utilizó una tarjeta de prueba en modo live	Utiliza una tarjeta real; reintentar con la tarjeta de prueba siempre fallará en modo live
LOST_CARD	Hard	Sí	La tarjeta se ha declarado como perdida	Muestra al cliente un mensaje de rechazo genérico; no reveles el motivo. Pídele que utilice otra tarjeta
MANDATE_INVALID	Soft	Sí	El mandato de pago no es válido	Pide al cliente que configure de nuevo el mandato de pago
MANDATE_REQUIRED	Soft	Sí	Se requiere un mandato para esta transacción	Configura un mandato y pide al cliente que lo autorice antes de realizar el cargo
MANDATE_REQUIRED_SYSTEM	Hard	No	El sistema requiere un mandato para este tipo de transacción	Asegúrate de completar el flujo de configuración del mandato antes de realizar el cargo
NETWORK_ERROR	Soft	No	Se produjo un error de red durante la transacción	Transitorio: reintenta el pago después de una breve espera
NETWORK_TIMEOUT	Soft	No	La solicitud de red agotó el tiempo de espera	Transitorio: reintenta el pago después de una breve espera
ORDER_ALREADY_EXISTS	Soft	No	Ya existe un pedido para esta transacción (creación de pedido duplicada)	Comprueba el estado del pedido existente antes de reintentar; ponte en contacto con soporte si el problema persiste
ORDER_CREATION_FAILED	Soft	No	No se pudo crear el pedido para la transacción	Error transitorio o del sistema: reintenta el pago; ponte en contacto con soporte si el problema persiste
PAYMENT_METHOD_PROVIDER_DECLINED	Hard	Sí	El proveedor del método de pago rechazó la transacción	Pide al cliente que se ponga en contacto con su proveedor o utilice otro método de pago
PAYMENT_METHOD_UNSUPPORTED	Hard	Sí	El método de pago no es compatible con esta transacción	Pide al cliente que utilice un método de pago compatible
PICKUP_CARD	Hard	Sí	La tarjeta se ha declarado como perdida o robada y se ha marcado para su retirada	Muestra al cliente un mensaje de rechazo genérico; no reveles el motivo. Pídele que utilice otra tarjeta
PROCESSING_ERROR	Soft	No	Se produjo un error al procesar la transacción	Transitorio: reintenta el pago; si el problema persiste, pide al cliente que se ponga en contacto con su banco
PROVIDER_UNSUPPORTED	Hard	No	El proveedor de pagos no admite este tipo de transacción	Pide al cliente que utilice otro método de pago
REENTER_TRANSACTION	Soft	Sí	Es necesario volver a introducir la transacción	Pide al cliente que reintente el pago
REVOCATION_OF_AUTHORIZATION	Hard	Sí	Se revocó la autorización de la transacción	Pide al cliente que utilice otro método de pago
STOLEN_CARD	Hard	Sí	La tarjeta se ha declarado como robada	Muestra al cliente un mensaje de rechazo genérico; no reveles el motivo. Pídele que utilice otra tarjeta
SUBSCRIPTION_NOT_ACTIVE	Hard	No	La suscripción no está activa, por lo que no se pudo procesar el cargo recurrente	Reactiva la suscripción (por ejemplo, actualizando el método de pago) antes de intentar realizar el cargo de nuevo
TRANSACTION_NOT_ALLOWED	Hard	Sí	La transacción no está permitida para esta tarjeta o cuenta	Pide al cliente que se ponga en contacto con su banco para permitir este tipo de transacción o utilice otra tarjeta
TRANSACTION_NOT_APPROVED	Hard	Sí	La transacción no fue aprobada	Pide al cliente que se ponga en contacto con su banco o pruebe con otra tarjeta
TRY_AGAIN_LATER	Soft	No	La transacción debe reintentarse más tarde	Transitorio: reintenta el pago más tarde
UNKNOWN_ERROR	Soft	No	Se produjo un error desconocido	Reintenta el pago; si el problema persiste, ponte en contacto con soporte

Error del usuario indica si el cliente puede resolver el rechazo del pago. Cuando Yes, el cliente puede actuar para solucionar el problema (por ejemplo, introduciendo correctamente los datos de la tarjeta). Cuando No, el rechazo se debe a problemas a nivel del sistema o a restricciones bancarias que el cliente no puede resolver directamente.

Una tarjeta también puede rechazarse cuando el propio motor de riesgo del banco emisor marca al titular como un cliente de alto riesgo, independientemente del comercio o de los detalles de la transacción. Estos rechazos suelen aparecer como códigos genéricos, como DO_NOT_HONOR, GENERIC_DECLINE, CARD_DECLINED, TRANSACTION_NOT_APPROVED o FRAUDULENT. En estos casos, el banco no comparte el motivo específico, y ni Dodo Payments ni el comercio pueden anular la decisión. Pide al cliente que se ponga en contacto con su banco para resolver la marca o que utilice otra tarjeta o método de pago.

​

Gestión programática de fallos

Lee error_code del webhook payment.failed o del objeto de pago, asígnalo a la acción recomendada anterior y decide si debes reintentar. Para las renovaciones de suscripciones, los rechazos suaves se reintentan automáticamente; consulta Reintentos de pago de suscripciones.

Para los errores a nivel de API y de lógica empresarial (como PAYMENT_NOT_SUCCEEDED o REFUND_WINDOW_EXPIRED) que no sean rechazos de tarjeta, consulta la referencia de Códigos de error.

​

Relacionado

Handle Payment Failures

Guía completa para detectar, mostrar y reintentar pagos fallidos.

Error Codes

Códigos de error de API y de lógica empresarial para fallos que no son rechazos.

Subscription Payment Retries

Reintentos automáticos que recuperan rechazos suaves en las renovaciones de suscripciones.

Subscription Dunning

Secuencias de correo electrónico que recuperan rechazos definitivos solicitando actualizar el método de pago.

​

Soporte

Para obtener ayuda adicional con los fallos de transacciones o problemas de integración, ponte en contacto con nuestro equipo de soporte en [e-mail].