Fallos de transacciones

Descripción general

Cuando un intento de pago falla, Dodo Payments devuelve un código de fallo estandarizado que indica el motivo. Los códigos son los mismos en todos los métodos de pago y procesadores de pagos, por lo que un único conjunto de reglas de gestión cubre todos los pagos fallidos. El webhook payment.failed y el objeto de pago exponen estos campos para un pago fallido:

error_code: un código de fallo estandarizado de la tabla siguiente.
error_message: una explicación escrita para ti, el merchant. Cuando error_code es uno de los códigos estandarizados siguientes, se trata de un encabezado más la acción recomendada, no del texto sin procesar del procesador de pagos.
retry_attempt: 0 para el cargo original, y 1 o superior para cada reintento programado de renovación de una suscripción. Los pagos que no son renovaciones de suscripción conservan el valor 0.

Usa estos códigos para proporcionar información clara a los clientes, decidir si un reintento puede tener éxito y recuperar más ingresos.

Texto para el merchant frente a texto para el cliente

Cada código de fallo estandarizado se asigna a dos mensajes, uno para ti y otro para tu cliente:

Audiencia	Dónde aparece	Qué indica
Tú	`error_message` en el pago, la página de detalles del pago en el dashboard y el correo electrónico de pago fallido que reciben los merchants	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 correos electrónicos de dunning	Una explicación breve y sencilla que puede poner en práctica, por ejemplo “Tu tarjeta aún no ha sido activada. Actívala con tu banco e inténtalo de nuevo.”

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

Handle Payment Failures

Una guía de desarrollo paso a paso para 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 es un rechazo temporal o un rechazo permanente. El tipo indica si un intento posterior con los mismos datos de pago puede tener éxito o si el cliente debe realizar alguna acción primero.

Tipo de rechazo	Qué significa	Qué hacer	Ejemplos
Rechazo temporal	Temporal. Los mismos datos de pago pueden tener éxito en un intento posterior.	Reintenta después de un tiempo.	`INSUFFICIENT_FUNDS`, `GENERIC_DECLINE`, `CARD_VELOCITY_EXCEEDED`, `PROCESSING_ERROR`, `NETWORK_ERROR`, `NETWORK_TIMEOUT`, `TRY_AGAIN_LATER`
Rechazo permanente	Un reintento con los mismos datos de pago y sin ninguna acción del cliente no cambia el resultado.	No vuelvas a intentar con los mismos datos. Pide al cliente que corrija sus datos, complete la autenticación, contacte con su banco o use otro método de pago.	`STOLEN_CARD`, `LOST_CARD`, `PICKUP_CARD`, `DO_NOT_HONOR`, `FRAUDULENT`, `INVALID_ACCOUNT`, `INCORRECT_CVC`

En las renovaciones de suscripciones, Dodo Payments aplica esta clasificación automáticamente. Subscription Payment Retries vuelve a intentar los rechazos temporales. Un rechazo permanente finaliza inmediatamente la cadena de reintentos; recupéralo con Subscription Dunning.

Nunca reveles al cliente el motivo real de STOLEN_CARD, LOST_CARD, PICKUP_CARD o FRAUDULENT. Revelar estos motivos puede alertar a un actor fraudulento. Muestra 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 el código específico solo internamente.Dodo Payments aplica esta regla en las superficies que controla. Para estos cuatro códigos, el checkout, el Customer Portal y los correos electrónicos de dunning muestran un mensaje de rechazo genérico, mientras que el texto destinado al merchant conserva el motivo real. Aplica la misma regla en cualquier lugar donde muestres error_message de la API del merchant a un cliente.

Motivos de fallo de transacciones

La tabla siguiente enumera 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`	Hard	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`	Hard	Sí	Se necesita autenticación adicional para completar la transacción	Pide al cliente que complete la autenticación 3DS. En 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 vuelva a intentarlo 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 vuelva a intentarlo, contacte con su banco o use 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`	Hard	Sí	El cliente canceló la transacción	Permite que el cliente reinicie el 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 de tarjetas lo consideran terminal	Pide al cliente que contacte con su banco. No vuelvas a intentarlo con la misma tarjeta
`EXPIRED_CARD`	Hard	Sí	La tarjeta ha caducado	Pide al cliente que use 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, sin indicar el motivo. Pídele que use otra tarjeta
`GENERIC_DECLINE`	Soft	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`	Hard	Sí	El CVC introducido era incorrecto	Pide al cliente que vuelva a introducir el CVC correcto
`INCORRECT_NUMBER`	Hard	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 use 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 contacte con su banco o use otra tarjeta
`INVALID_AMOUNT`	Hard	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`	Hard	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`	Hard	Sí	La información del titular de la tarjeta no es válida	Pide al cliente que corrija el nombre del titular
`INVALID_CVC`	Hard	Sí	El formato del CVC no es válido	Pide al cliente que vuelva a introducir un CVC válido
`INVALID_EXPIRY_YEAR`	Hard	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`	Hard	Sí	El PIN introducido es incorrecto	Pide al cliente que vuelva a introducir el PIN correcto
`INVALID_REQUEST`	Hard	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`	Hard	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 use otro método
`LIVE_MODE_TEST_CARD`	Hard	Sí	Se usó una tarjeta de prueba en modo live	Usa una tarjeta real. Una tarjeta de prueba siempre falla en modo live
`LOST_CARD`	Hard	Sí	Se ha informado de la pérdida de la tarjeta	Muestra al cliente un mensaje de rechazo genérico, sin indicar el motivo. Pídele que use otra tarjeta
`MANDATE_INVALID`	Hard	Sí	El mandato de pago no es válido	Pide al cliente que configure de nuevo el mandato de pago
`MANDATE_REQUIRED`	Hard	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`	Hard	No	El sistema requiere un mandato para este tipo de transacción	Completa 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. Vuelve a intentar el pago después de un breve intervalo
`NETWORK_TIMEOUT`	Soft	No	La solicitud de red agotó el tiempo de espera	Transitorio. Vuelve a intentar el pago después de un breve intervalo
`ORDER_ALREADY_EXISTS`	Hard	No	Ya existe un pedido para esta transacción (creación de pedido duplicada)	Comprueba el estado del pedido existente antes de volver a intentarlo. Contacta con soporte si el problema persiste
`ORDER_CREATION_FAILED`	Soft	No	No se pudo crear el pedido de la transacción	Error transitorio o del sistema. Vuelve a intentar el pago y contacta 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 contacte con su proveedor o use 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 use un método de pago compatible
`PICKUP_CARD`	Hard	Sí	Se ha informado de que la tarjeta se perdió o fue robada y se marcó para su retirada	Muestra al cliente un mensaje de rechazo genérico, sin indicar el motivo. Pídele que use otra tarjeta
`PROCESSING_ERROR`	Soft	No	Se produjo un error al procesar la transacción	Transitorio. Vuelve a intentar el pago. Si el problema persiste, pide al cliente que contacte con su banco
`PROVIDER_UNSUPPORTED`	Hard	No	El proveedor de pagos no admite este tipo de transacción	Pide al cliente que use otro método de pago
`REENTER_TRANSACTION`	Soft	Sí	Es necesario volver a introducir la transacción	Pide al cliente que vuelva a intentar el pago
`REVOCATION_OF_AUTHORIZATION`	Hard	Sí	Se revocó la autorización de la transacción	Pide al cliente que use otro método de pago
`STOLEN_CARD`	Hard	Sí	Se ha informado de que la tarjeta fue robada	Muestra al cliente un mensaje de rechazo genérico, sin indicar el motivo. Pídele que use 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`	Soft	Sí	La transacción no está permitida para esta tarjeta o cuenta	Vuelve a intentarlo después de un tiempo. Si sigue fallando, pide al cliente que contacte con su banco para permitir este tipo de transacción o que use otra tarjeta
`TRANSACTION_NOT_APPROVED`	Soft	Sí	La transacción no fue aprobada	Vuelve a intentarlo después de un tiempo. Si sigue fallando, pide al cliente que contacte con su banco o pruebe con otra tarjeta
`TRY_AGAIN_LATER`	Soft	No	La transacción debe reintentarse más tarde	Transitorio. Vuelve a intentar el pago más tarde
`UNKNOWN_ERROR`	Soft	No	Se produjo un error desconocido	Vuelve a intentar el pago. Si el problema persiste, contacta con soporte

Error del usuario indica si el cliente puede resolver el rechazo. Yes significa que el cliente puede solucionar el problema, por ejemplo, introduciendo correctamente los datos de la tarjeta. No significa que el rechazo se debe a un problema del sistema o a una restricción bancaria, y que el cliente no puede resolverlo directamente.

Un banco emisor también puede rechazar una tarjeta porque su propio motor de riesgo marca al titular de la tarjeta como 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. 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 el bloqueo, 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 en la tabla y decide si debes reintentar. En las renovaciones de suscripciones, Dodo Payments reintenta por ti los rechazos temporales. Consulta Subscription Payment Retries. Para consultar errores de la API y de la lógica empresarial que no son rechazos de tarjetas, como PAYMENT_NOT_SUCCEEDED o REFUND_WINDOW_EXPIRED, 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 más ayuda con fallos de transacciones o problemas de integración, contacta con el 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

Moderation

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