Códigos de error en cargos recurrentes

16 septiembre 2024

Aprende cómo manejar los diferentes tipos de mensajes de error recibidos durante las transacciones para cada medio de pago.

¿Qué tipo de códigos de respuesta retorna Kushki?

Kushki retornará dos códigos diferentes de respuesta para indicar el éxito o fallo de las transacciones: processorError y code. El campo code retorna mensajes genéricos. Por su parte, el campo processorError indica que la transacción ha pasado a través del procesador y probablemente ha sido mapeado por Kushki para darte una idea específica de porqué tu transacción no se pudo completar.

Códigos retornados por Kushki para cargos recurrentes con tarjeta

La API de Kushki realizará validaciones antes de enviar la transacción hacia los procesadores. Si este es el caso, el campo processorError no aparecerá en la respuesta y solo verás el campo code . El siguiente es un ejemplo de un mensaje retornado por el API de Kushki:

    {"message": "Comercio deshabilitado",
    "code": "K026" }

A continuación te presentamos los códigos de error genéricos retornados en el campo code.

code	message	¿Qué hacer?
K001	El cuerpo de la petición es inválido	Revisar el body de la petición
K003	Error en la respuesta del gateway	Reintentar, en caso de que el error persista, comunícate con el equipo de soporte de Kushki para revisar el caso
K004	Id de comercio no válido	Verificar el public merchant ID o el private merchant ID y reintentar
K006	Rechazo suscripción por cobro validación	Reintentar la transacción
K007	Tarjeta bloqueada por el emisor	Internar con otra tarjeta
K008	Token incorrecto	Completar nuevamente los datos y reintentar
K010	Comercio no habilitado para suscripciones	Comunícate con el equipo de soporte de Kushki para revisar el caso
K011	Fecha de inicio inválida	Revisar la fecha de inicio enviada en la variable `startDate`
K012	ID de suscripción no válida	Verificar el monto a capturar y reintentar
K013	Fecha final inválida	Revisar la fecha enviada en la variable `endDate`
K014	Monto de captura inválido	Verificar el monto de la captura y reintentar
K015	Transacción no permitida sin ccv2	Verificar el CVV y reintentar
K016	No es posible actualizar la subscripción	Verificar la información enviada y reintentar
K020	ERROR_REJECTED_TRANSACTION	Reintentar la transacción, en caso de que el error persista comunícate con el equipo de soporte de Kushki para revisar el caso
K021	Rechazo suscripción por SiftScience	Reintentar la transacción ya que quizá se debe a un error en la conexión con el proveedor de validación antifraude
K022	Rechazo suscripción por token reutilizado	Solicitar un nuevo token y reintentar
K023	Monto del void superior al del sale	Este mensaje se presenta cuando se trata de hacer un void parcial pero el monto es superior al monto de la venta
K024	El valor del monto debe ser mayor a cero	Verificar el monto enviado y reintentar
K025	Tarjeta inválida	Intentar con otra tarjeta
K026	Comercio deshabilitado	Comunícate con el equipo de soporte de Kushki para revisar el caso
K027	No se pudo completar la transacción	Intentar nuevamente la transacción
K028	Processor Declined	Comunícate con el equipo de soporte de Kushki para revisar el caso
K029	Los datos de tarjeta no coiciden en la subscripción y su confirmación	Revisar los datos enviados y reintentar
K031	No existe la subscripción webpay a confirmar	Revisar el ID de suscripción enviado y reintentar
K032	La subscripción webpay ha sido confirmada anteriormente	-
K034	No existen procesadores	Comunícate con el equipo de soporte de Kushki para revisar el caso
K035	Procesador no disponible	Reintenta nuevamente. Si el error persiste, comunícate con el equipo de soporte de Kushki para revisar el caso
K036	Error de integración con un tercero	Comunícate con el equipo de soporte de Kushki para revisar el caso
K037	Subscripción no encontrada	Revisa el ID de suscripción enviado e inténtalo de nuevo
K038	No se puede realizar un void parcial sin especificar el valor a sustraer	Especificar el objecto `amount`
K039	La suma de los valores de la propiedad amount debe ser mayor a 0	Se debe enviar un monto mayor a 0 en la propiedad amount.
K040	El ID de comercio no corresponde a la credencial enviada	Se debe enviar un monto mayor a 0 en la propiedad amount.
K041	Operación no permitida	Comunícate con el equipo de soporte de Kushki para revisar el caso
K042	El código de moneda es diferente al de la transacción inicial.	Este mensaje se presenta cuando se envía un código de moneda diferente al de la transacción inicial. Envía el código de moneda correcto.
K043	Transacción de preautorización no corresponde a la suscripción	Revisa la información enviada e inténtalo nuevamente
K044	El bin ingresado no soporta este método de pago	Intenta con otra tarjeta
K045	Transacción de captura realizada anteriormente	No es posible realizar la captura nuevamente
K046	La operación cayó en timeout, por favor inténtelo de nuevo	Reintenta la transacción
K047	Ha ocurrido un error inesperado	Reintenta la transacción
K048	Procesador no soporta el actual método	Comunícate con el equipo de soporte de Kushki para revisar el caso
K049	Tarjeta expirada	Intenta con otra tarjet
K050	Este token ya no es válido	Revisar los datos enviados y reintentar
K051	El comercio no tiene habilitado la opción de diferidos	Comunícate con el equipo de soporte de Kushki para revisar el caso
K052	ERROR_REJECTED_TRANSACTION	Reintentar la transacción, en caso de que el error persista comunícate con el equipo de soporte de Kushki para revisar el caso
K027	La operación cayó en timeout, por favor inténtelo de nuevo	Intentar nuevamente la transacción

Códigos de error cuando la transacción viaja al procesador

A continuación te presentamos los códigos de error retornados en el campo processorError, de forma que puedas usar estos para mapear los mensajes de tu aplicación.

Las columnas processorError y message te mostrarán el código de error y mensaje enviado desde Kushki. En la columna ¿Qué hacer? te damos una explicación más detallada de las causas y el posible procedimiento a seguir.

processorError	message	¿Qué hacer?
501	Transacción rechazada. Póngase en contacto con el emisor de su tarjeta	El tarjetahabiente deberá ponerse en contacto con el emisor de su tarjeta para conocer las razones por las cuales se rechazó la transacción
503	El número de comercio no está registrado	El número de terminal o código del comercio no está registrado o habilitado en el procesador. Comunícate con el equipo de soporte de Kushki para revisar el caso.
504	La tarjeta ingresada ha sido reportada.	El tarjetahabiente deberá usar una tarjeta diferente para procesar la transacción y ponerse en contacto con el emisor de su tarjeta para revisar el caso.
505	La transacción fue declinada por el procesador o emisor.	El tarjetahabiente deberá esperar un par de minutos y reintentar, de lo contrario, usar una tarjeta alternativa.
512	Transacción no permitida por el emisor.	La Transacción no está permitida por el procesador o el emisor. El tarjetahabiente deberá usar una tarjeta alternativa.
513	El monto que ingresó contiene una sintaxis no válida	Es necesario verificar el monto ingresado y reintentar. Por ejemplo, es posible que se hayan ingresado caracteres no permitidos en el monto, como `,` en lugar de `.` para separar decimales.
514	El número de tarjeta ingresado no es válido	El tarjetahabiente deberá verificar que el número de tarjeta haya sido ingresado correctamente y reintentar.
515	El emisor no puede autorizar esta transacción	El procesador o franquicia rechazó el BIN enviado. El tarjetahabiente deberá usar otra tarjeta.
518	Has ingresado una tarjeta vencida	La tarjeta se encuentra caducada o la fecha es incorrecta. El tarjetahabiente deberá revisar que la fecha esté correcta o intentar con otra tarjeta.
519	Se produjo un error al procesar la operación. Inténtalo de nuevo	El tarjetahabiente deberá reintentar la transacción.
520	El nombre del titular de la tarjeta ingresado no es correcto	Ingresar nuevamente el nombre del tarjetahabiente y reintentar.
521	El apellido del titular de la tarjeta ingresado no es correcto	Ingresar nuevamente el apellido del tarjetahabiente y reintentar.
522	El correo electrónico que ha ingresado no es válido.	Ingresar nuevamente el correo electrónico del tarjetahabiente y reintentar.
523	El número de la dirección IP es incorrecto.	Verificar que la transacción se esté efectuando desde una dirección IP válida.
524	El número de identificación que ha ingresado es incorrecto.	Ingresar nuevamente el tipo y número de identificación del tarjetahabiente y reintentar.
525	La información encriptada no es válida	El proceso de encriptación de la información no pudo completarse correctamente. Comunícate con el equipo de soporte de Kushki para revisar el caso.
526	El comercio no tiene permiso para procesar una transacción	Se debe a una restricción del procesador al comercio. Comunícate con el equipo de soporte de Kushki para revisar el caso.
527	El monto enviado no puede ser cero	El monto de esta transacción no puede ser cero. Se debe ingresar un monto diferente y reintentar.
528	Monto de la transacción es diferente al monto de la venta inicial	El monto enviando en el token debe ser igual al de la compra. Será necesario asegurarse que el monto a pagar sea el correcto.
529	No ha sido posible encontrar la transacción	Al realizar el reverso o anulación no fue posible encontrar el mensaje original. Comunícate con el equipo de soporte de Kushki para revisar el caso.
530	Transacción rechazada por error de formato	Al momento de realizar la transacción se presentó un error en el formato de la misma. Comunícate con el equipo de soporte de Kushki para revisar el caso.
541	Esta tarjeta ha sido reportada como perdida	El tarjetahabiente deberá usar una tarjeta diferente para procesar la transacción y ponerse en contacto con el emisor de su tarjeta para revisar el caso.
543	Esta tarjeta ha sido reportada como robada	El tarjetahabiente deberá usar una tarjeta diferente para procesar la transacción y ponerse en contacto con el emisor de su tarjeta para revisar el caso.
551	No hay fondos suficientes para completar la operación.	El tarjetahabiente deberá usar una tarjeta diferente para procesar la transacción ya que la tarjeta ingresada no cuenta con los fondos suficientes para procesar la transacción.
552	El tipo de cuenta ingresado no es válido	El tarjetahabiente deberá verificar el tipo de cuenta seleccionada e internar nuevamente.
553	La tarjeta no es compatible	La marca de la tarjeta ingresada no es compatible para poder efectuar la autorización. El tarjetahabiente deberá usar una tarjeta diferente para procesar la transacción.
554	El tipo de moneda no es válido	El procesador o emisor no acepta transacciones en la moneda seleccionada. Comunícate con el equipo de soporte de Kushki para revisar el caso.
555	La solicitud enviada no es válida	Ha existido una novedad en la solicitud de la transacción que se ha realizado. Comunícate con el equipo de soporte de Kushki para revisar el caso.
556	La transacción se encuentra anulada	La transacción que se está intentando anular o reversar ya fue anulada anteriormente
557	El emisor no puede autorizar esta transacción	Por restricciones del emisor no es posible autorizar la Transacción. El tarjetahabiente deberá cambiar de tarjeta o medio de pago y ponerse en contacto con el emisor de su tarjeta para revisar el caso.
558	Transacción no permitida al comercio	Por restricciones del procesador no es posible autorizar la Transacción al comercio. Comunícate con el equipo de soporte de Kushki para revisar el caso.
559	La transacción ha sido considerada como una sospecha de fraude	La transacción que se ha realizado fue declinada por el procesador o emisor por sospecha de fraude.
560	El monto ingresado es menor o mayor de lo permitido	El monto enviado en la transacción es menor o mayor a los límites que han sido establecidos. El tarjetahabiente deberá verificar el monto de la transacción y reintentar.
561	Se ha excedido el límite diario de transacciones	El tarjetahabiente ha superado el límite de actividad en cantidad o monto de transacciones diarias
562	Tarjeta restringida por el emisor	El emisor ha declinado la transacción porque aplicó restricciones al tarjetahabiente. El tarjetahabiente deberá ponerse en contacto con el emisor de su tarjeta para revisar el caso.
563	Operación rechazada por violación de seguridad	El emisor o procesador declinó la transacción porque existe una violación de seguridad.
564	El token ingresado no es válido o ha expirado	El token que se está usando no posee un formato válido, no existe o ya fue usado en una transacción
565	La transacción fue declinada por reglas de seguridad	La transacciones está siendo declinada por reglas de seguridad configuradas a la tarjeta o al comercio
566	El token es inváalido , o ya fue usado en otra transacción	El token que se está usando no posee un formato válido, no existe o ya fue usado en una transacción. Comunícate con el equipo de soporte de Kushki para revisar el caso.
567	El monto de la transacción es requerido	Es obligatorio enviar un valor en el campo “amount”.
568	El número de ticket de la transacción no es válido	Ingresa nuevamente el número de ticket, si el error persiste, comunícate con el equipo de soporte de Kushki para revisar el caso.
579	La fecha de vencimiento ingresada es incorrecta	El tarjetahabiente deberá ingresar nuevamente la fecha de vencimiento e intentar otra vez.
580	El diferido enviado no es correcto	El tipo de diferido o formato del diferido que se está empleando no es el correcto. Comunícate con el equipo de soporte de Kushki para revisar el caso.
581	Las credenciales no son correctas	Verífica las credenciales enviadas e íntentalo de nuevo
582	El número de seguridad (cvv2) ingresado no es correcto	El tarjetahabiente deberá ingresar nuevamente el código de seguridad y reintentar la transacción.
583	La operación ya se canceló o se alcanzó el tiempo máximo para revertir	No es posible cancelar o revertir la transacción porque ya fue cancelada, no se encontró la transacción original , o se ha cumplido el tiempo máximo permitido para poder reversarla. Comunícate con el equipo de soporte de Kushki para revisar el caso.
591	Transacción no autorizada. Emisor inoperativo	Esperar un par de minutos y reintentar, de lo contrario, usar una tarjeta alternativa.
594	La transacción rechazada parece ser una operación duplicada	La transacción fue declinada porque existe una coincidencia con otra transacción realizada anteriormente. Comúnmente porque se está enviando el mismo número de referencia.
596	El emisor ha tenido un problema al autorizar la transacción.	El tarjetahabiente deberá esperar un par de minutos y reintentar, de lo contrario, usar una tarjeta alternativa o comunicarse con el emisor de la tarjeta para verificar.

Códigos de estado HTTP

Kushki podrá retornar diferentes códigos de estado HTTP dependiendo de las solicitudes realizadas. Existen cinco categorías de respuestas estándar, descritas en la siguiente imagen:

Códigos de estado HTTP

A continuación te presentamos los códigos de estado HTTP más comunes, su mensaje estándar asociado, así como una descripción más detallada de la respuesta.

Código	Mensaje	Detalle
200	OK	El proceso fue exitoso. Todo funcionó de la manera que se esperaba, según el método HTTP
400	Bad Request	El servidor no puede interpretar la solicitud (sintaxis incorrecta, tamaño demasiado grande, faltan parámetros)
401	Authorization Required	Se deben autenticar las credenciales, o bien, la autenticación ha fallado
403	Forbidden	No se cuenta con los permisos necesarios para realizar esa acción
404	Not Found	Recurso o página no encontrada
409	Conflict	La solicitud no puede ser procesada por un conflicto con el recurso (por ejemplo, múltiples actualizaciones simultáneas)
410	Gone	El recurso solicitado ha sido borrado del servidor, y ya no está ni estará disponible
429	Too Many Requests	Se han enviado demasiadas solicitudes en un tiempo determinado
430	Request Header Fields Too Large	Código no oficial, aplica solo para Shopify. Similar al código 429
500	Internal Server Error	Ocurrió un error inesperado del lado del servidor
502	Bad Gateway	El servidor (actuando como proxy o gateway) recibió una respuesta inválida de otro servidor
503	Service Temporarily Unavailable	El servidor no está disponible (comúnmente es porque se encuentra en mantenimiento, o porque está sobrecargado)
504	Gateway Timeout	El servidor (actuando como proxy o gateway) no ha recibido una respuesta del otro servidor a tiempo