SDK de Kushki para Node.js: instalación, configuración y primeros cobros
El SDK oficial de Kushki para Node.js abstrae toda la complejidad de la API. En este post cubrimos instalación, manejo de errores y testing con mocks.
20 de febrero de 2026
·9 minEl SDK oficial de Kushki para Node.js proporciona types completos en TypeScript, manejo automático de reintentos con backoff exponencial y helpers para el parsing de errores de la API. Si estás construyendo en Node.js, es el punto de partida recomendado.
Instalación
Instala el SDK con npm o yarn. El paquete incluye tipos TypeScript — no necesitas instalar @types/kushki por separado.
Autenticación
El SDK soporta dos modos: sandbox (para pruebas) y production. Nunca pongas tu private key en el código — usa variables de entorno. El SDK lee KUSHKI_PRIVATE_KEY del entorno si no pasas la key explícitamente.
En producción usa siempre process.env para las keys. Considera usar un secrets manager como AWS Secrets Manager o GCP Secret Manager en lugar de variables de entorno planas.
Tu primer cobro
El método charges.create() acepta un token (obtenido con Kushki.js), el monto en centavos y la moneda ISO 4217. Retorna una promesa con el objeto de la transacción o lanza un KushkiError si falla.
Manejo de errores
El SDK distingue entre errores de red (NetworkError), errores de la API (ApiError con código y mensaje) y errores de validación (ValidationError). Siempre maneja los tres tipos por separado para dar feedback útil al usuario.
- NetworkError: problema de conectividad — reintentar con backoff
- ApiError code 402: fondos insuficientes — notificar al usuario
- ApiError code 422: datos inválidos — revisar el payload
- ValidationError: error del SDK mismo — revisar la integración
Testing con mocks
El SDK exporta KushkiMock para testing. No necesitas un account de sandbox para tus unit tests — el mock simula todos los casos de éxito y error de la API sin hacer requests reales.