Fallos de transacciones

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 escrita para ti, el merchant. Cuando error_code es uno de los códigos estandarizados siguientes, se muestra un encabezado más la acción recomendada, en lugar del texto sin procesar del procesador de pagos.
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.

Texto para el merchant frente a texto para el cliente

Cada código de fallo estandarizado corresponde a dos mensajes diferentes, para que cada audiencia vea el nivel de detalle adecuado:

Audiencia	Dónde aparece	Qué indica
Tú	`error_message` en el pago, en la página de detalles del pago del dashboard y en el email de pago fallido para el merchant	El motivo real más una acción recomendada, por ejemplo “La tarjeta no ha sido activada por el titular. Pide al cliente que la active con su banco y vuelve a intentarlo.”
Tu cliente	La pantalla de fallo del checkout, el Customer Portal y los emails de dunning	Una explicación breve y clara con la que pueda actuar, por ejemplo “Tu tarjeta aún no ha sido activada. Actívala con tu banco y vuelve a intentarlo.”

El Customer Portal devuelve el texto dirigido al cliente en error_message, mientras que la API del merchant devuelve el texto dirigido al merchant para el mismo pago. El error_code es idéntico en ambos casos.

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 temporales frente a rechazos 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
Rechazo temporal	Temporal o corregible: la misma tarjeta puede funcionar en un intento posterior o una vez que el cliente corrija los datos introducidos.	Es seguro reintentar (después de una espera o cuando el cliente corrija sus datos).	`INSUFFICIENT_FUNDS`, `GENERIC_DECLINE`, `CARD_VELOCITY_EXCEEDED`, `PROCESSING_ERROR`, `NETWORK_ERROR`, `NETWORK_TIMEOUT`, `TRY_AGAIN_LATER`
Rechazo definitivo	Terminal: reintentar con la misma tarjeta no cambiará el resultado.	No reintentes con la misma tarjeta. Pide al cliente que use otro método de pago o que contacte 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 temporales se reintentan mediante Subscription Payment Retries, mientras que los rechazos definitivos finalizan inmediatamente la cadena de reintentos y se gestionan mejor con Subscription Dunning.

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, “Tu tarjeta ha sido rechazada. Contacta con tu banco o usa otra tarjeta.”) y registra únicamente el código específico de forma interna.Dodo Payments ya aplica esta regla en las superficies que controla: para estos cuatro códigos, el checkout, el Customer Portal y los emails de dunning siempre recurren a un mensaje de rechazo genérico, mientras que tu propio texto conserva el motivo real. Aplica la misma regla en cualquier lugar donde muestres error_message desde la API del merchant a un cliente.

Motivos de fallo de transacciones

La siguiente tabla incluye todos los códigos 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`	Temporal	Sí	La autenticación falló durante la transacción	Pide al cliente que vuelva a intentarlo y complete la autenticación 3DS, o que use otra tarjeta
`AUTHENTICATION_REQUIRED`	Temporal	Sí	Se necesita autenticación adicional para completar la transacción	Pide al cliente que complete la autenticación 3DS. Para las renovaciones de suscripciones, pídele que vuelva y se autentique
`AUTHENTICATION_TIMEOUT`	Temporal	Sí	El proceso de autenticación agotó el tiempo de espera	Pide al cliente que vuelva a intentarlo y complete la autenticación cuanto antes
`CARD_DECLINED`	Temporal	No	El banco emisor rechazó la tarjeta sin indicar un motivo específico (rechazo genérico)	Pide al cliente que vuelva a intentarlo, contacte con su banco o use otra tarjeta
`CARD_NOT_ACTIVATED`	Temporal	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`	Temporal	Sí	Se intentaron realizar demasiadas transacciones en un periodo corto	Pide al cliente que espere y vuelva a intentarlo más tarde, o que consulte con su banco los límites
`CUSTOMER_CANCELLED`	Temporal	Sí	El cliente canceló la transacción	Permite que el cliente reinicie el checkout cuando esté preparado
`DO_NOT_HONOR`	Definitivo	No	El banco emisor rechazó explícitamente la transacción (código ISO 8583 05 — no aceptar); las redes lo consideran terminal	Pide al cliente que contacte con su banco; no reintentes con la misma tarjeta
`EXPIRED_CARD`	Definitivo	Sí	La tarjeta ha caducado	Pide al cliente que use una tarjeta con una fecha de caducidad válida
`FRAUDULENT`	Definitivo	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 use otra tarjeta
`GENERIC_DECLINE`	Temporal	No	La transacción fue rechazada por un motivo no especificado	Pide al cliente que contacte con su banco o pruebe con otra tarjeta
`INCORRECT_CVC`	Temporal	Sí	El código CVC proporcionado era incorrecto	Pide al cliente que vuelva a introducir el CVC correcto
`INCORRECT_NUMBER`	Temporal	Sí	El número de tarjeta se introdujo incorrectamente	Pide al cliente que vuelva a introducir el número de tarjeta correcto
`INSUFFICIENT_FUNDS`	Temporal	Sí	La cuenta no tiene fondos suficientes para completar la transacción	Pide al cliente que use otro método de pago o que vuelva a intentarlo cuando haya fondos disponibles
`INVALID_ACCOUNT`	Definitivo	Sí	Los datos de la cuenta proporcionados no son válidos	Pide al cliente que contacte con su banco o use otra tarjeta
`INVALID_AMOUNT`	Temporal	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`	Temporal	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`	Temporal	Sí	La información del titular de la tarjeta no es válida	Pide al cliente que corrija el nombre del titular
`INVALID_CVC`	Temporal	Sí	El formato del CVC no es válido	Pide al cliente que vuelva a introducir un CVC válido
`INVALID_EXPIRY_YEAR`	Temporal	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`	Temporal	Sí	El PIN proporcionado es incorrecto	Pide al cliente que vuelva a introducir el PIN correcto
`INVALID_REQUEST`	Temporal	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`	Temporal	Sí	El UPI ID proporcionado no es válido	Pide al cliente que introduzca un UPI ID válido
`LIMIT_EXCEEDED`	Temporal	Sí	La transacción supera el límite de la tarjeta o la cuenta	Pide al cliente que consulte con su banco los límites o use otro método
`LIVE_MODE_TEST_CARD`	Definitivo	Sí	Se utilizó una tarjeta de prueba en modo live	Usa una tarjeta real; reintentar con la tarjeta de prueba siempre fallará en modo live
`LOST_CARD`	Definitivo	Sí	La tarjeta se ha denunciado como perdida	Muestra al cliente un mensaje de rechazo genérico; no reveles el motivo. Pídele que use otra tarjeta
`MANDATE_INVALID`	Temporal	Sí	El mandato de pago no es válido	Pide al cliente que configure de nuevo el mandato de pago
`MANDATE_REQUIRED`	Temporal	Sí	Esta transacción requiere un mandato	Configura un mandato y pide al cliente que lo autorice antes de realizar el cargo
`MANDATE_REQUIRED_SYSTEM`	Definitivo	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`	Temporal	No	Se produjo un error de red durante la transacción	Transitorio: reintenta el pago después de una breve espera
`NETWORK_TIMEOUT`	Temporal	No	La solicitud de red agotó el tiempo de espera	Transitorio: reintenta el pago después de una breve espera
`ORDER_ALREADY_EXISTS`	Temporal	No	Ya existe un pedido para esta transacción (creación de pedido duplicada)	Comprueba el estado del pedido existente antes de reintentar; contacta con soporte si persiste
`ORDER_CREATION_FAILED`	Temporal	No	No se pudo crear el pedido para la transacción	Error transitorio/del sistema: reintenta el pago; contacta con soporte si persiste
`PAYMENT_METHOD_PROVIDER_DECLINED`	Definitivo	Sí	El proveedor del método de pago rechazó la transacción	Pide al cliente que contacte con su proveedor o use otro método de pago
`PAYMENT_METHOD_UNSUPPORTED`	Definitivo	Sí	El método de pago no es compatible con esta transacción	Pide al cliente que use un método de pago compatible
`PICKUP_CARD`	Definitivo	Sí	La tarjeta se ha denunciado 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 use otra tarjeta
`PROCESSING_ERROR`	Temporal	No	Se produjo un error al procesar la transacción	Transitorio: reintenta el pago; si persiste, pide al cliente que contacte con su banco
`PROVIDER_UNSUPPORTED`	Definitivo	No	El proveedor de pagos no admite este tipo de transacción	Pide al cliente que use otro método de pago
`REENTER_TRANSACTION`	Temporal	Sí	Es necesario volver a introducir la transacción	Pide al cliente que vuelva a intentar el pago
`REVOCATION_OF_AUTHORIZATION`	Definitivo	Sí	Se revocó la autorización de la transacción	Pide al cliente que use otro método de pago
`STOLEN_CARD`	Definitivo	Sí	La tarjeta se ha denunciado como robada	Muestra al cliente un mensaje de rechazo genérico; no reveles el motivo. Pídele que use otra tarjeta
`SUBSCRIPTION_NOT_ACTIVE`	Definitivo	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`	Definitivo	Sí	La transacción no está permitida para esta tarjeta o cuenta	Pide al cliente que contacte con su banco para permitir este tipo de transacción o use otra tarjeta
`TRANSACTION_NOT_APPROVED`	Definitivo	Sí	La transacción no fue aprobada	Pide al cliente que contacte con su banco o pruebe con otra tarjeta
`TRY_AGAIN_LATER`	Temporal	No	La transacción debe reintentarse más tarde	Transitorio: reintenta el pago más tarde
`UNKNOWN_ERROR`	Temporal	No	Se produjo un error desconocido	Reintenta el pago; si persiste, contacta 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, introducir correctamente los datos de la tarjeta). Cuando No, el rechazo se debe a problemas del sistema o restricciones bancarias que el cliente no puede resolver directamente.

Una tarjeta también puede ser rechazada cuando el propio motor de riesgo del banco emisor marca al titular como un cliente de alto riesgo, independientemente del merchant 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 merchant pueden anular la decisión. Pide al cliente que contacte con su banco para resolver el bloqueo o que use 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 temporales se reintentan automáticamente por ti; consulta Subscription Payment Retries. Para los errores de nivel de API y de lógica de negocio (como PAYMENT_NOT_SUCCEEDED o REFUND_WINDOW_EXPIRED) que no sean rechazos de tarjeta, consulta la referencia de Error Codes.

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 de negocio para fallos que no son rechazos.

Subscription Payment Retries

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

Subscription Dunning

Secuencias de emails que recuperan rechazos definitivos al solicitar la actualización del método de pago.

Soporte

Para obtener ayuda adicional con fallos de transacciones o problemas de integración, contacta con nuestro equipo de soporte en support@dodopayments.com.

API Reference

Checkout Sessions

Payments

Subscriptions

Discounts

Licenses

Entitlements

Customers

Customer Wallets

Products

Localized Pricing

Addons

Credit Entitlements

Meters

Usage Events

Refunds

Disputes

Payouts

Balance Ledger

Brands

Webhooks

Miscellaneous

Product Collections

Descripción general

Texto para el merchant frente a texto para el cliente

Handle Payment Failures

Rechazos temporales frente a rechazos definitivos

Motivos de fallo de transacciones

Gestión programática de fallos

Relacionado

Handle Payment Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

Soporte

​Descripción general

​Texto para el merchant frente a texto para el cliente

Handle Payment Failures

​Rechazos temporales frente a rechazos definitivos

​Motivos de fallo de transacciones

​Gestión programática de fallos

​Relacionado

Handle Payment Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

​Soporte

Descripción general

Texto para el merchant frente a texto para el cliente

Rechazos temporales frente a rechazos definitivos

Motivos de fallo de transacciones

Gestión programática de fallos

Relacionado

Soporte