tumipay-cards-js

SDK JavaScript/TypeScript para tokenización segura de tarjetas de crédito y débito con TumiPay.

Instalación

npm install tumipay-cards-js

Inicio Rápido

import { TumiPayCardPaymentSDK } from 'tumipay-cards-js';

// 1. Crear instancia
const sdk = new TumiPayCardPaymentSDK({
  environment: 'staging',   // "staging" | "production"
  currency: 'COP',
});

// 2. Inicializar con el merchantId de TumiPay
await sdk.initialize({ merchantId: 'tu-merchant-id' });

// 3. Validar tarjeta (no requiere inicialización)
const validation = sdk.validateCard({
  cardNumber: '4111111111111111',
  cardHolderName: 'Juan Perez',
  expirationMonth: '12',
  expirationYear: '29',
  cvv: '123',
});

if (!validation.status) {
  console.error(validation.errors);
  return;
}

// 4. Autenticar tarjeta (3DS o OTP según el banco)
const auth = await sdk.authenticateCard({
  cardNumber: '4111111111111111',
  cardHolderName: 'Juan Perez',
  expirationMonth: '12',
  expirationYear: '29',
  cvv: '123',
});

// 4a. Si el banco requiere 3DS → redirigir al usuario
if (auth.data?.authType === '3ds') {
  window.location.href = auth.data.redirectUrl!;
  // En la página de callback:
  // const cb = sdk.handle3DSCallback();
  // → usar cb.data.token como authToken
}

// 4b. Si el banco requiere OTP → solicitar código al usuario
if (auth.data?.authType === 'otp') {
  const otp = await sdk.validateOTP(auth.data.secureId!, '155');
  // → usar auth.data.token como authToken
}

// 5. Generar token de suscripción (con authToken del paso anterior)
const tokenResult = await sdk.generateSubscriptionToken(
  { cardNumber: '4111111111111111', cardHolderName: 'Juan Perez',
    expirationMonth: '12', expirationYear: '29', cvv: '123' },
  { authToken: auth.data?.token }
);
console.log(tokenResult.data?.token); // "2da0dd03c6e5..."

API Reference

new TumiPayCardPaymentSDK(config)

Crea una instancia del SDK. No realiza llamadas a la red.

interface SdkConfig {
  environment: 'staging' | 'production';
  currency: string;  // Ej: "COP", "USD"
}

sdk.initialize({ merchantId })

Llama a /api/configuration con el merchantId y carga las credenciales internas del SDK.

Debe llamarse antes de authenticateCard, generateSubscriptionToken y getBinInfo.

const result = await sdk.initialize({ merchantId: 'tu-merchant-id' });

Response:

{
  "initialized": true,
  "code": "SUCCESS",
  "status": true,
  "message": "Configuración obtenida correctamente",
  "data": {
    "payment_provider": {
      "external_merchant_id": "...",
      "public_key": "...",
      "environment": "uat"
    },
    "otp_config": {
      "id_credentials": "...",
      "public_key": "...",
      "private_key": "..."
    }
  }
}

sdk.validateCard(request)

Valida los datos de tarjeta localmente (sin llamadas a la red). No requiere inicialización.

sdk.validateCard({
  cardNumber: '4111111111111111',
  cardHolderName: 'Juan Perez',
  expirationMonth: '12',
  expirationYear: '29',
  cvv: '123',
});

Marcas soportadas: visa, mastercard, amex, discover, diners, jcb

sdk.authenticateCard(card, options?) ⭐ Nuevo

Autentica la tarjeta con el banco a través de Kushki (3DS o OTP). Requiere inicialización previa.

El banco decide el método de autenticación:

• "3ds" → redirigir al usuario a data.redirectUrl, luego llamar handle3DSCallback()
• "otp" → mostrar campo de código al usuario, luego llamar validateOTP()
• "none" → solo en staging, sin autenticación (bypass de pruebas)

const auth = await sdk.authenticateCard(card, {
  callbackUrl: 'https://tuapp.com/3ds-callback',  // Para flujo 3DS
  totalAmount: 100,                                 // Monto (default: 100)
});

Response:

{
  "code": "SUCCESS",
  "status": true,
  "message": "Autenticación OTP requerida. Solicitar código al usuario.",
  "data": {
    "authType": "otp",
    "secureId": "5e44449e-...",
    "token": "406aea95..."
  }
}

sdk.handle3DSCallback() ⭐ Nuevo

Lee el token del callback de 3DS desde los parámetros de la URL actual. Llamar en la página de callbackUrl tras la redirección de Kushki.

const result = sdk.handle3DSCallback();
// result.data.token → authToken para generateSubscriptionToken

sdk.validateOTP(secureId, otpValue) ⭐ Nuevo

Valida el código OTP ingresado por el usuario. Usar cuando authenticateCard devuelva authType = "otp".

const result = await sdk.validateOTP(secureId, '155');
// Si result.status → usar auth.data.token como authToken

| Parámetro | Tipo | Descripción | |-----------|------|-------------| | secureId | string | data.secureId de authenticateCard | | otpValue | string | Código de 3 dígitos ingresado por el usuario |

sdk.generateSubscriptionToken(card, options?) — Actualizado

Genera un token de suscripción usando Kushki. Requiere inicialización previa.

await sdk.generateSubscriptionToken(card, {
  authToken: 'token-validado-de-authenticate',  // Recomendado
  documentNumber: '1234567890',                  // Opcional
  email: '[email protected]',                   // Opcional
});

Response:

{
  "code": "SUCCESS",
  "status": true,
  "message": "Token de suscripción generado correctamente",
  "data": { "token": "2da0dd03c6e54ebd80b1a09a2d17ea9e" }
}

sdk.getBinInfo(bin)

Consulta información del BIN en Kushki. Requiere inicialización previa.

const result = await sdk.getBinInfo('411111');

sdk.isInitialized() / sdk.getConfig()

sdk.isInitialized(); // boolean
sdk.getConfig();     // { environment, currency }

Flujo Completo con Autenticación

import {
  TumiPayCardPaymentSDK,
  type AuthenticateCardResult,
} from 'tumipay-cards-js';

const sdk = new TumiPayCardPaymentSDK({ environment: 'staging', currency: 'COP' });
await sdk.initialize({ merchantId: 'tu-merchant-id' });

const card = {
  cardNumber: '4111111111111111', cardHolderName: 'Juan Perez',
  expirationMonth: '12', expirationYear: '29', cvv: '123',
};

// Paso 1 — Validar localmente
const validation = sdk.validateCard(card);
if (!validation.status) { /* mostrar errores */ return; }

// Paso 2 — Autenticar
const auth = await sdk.authenticateCard(card, { callbackUrl: 'https://tuapp.com/3ds' });
let authToken: string | undefined;

if (auth.data?.authType === 'none') {
  authToken = auth.data.token;                      // staging bypass
} else if (auth.data?.authType === 'otp') {
  const otp = await sdk.validateOTP(auth.data.secureId!, userInputOTP);
  if (otp.status) authToken = auth.data.token;
} else if (auth.data?.authType === '3ds') {
  window.location.href = auth.data.redirectUrl!;    // redirigir
  // En callbackUrl:
  // const cb = sdk.handle3DSCallback();
  // authToken = cb.data?.token;
}

// Paso 3 — Generar token de suscripción
const tokenResult = await sdk.generateSubscriptionToken(card, { authToken });
const token = tokenResult.data?.token;
// Enviar `token` al backend

Tipos exportados

import type {
  SdkConfig,
  SdkInitOptions,
  SdkInitializationResult,
  ValidateCardRequest,
  ValidateCardResult,
  GenerateTokenResult,
  GetBinInfoResult,
  AuthType,
  AuthenticateCardOptions,
  AuthenticateCardResult,
  Handle3DSCallbackResult,
  ValidateOTPResult,
  GenerateSubscriptionTokenOptions,
} from 'tumipay-cards-js';

Licencia

MIT