Códigos de error para transacciones con tarjeta presente

Te contamos los errores comunes en las transacciones con tarjeta presente y cómo solucionarlos.

Códigos de estado HTTP

Te mostramos a continuación cuáles son los códigos de estado HTTP más comunes, su mensaje estándar asociado, así como una descripción de la respuesta.

A continuación te mostramos los códigos que podrías recibir.

Código	Mensaje	Detalle
200	OK	El proceso fue exitoso; este funcionó como se esperaba, según el método HTTP.
400	Bad Request (Solicitud incorrecta)	El servidor no puede interpretar la solicitud (sintaxis incorrecta, tamaño demasiado grande, parámetros faltantes).
401	Authorization Required (Autorización requerida)	Las credenciales deben estar autenticadas o la autenticación falló.
403	Forbidden (Prohibido)	No se tienen los permisos necesarios para realizar esta acción.
404	Not Found (No encontrado)	Recurso o página no encontrada.
409	Conflict (Conflicto)	El requerimiento no puede ser procesado debido a un conflicto con el recurso (e.j. múltiples actualizaciones simultáneas.
410	Gone (No disponible)	El recurso solicitado ha sido eliminado del servidor y ya no estará disponible.
412	Precondition failed (Condición previa falló)	Indica que se ha denegado el acceso al recurso de destino.
429	Too Many Requests (Demasiadas solicitudes)	Se han enviado demasiadas solicitudes en un corto período de tiempo.
430	Request Header Fields Too Large (Los campos del encabezado de solicitud son demasiado grandes)	Este código de estado indica que el servidor no está dispuesto a procesar la solicitud porque sus campos de encabezado son demasiado grandes.
500	Internal Server Error (Error interno del servidor)	Se produjo un error inesperado en el servidor.
502	Bad Gateway (Puerta de enlace incorrecta)	El servidor (que actúa como proxy o puerta de enlace) recibió una respuesta no válida de otro servidor
503	Service Temporarily Unavailable (Servicio temporalmente no disponible)	El servidor no está disponible (normalmente porque está en mantenimiento o porque está sobrecargado).
504	Gateway Timeout (Tiempo de espera de puerta de enlace)	El servidor (que actúa como proxy o puerta de enlace) no ha recibido una respuesta del otro servidor a tiempo.

Códigos de pre-procesamiento de Kushki

Los siguientes códigos de error son generados directamente por Kushki durante la etapa de validación interna, antes de que la transacción sea enviada al procesador o a la marca de la tarjeta.

Estos códigos suelen estar relacionados con la validación de la carga útil (payload), reglas de negocio, límites de tiempo o el estado de transacciones previas en nuestra base de datos.

Cuando se presente uno de estos errores, lo recibirás en el cuerpo de la respuesta con una estructura similar a la siguiente:

{
  "code": "E047",
  "details": {
    "Origin": "Process Reverse | Transaction",
    "Message": "Code: K007, Message: \"Error al obtener la transacción actualizada\", StatusCode: 500, Reverse: false"
  },
  "message": "TimeOut por procesador inalcanzable"
}

Código	Mensaje	Descripción	Sugerencia / ¿Qué hacer?
E001	Cuerpo de la petición inválido.	Se produce cuando en el body del request no se envía uno o varios campos obligatorios.	Revisa la documentación de Kushki donde se detallan los campos obligatorios y opcionales para este endpoint.
E001	Ocurrió un error al guardar la transacción en la base de datos.	Se produjo un error al hacer el guardado inicial de la transacción en DynamoDB.	Revisa los logs internos para verificar el error retornado por la base de datos.
E002	Ocurrió un error al enviar u obtener transacción al gateway.	Los gateways respondieron algún error distinto de K007.	Revisa qué código de error en la respuesta entregaron los gateways.
E002	Ha ocurrido un error inesperado.	Se produjo un error distinto a los mencionados en la documentación estándar.	Revisa los logs de la función Lambda de transacciones para más detalles.
E006	Ocurrió un error al obtener la transacción en la base de datos.	Ocurrió un error al consultar la transacción original. Frecuente al intentar realizar operaciones de Void, Refund o Capture.	Revisa los logs para validar la respuesta de DynamoDB al consultar el registro.
E011	Ocurrió un error al actualizar la transacción.	Error (distinto a Timeout) al intentar actualizar el estado de la transacción en DynamoDB.	Revisa los logs de la función Lambda de update trx.
E014	Ocurrió un error al validar la transacción original.	Ocurre únicamente en Reautorizaciones, cuando la transacción previa no es una preautorización/reautorización o no se encuentra disponible.	Verifica que la transacción que se envía a reautorizar cumpla con los criterios descritos.
E015	La transacción previa no consta como aprobada.	Se produce en peticiones de Void, Refund o Capture cuando la transacción original vinculada no está en estado aprobada.	Asegúrate de enviar operaciones de anulación, reembolso o captura solo sobre transacciones exitosas.
E016	Refund no disponible.	Se produce por: Aún no pasa el tiempo mínimo permitido (1 día) para ejecutar un Refund. La fecha de la transacción excede el límite de días permitidos (varía por país). La transacción original NO es Charge, Capture, Checkout o PosTip.	Valida que la transacción cumpla con las condiciones temporales y de tipo permitidas para reembolsos.
E017	Transacción no disponible para anulación.	Se intenta anular una transacción con un monto mayor al de la venta. A diferencia del E023, puede ocurrir si entran 2 anulaciones simultáneas.	Verifica el monto restante disponible para anular y evita enviar peticiones duplicadas.
E018	Anulación no disponible.	Se solicita anular (Void) un tipo de transacción no soportada para esta operación.	Solo puedes anular transacciones tipo: Charge, Preauth, Reauth, Capture, CheckIn, CheckOut, Tip o PosTip.
E020	Transacción no disponible para captura.	Se intenta capturar una transacción cuyo tiempo límite ya expiró (el límite varía según el país de procesamiento).	Asegúrate de no exceder la ventana de tiempo estipulada para hacer la captura.
E023	Monto del void superior al del sale.	Se envía un Void (total o parcial) o un Refund por un valor que supera el monto de la venta original.	Ajusta el monto de la petición; este no debe exceder el valor original.
E024	Datos de lectura de tarjeta no válidos.	Los datos de los tracks (banda magnética/chip) enviados son incorrectos o están mal formateados.	Valida y envía los datos de lectura de la tarjeta correctamente.
E041	Operación no permitida.	Se produce por: Captura sobre una transacción que no es preautorización. El monto a capturar excede el total + n% de la preautorización original. Intento de Void parcial de una preautorización. Uso de un `transaction_type` no soportado. Transacción dirigida a una franquicia desconocida.	Ajusta los parámetros de la petición según las reglas de negocio de la operación deseada.
E042	El código de moneda es diferente al de la transacción inicial.	Se envía una operación posterior (Void, Refund o Capture) donde el campo `currency` no coincide con el de la venta original.	El campo `currency` debe ser exactamente el mismo que se utilizó en el Sale.
E044	Anulación no permitida.	Se intenta realizar un Void directamente sobre una Reautorización.	Las reautorizaciones no admiten anulaciones directas.
E046	Reverso no disponible por exceso de tiempo.	Se intenta procesar un reverso manual después del tiempo máximo permitido (29 segundos desde la transacción original).	No realices intentos de reversos manuales una vez transcurridos los 29 segundos.
E047	TimeOut por procesador inalcanzable.	Los gateways retornaron `K007` (Timeout esperando respuesta de la franquicia), o la base de datos excedió el tiempo permitido para actualizar.	Revisa los logs del API o del gateway para identificar el cuello de botella.
E048	La transacción previa ya se encuentra reversada.	Intento de Void o Refund sobre una transacción previamente reversada. También aplica si se envía un Smart Void duplicado (mismo `client_transaction_id`).	Valida el estado actual de la transacción antes de intentar anularla nuevamente.
E049	Transacción no disponible para cashback.	La transacción no cumple con las características requeridas para procesar un retiro de efectivo (Cashback).	El Cashback exige: Tipo Charge, Aprobada vía Chip/Contactless, franquicia Visa/Mastercard, transacción doméstica y NO diferida.
E055	Tipo de moneda no permitido.	Se envía un código de moneda (`currency`) diferente a la moneda local del país donde opera el comercio.	Configura el `currency` oficial correspondiente al país de tu credencial de comercio.
E322	Ocurrió un error procesando la transacción (Regla de seguridad).	Se produjo un fallo en la capa intermedia del middleware de `SecurityRule`.	Escala el incidente y revisa los logs de la función Lambda correspondiente.

Códigos retornados por Kushki en transacciones con tarjeta presente

Los códigos de respuesta recibidos por los procesadores y emisores aparecerán en el objeto kushki_response, tal como en el siguiente ejemplo.

"kushki_response": {
        "code": "01",
        "message": "Refer to card issuer"
    },

Error 006

Este código de error aparece cuando Kushki bloquea la tarjeta, por ejemplo si la marca no está soportada

"kushki_response": {
        "code": "006",
        "message": "Card brand not supported"
    }

A continuación encuentra un listado de los códigos de declinación más comunes.

ISO Error Code	Description	Source
00	Approved or completed successfully	Visa, Mastercard
01	Refer to card issuer	Visa, Mastercard
02	Refer to card issuer, special condition	Visa
03	Invalid merchant	Visa, Mastercard
04	Pick up card (no fraud)	Visa, Mastercard
05	Do not honor	Visa, Mastercard
06	Error	Visa
07	Pick up card, special condition (fraud account)	Visa
08	Honor with ID	Mastercard
10	Partial Approval	Visa, Mastercard
11	Approved (VIP)	Visa
12	Invalid transaction	Visa, Mastercard
13	Invalid amount	Visa, Mastercard
14	Invalid card number	Visa, Mastercard
15	Invalid issuer	Visa, Mastercard
19	Re-enter transaction	Visa
21	No action taken	Visa
25	Unable to locate record in file	Visa
28	File is temporarily unavailable for update or inquiry	Visa
30	Format error	Visa, Mastercard
33	Expired card	Visa
34	Suspected fraud	Visa
35	Card acceptor contact acquirer	Visa
36	Restricted card	Visa
37	Card acceptor call acquirer security	Visa
38	Allowable PIN tries exceeded	Visa
39	No credit account	Visa
40	Command rejected	Visa
41	Lost card	Visa, Mastercard
43	Stolen card	Visa, Mastercard
46	Closed account	Visa
51	Insufficient funds/over credit limit	Visa, Mastercard
52	No checking account	Visa
53	No savings account	Visa
54	Expired card or expiration date missing	Visa, Mastercard
55	Invalid PIN	Visa, Mastercard
57	Transaction not permitted to issuer/cardholder	Visa, Mastercard
58	Transaction not permitted to acquirer/terminal	Visa, Mastercard
59	Suspected fraud	Visa
61	Exceeds withdrawal amount limit	Visa, Mastercard
62	Restricted card	Visa, Mastercard
63	Security violation	Visa, Mastercard
64	Transaction does not fulfill AML requirement	Visa
65	Exceeds withdrawal count limit	Visa, Mastercard
70	PIN data required	Visa
71	Issuer PIN Not Changed	Mastercard
74	Different value than that used for PIN encryption errors	Visa
75	Allowable number of PIN-entry tries exceeded	Visa, Mastercard
76	Unsolicited reversal	Visa, Mastercard
77	Invalid/nonexistent 'From Account' specified	Mastercard
78	Blocked, first used or special condition	Visa, Mastercard
79	Reversed (by switch)	Visa
80	No financial impact	Visa
81	Cryptographic error	Visa, Mastercard
82	Policy / Negative online authentication failure	Visa, Mastercard
83	Fraud/Security	Mastercard
84	Invalid Authorization Life Cycle	Mastercard
85	Not declined, valid for all zero amount transactions	Visa, Mastercard
86	Cannot verify PIN	Visa, Mastercard
87	Purchase Amount Only, No Cash Back Allowed	Mastercard
88	Cryptographic failure	Mastercard
89	Unacceptable PIN	Mastercard
91	Authorization System or issuer system inoperative	Visa, Mastercard
92	Unable to route transaction	Visa, Mastercard
93	Transaction cannot be completed—violation of law	Visa
94	Duplicate transmission detected	Visa, Mastercard
96	System error	Visa, Mastercard
N0	Force STIP	Visa
N3	Cash service not available	Visa
N4	Cash request exceeds issuer or approved limit	Visa
N7	Decline for CVV2 failure	Visa
N8	Transaction amount exceeds pre-authorized approval amount	Visa
R0	Stop payment order	Visa
R1	Revocation of authorization order	Visa
R2	Transaction does not qualify for Visa PIN	Visa
R3	Revocation of all authorizations order	Visa
Z3	Unable to go online; offline-declined	Visa

Códigos retornados por Kushki en cancelaciones e intentos de reversión

Los códigos de respuesta recibidos por los procesadores y emisores aparecerán en el objeto kushki_response, tal como en el siguiente ejemplo.

"kushki_response": {
        "code": "01",
        "message": "Refer to card issuer"
    },

A continuación encuentra la información de los códigos y mensajes enviados por Kushki para describir los códigos de respuesta de la solicitud realizada con transacciones con tarjeta presente. En la columna “¿Qué hacer?” encontrarás una explicación detallada de las causas y el procedimiento que debes realizar.

Código	Mensaje	¿Qué hacer?
000	Approved Transaction (Transacción aprobada)	Indica que la transacción fue aprobada exitosamente.
01	Refer to card issuer (Comuníquese con la compañía que expidió la tarjeta)	El titular de la tarjeta debe comunicarse con el emisor de su tarjeta para comprender por qué se rechazó la transacción.
04	Capture card (Capturar tarjeta)	El titular de la tarjeta debe volver a intentar la transacción.
05	Do not honor (La transacción no fue aceptada)	El titular de la tarjeta debe volver a intentar la transacción.
12	Invalid transaction (Transacción inválida)	La transacción no está permitida por el procesador de pagos ni por el emisor de la tarjeta. Póngase en contacto con el emisor de la tarjeta.
32	Expired card (Tarjeta expirada)	El titular de la tarjeta debe utilizar una tarjeta alternativa.
41	Lost card (Tarjeta perdida)	El titular de la tarjeta debe comunicarse con el emisor de su tarjeta para que revise el caso.
57	Transaction not permitted to cardholder (La transacción no está permitida para el titular de la tarjeta)	El titular de la tarjeta debe comunicarse con el emisor de su tarjeta para que revise el caso.
62	Restricted card (Tarjeta restringida)	El titular de la tarjeta debe comunicarse con el emisor de su tarjeta para que revise el caso.
91	Authorization System or issuer system inoperative (Sistema de autorización o sistema emisor inoperativo)	El titular de la tarjeta debe volver a intentar la transacción.
92	Unable to route transaction (No se puede enrutar la transacción)	El titular de la tarjeta debe volver a intentarlo o contactar al emisor.
6P	Verification data failed (Los datos de verificación fallaron)	Reintentar la transacción.
E016	Refund not available (Reembolso no disponible)	Comprueba que el reembolso está dentro del plazo permitido

Datos de prueba

Realiza los ajustes necesarios en tu sistema con los datos de prueba.

Códigos de error para transacciones con tarjeta presente

Códigos de estado HTTP#

Códigos de pre-procesamiento de Kushki#

Códigos retornados por Kushki en transacciones con tarjeta presente#

Error 006#

Códigos retornados por Kushki en cancelaciones e intentos de reversión#

Códigos de estado HTTP

Códigos de pre-procesamiento de Kushki

Códigos retornados por Kushki en transacciones con tarjeta presente

Error 006

Códigos retornados por Kushki en cancelaciones e intentos de reversión