Códigos de rechazo - Documentación Quentli

¿Qué son los códigos de rechazo?

Los códigos de rechazo son respuestas que envían los bancos emisores, procesadores de pago o redes de tarjetas cuando una transacción no puede ser completada. Estos códigos pueden indicar problemas temporales (como fondos insuficientes) o permanentes (como tarjeta expirada). Quentli simplifica los códigos de rechazo de los procesadores y bancos en un campo estandarizado (errorType en la API). Esto te permite manejar los errores de forma consistente sin importar qué procesador de pagos esté siendo utilizado.

Si encuentras errores frecuentes o patrones inusuales, no dudes en contactar a nuestro equipo de soporte en soporte@quentli.com.

Tabla de códigos de rechazo

Cuando procesas cargos a tarjetas de débito o crédito, podrías encontrarte con alguno de estos códigos de rechazo.

Código	Descripción	Consejo para el comercio	Consejo para el cliente
`AUTHENTICATION_REQUIRED`	Autenticación requerida	El banco emisor de la tarjeta requiere una autenticación adicional. Solicita al cliente que intente este pago desde el Portal de Clientes.	Este pago requiere verificación adicional. Por favor intenta desde el Portal de Clientes.
`DO_NOT_HONOR`	No honrar	El emisor de la tarjeta rechazó este pago por una razón desconocida. Pide al cliente que se ponga en contacto con su banco.	No pudimos procesar tu pago. Por favor intenta con otro método de pago o contacta a tu banco.
`INSUFFICIENT_FUNDS`	Fondos insuficientes	La tarjeta no tiene fondos suficientes para completar el pago. Pide al cliente que utilice otro método de pago.	No pudimos procesar tu pago. Por favor intenta con otro método de pago.
`CARD_EXPIRED`	Tarjeta expirada	La tarjeta está expirada. Pide al cliente que utilice otra tarjeta.	No pudimos procesar tu pago. Por favor intenta con otra tarjeta.
`INCORRECT_CVV`	CVV/CVC incorrecto	El código de seguridad de la tarjeta es incorrecto. Pide al cliente que verifique el código y intente nuevamente.	Los datos de tu tarjeta son incorrectos. Por favor verifica e intenta nuevamente.
`PROCESSING_ERROR`	Error de procesamiento	Ocurrió un error al procesar el pago. Pide al cliente que intente nuevamente más tarde.	No pudimos procesar tu pago. Por favor intenta más tarde.
`TRANSACTION_NOT_PERMITTED`	Transacción no permitida	El banco emisor de la tarjeta no permite este pago. Pide al cliente que se ponga en contacto con su banco	No pudimos procesar tu pago. Por favor intenta con otro método de pago o contacta a tu banco.
`AUTHENTICATION_FAILED`	Autenticación fallida	El proceso de autenticación de la tarjeta falló. Pide al cliente que intente nuevamente más tarde.	No pudimos verificar tu pago. Por favor intenta nuevamente.
`FRAUD`	Posible fraude	El procesador o banco emisor bloquearon este pago por sospecha de fraude. Pide al cliente que intente nuevamente o que se ponga en contacto con su banco.	No pudimos procesar tu pago. Por favor intenta con otro método de pago o contacta a tu banco.
`DECLINED`	Declinada	El banco emisor de la tarjeta rechazó este pago por una razón desconocida. Pide al cliente que se ponga en contacto con su banco.	No pudimos procesar tu pago. Vuelve a intentarlo o contacta a tu banco si el problema persiste.
`CARD_LOST_OR_STOLEN`	Tarjeta reportada	La tarjeta ha sido reportada como perdida o robada. Pide al cliente que utilice otro método de pago.	No pudimos procesar tu pago. Por favor intenta con otro método de pago.
`CARD_RESTRICTED`	Tarjeta restringida	La tarjeta tiene restricciones que impiden realizar este pago. Pide al cliente que utilice otro método de pago.	No pudimos procesar tu pago. Por favor intenta con otro método de pago.
`TEMPORARY_HOLD`	Retención temporal	El banco ha puesto una retención temporal en la tarjeta. Pide al cliente que se ponga en contacto con su banco.	No pudimos procesar tu pago. Por favor contacta a tu banco.
`EXCEEDS_WITHDRAWAL_LIMIT`	Límite excedido	El pago excede el límite de retiro de la tarjeta. Pide al cliente que utilice otro método de pago o que se ponga en contacto con su banco.	No pudimos procesar tu pago. Por favor intenta con otro método de pago o contacta a tu banco.
`INVALID_CARD_NUMBER`	Número inválido	El número de tarjeta es inválido. Pide al cliente que verifique los datos e intente nuevamente.	Los datos de tu tarjeta son incorrectos. Por favor verifica e intenta nuevamente.
`NETWORK_ISSUE`	Error de red	Hubo un error en la red de pagos. Pide al cliente que intente nuevamente más tarde.	No pudimos procesar tu pago. Por favor intenta más tarde.
`INVALID_MERCHANT`	Comercio inválido	El comercio no está autorizado para procesar este pago. Por favor contacta a soporte técnico.	No pudimos procesar tu pago. Por favor intenta más tarde.
`PROCESSOR_DECLINED`	Rechazado por el procesador	El procesador rechazó procesar este pago. Pide al cliente que intente nuevamente o que contacte a su banco.	No pudimos procesar tu pago. Por favor intenta nuevamente o contacta a tu banco si el problema persiste.

Errores específicos de domiciliación bancaria

Los siguientes errores son específicos para pagos por domiciliación bancaria (débito directo):

Código	Descripción	Consejo para el comercio	Consejo para el cliente
`INSUFFICIENT_ACCOUNT_FUNDS`	Fondos insuficientes	No hay fondos suficientes en la cuenta. Pide al cliente que verifique los fondos de su cuenta.	No hay fondos suficientes en la cuenta. Por favor contacta a tu banco.
`BLOCKED_ACCOUNT`	Cuenta bloqueada	La cuenta bancaria está bloqueada para domiciliaciones. Pide al cliente que se ponga en contacto con su banco.	Tu cuenta está bloqueada para domiciliaciones. Por favor contacta a tu banco.
`NONEXISTENT_ACCOUNT`	Cuenta inexistente	La cuenta bancaria no existe. Pide al cliente que verifique el número de cuenta.	La cuenta bancaria no existe. Por favor verifica el número de cuenta.
`CANCELED_ACCOUNT`	Cuenta cancelada	La cuenta bancaria ha sido cancelada. Pide al cliente que utilice otra cuenta.	Tu cuenta bancaria ha sido cancelada. Por favor utiliza otra cuenta.
`DIFFERENT_CURRENCY`	Divisa incorrecta	La cuenta bancaria está en una divisa diferente. Pide al cliente que utilice una cuenta en la divisa correcta.	Tu cuenta está en una divisa diferente. Por favor utiliza una cuenta en la divisa correcta.
`WRONG_BANK`	Banco incorrecto	La cuenta no pertenece al banco receptor. Pide al cliente que verifique el banco de la cuenta.	La cuenta no pertenece al banco receptor. Por favor verifica el banco de tu cuenta.
`MERCHANT_BLOCKED`	Comercio bloqueado	El cliente ha pedido a su banco que no autorice los pagos a tu comercio. Pide al cliente que autorice los pagos con su banco.	Has bloqueado los pagos a este comercio. Por favor autoriza los pagos si deseas continuar.
`AUTHORIZED_AMOUNT_EXCEEDED`	Límite excedido	El monto excede el límite autorizado por el cliente. Pide al cliente que aumente su límite o utilice otro método de pago.	El monto excede tu límite autorizado. Por favor aumenta tu límite o utiliza otro método de pago.
`SERVICE_CANCELED`	Servicio cancelado	El cliente ha cancelado el servicio de domiciliación. Pide al cliente que reactive el servicio.	Has cancelado el servicio de domiciliación. Por favor reactívalo si deseas continuar.
`SERVICE_NOT_AUTHORIZED`	Servicio no autorizado	El cliente no tiene autorizado el servicio de domiciliación. Pide al cliente que active el servicio en su banco.	No tienes autorizado el servicio de domiciliación. Por favor actívalo en tu banco.
`PAYMENT_ORDER_EXPIRED`	Orden vencida	La orden de domiciliación ha vencido. Pide al cliente que genere una nueva orden de pago.	La orden de domiciliación ha vencido. Por favor genera una nueva orden de pago.

Mejores prácticas

Para desarrolladores

Respeta los límites de reintento: No intentes procesar pagos más frecuentemente de lo permitido.
Muestra mensajes apropiados: Usa Consejo para el cliente para mostrar mensajes al cliente y Consejo para el comercio para tu equipo.
Implementa logging: Registra todos los errores para análisis posterior.

Para comercios

Comunica claramente: Usa los mensajes predefinidos para explicar los errores a tus clientes.
Ofrece alternativas: Siempre que sea posible, sugiere métodos de pago alternativos.
Capacita a tu equipo: Asegúrate de que tu equipo de soporte entienda estos códigos.
Monitorea patrones: Analiza los errores frecuentes para identificar problemas sistemáticos.

Estructura del error

Cuando un pago es rechazado, recibirás la siguiente información en el objeto PaymentAttempt de la API:

{
  "errorType": "INSUFFICIENT_FUNDS",
  "errorCode": "51",
  // Respuesta "en crudo" del procesador de pago (típicamente un JSON)
  "errorResponse": "..."
}

Si encuentras errores frecuentes o patrones inusuales, no dudes en contactar a nuestro equipo de soporte en soporte@quentli.com.

Conceptos

​¿Qué son los códigos de rechazo?

​Tabla de códigos de rechazo

​Errores específicos de domiciliación bancaria

​Mejores prácticas

​Para desarrolladores

​Para comercios

​Estructura del error

¿Qué son los códigos de rechazo?

Tabla de códigos de rechazo

Errores específicos de domiciliación bancaria

Mejores prácticas

Para desarrolladores

Para comercios

Estructura del error