Autenticación y Cifrado de Requests

🚧 Early Release — Beta

Este producto está en acceso temprano. Los parámetros, estructuras de respuesta y comportamientos pueden cambiar sin previo aviso. No uses esta versión en producción sin coordinarlo previamente con el equipo de integraciones de Kushki.

Todas las comunicaciones hacia Kushki ONE Connect se autentican con una firma que calculas a partir de tu Business-Code, y el payload viaja cifrado. Hay un solo mecanismo, y es el mismo en todas partes.

El mecanismo no cambia entre topologías

Tu lógica de firma y cifrado es idéntica en Cloud, en red local y en localhost. Escríbela una sola vez. La única diferencia es el header encrypted_http_communication, que solo envías en red local y localhost.

Envía siempre el header encrypted_http_communication en true

En las integraciones por Red Local y Localhost, envía el header encrypted_http_communication: true en cada request, en UAT y en producción.

Si certificas con el header en false o sin enviarlo, tus requests no se firman ni se cifran, y al pasar a producción cada llamada falla con AUTH-001 («Invalid or expired credentials»).

La integración por Nube (Cloud) no requiere este header.

Requisitos

Antes de empezar

Tu Business-Code: la llave privada que autentica a tu comercio. La entrega el equipo de integraciones durante el onboarding.

El terminalSerial del dispositivo. También lo entrega el equipo de integraciones durante el onboarding.

Business-Code no es private_credential_id

La llave de firma es tu Business-Code. El private_credential_id es un campo de configuración de la terminal y nunca se usa para firmar requests. Confundirlos produce un error de autenticación en cada llamada.

Qué lleva cada request

Cada request va firmado y cifrado. El payload original nunca viaja en texto plano.

Variables que necesitas

Variable	Descripción
`businessCode`	Llave privada que autentica a tu comercio
`terminalSerial`	Número de serie de la terminal SmartPOS
`timestamp`	Unix timestamp en segundos, en UTC
`requestData`	Payload original del request

Flujo general

Cada request pasa por dos procesos independientes que parten del mismo requestData. Uno produce la firma y el otro produce el payload cifrado. Ambos se envían juntos.

dataWithKey nunca se envía

dataWithKey solo existe para generar la firma. No se cifra ni se transmite. Incluir el campo key dentro del payload cifrado provoca un error de autenticación.

Cadena de derivación de claves

Las tres variables de entrada producen exactamente dos salidas: aesKey para el cifrado y encodedKeyTimestamp para la firma.

El password es el valor central de la cadena. Cambia cada minuto porque depende de formattedDate, lo que hace que cualquier request firmado caduque automáticamente.

Paso 1: genera el timestamp

Guarda este valor en una variable al inicio del flujo. Lo reutilizas en los pasos 3, 4 y 6.

Un solo timestamp por request

Nunca llames Date.now() más de una vez en el mismo flujo. Un timestamp distinto entre la firma, el cifrado y el header es la causa más silenciosa de los errores de autenticación.

Paso 2: genera formattedDate en UTC

Calcula siempre en UTC

Un desfase de zona horaria es una de las causas más frecuentes de firma inválida. Usa los métodos getUTC*, nunca sus equivalentes de hora local.

Paso 3: genera el password temporal

Paso 4: construye dataWithKey

Es una copia de requestData con el campo key añadido. Solo se usa para firmar.

Paso 5: genera la firma

Headers resultantes:

Authorization: Basic <hash>
timestamp: <timestamp>

Paso 6: cifra el payload

Se cifra únicamente requestData, sin el campo key.

Paso 7: arma el request final

Los headers son iguales en todos los métodos. Lo que cambia es cómo entregas el campo data. En Red Local y Localhost, agrega además el header encrypted_http_communication: true en cada request.

Anatomía de un request HTTP firmado y cifrado

En POST, PATCH y PUT, el dato cifrado va en el cuerpo:

{
  "data": "<iv_hex>:<ciphertext_hex>"
}

En GET, va como parámetro de consulta:

GET /endpoint?data=<iv_hex>:<ciphertext_hex>

Elimina los demás parámetros de consulta del request original antes de enviarlo.

Las operaciones sin payload firman un objeto vacío

En /abort no hay payload, así que lo que firmas es el literal {} — no una cadena vacía. Dos bytes de diferencia, y la respuesta no te da ninguna pista.

Errores de autenticación

Una firma inválida siempre devuelve la misma respuesta, sin distinguir la causa:

{
  "type": "AUTH",
  "code": "AUTH-001",
  "message": "Invalid or expired credentials"
}

Revisa estas causas en orden. Cubren la gran mayoría de los casos:

Causa	Cómo la detectas	Solución
Unidad de `timestamp` equivocada	El valor tiene 13 dígitos en vez de 10	Segundos, no milisegundos
Reloj fuera de la ventana de tolerancia	La firma falla de forma intermitente	Sincroniza con NTP; la tolerancia es de ±5 min
`formattedDate` en hora local	La firma falla de forma intermitente según la hora del día	Calcula la fecha con métodos UTC
Cadena vacía firmada en vez de `{}`	Falla solo en `/abort`	Firma el literal `{}`, no una cadena vacía
Body re-serializado después de firmar	Falla siempre, desde el primer request	Firma exactamente el mismo string que envías
Campo `key` incluido en el payload cifrado	Falla siempre, desde el primer request	Cifra `requestData` sin `key`; `dataWithKey` solo se usa para firmar
Header `encrypted_http_communication` ausente o en `false` (Red Local y Localhost)	Pasa la certificación en UAT y falla al pasar a producción	Envía `encrypted_http_communication: true` en cada request, también en UAT, y vuelve a certificar

Árbol de diagnóstico de errores de autenticación

No registres la firma completa

Nunca escribas el valor completo del header Authorization en tus registros de producción. Registra solo su presencia o ausencia para diagnóstico.

Script de referencia para Postman

Configura este pre-request script a nivel de colección para que el flujo de firma y cifrado se ejecute automáticamente en cada request. Define las variables businessCode y terminalSerial en el entorno.

Acepta cobros con Kushki ONE

Con la autenticación resuelta, revisa los flujos de cobro presencial y sus variantes síncrona y asíncrona.

Errores de autenticación

Consulta el catálogo completo de códigos de error, incluidos los de credenciales y permisos.

Autenticación y Cifrado de Requests

Requisitos#

Qué lleva cada request#

Variables que necesitas#

Flujo general#

Cadena de derivación de claves#

Paso 1: genera el timestamp#

Paso 2: genera formattedDate en UTC#

Paso 3: genera el password temporal#

Paso 4: construye dataWithKey#

Paso 5: genera la firma#

Paso 6: cifra el payload#

Paso 7: arma el request final#

Errores de autenticación#

Script de referencia para Postman#

Requisitos

Qué lleva cada request

Variables que necesitas

Flujo general

Cadena de derivación de claves

Paso 1: genera el timestamp

Paso 2: genera formattedDate en UTC

Paso 3: genera el password temporal

Paso 4: construye dataWithKey

Paso 5: genera la firma

Paso 6: cifra el payload

Paso 7: arma el request final

Errores de autenticación

Script de referencia para Postman