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 las credenciales de TumiPay
await sdk.initialize({
  merchantId: 'tu-merchant-id',
  tokenTop: 'tu-token-top',
  basicAuthUser: 'tu-usuario',
  basicAuthPass: 'tu-contraseña'
});

// 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 — el resultado incluye el token de suscripción
const auth = await sdk.authenticateCard({
  cardNumber: '4111111111111111',
  cardHolderName: 'Juan Perez',
  expirationMonth: '12',
  expirationYear: '29',
  cvv: '123',
}, {
  callbackUrl: 'https://tuapp.com/3ds-callback', // Requerido en producción
});

// 4a. Producción — siempre authType === '3ds' y llega redirectUrl
if (auth.data?.authType === '3ds' && auth.data.redirectUrl) {
  const token = auth.data.token; // usar para crear la suscripción
  window.location.href = auth.data.redirectUrl;

// 4b. Staging con 3DS modal — token disponible directo en la respuesta
} else if (auth.data?.authType === '3ds' && !auth.data.redirectUrl) {
  const token = auth.data.token;
  console.log(token);

// 4c. Staging sin autenticación adicional — solo puede ocurrir en staging
} else if (auth.data?.authType === 'none') {
  const token = auth.data.token;
  console.log(token);
}

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, tokenTop, basicAuthUser, basicAuthPass })

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

Debe llamarse antes de authenticateCard y getBinInfo.

const result = await sdk.initialize({
  merchantId: 'tu-merchant-id',
  tokenTop: 'tu-token-top',
  basicAuthUser: 'tu-usuario',
  basicAuthPass: 'tu-contraseña'
});

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?)

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

El comportamiento final depende del ambiente:

• Producción → siempre retorna authType: "3ds", incluso si el banco indica que no se requiere autenticación. La respuesta incluye data.token y data.redirectUrl. callbackUrl requerida (HTTPS).
• Staging con 3DS → challenge modal inline → data.token disponible directo.
• Staging sin 3DS → retorna authType: "none" → data.token disponible directo.

const auth = await sdk.authenticateCard(card, {
  callbackUrl: 'https://tuapp.com/3ds-callback',  // Requerido en producción (HTTPS)
  documentNumber: '1234567890',                    // Opcional
  email: '[email protected]',                     // Opcional
});

Response (authType "none" — solo staging):

{
  "code": "SUCCESS",
  "status": true,
  "message": "Autenticación no requerida por el banco",
  "data": {
    "authType": "none",
    "token": "406aea95..."
  }
}

Response (authType "3ds" — staging):

{
  "code": "SUCCESS",
  "status": true,
  "message": "Autenticación 3DS completada correctamente",
  "data": {
    "authType": "3ds",
    "token": "406aea95..."
  }
}

Response (authType "3ds" producción):

{
  "code": "SUCCESS",
  "status": true,
  "message": "Autenticación 3DS requerida",
  "data": {
    "authType": "3ds",
    "token": "406aea95...",
    "redirectUrl": "https://kushki-3ds.com/..."
  }
}

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',
  tokenTop: 'tu-token-top',
  basicAuthUser: 'tu-usuario',
  basicAuthPass: 'tu-contraseña'
});

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 (obtiene el token de suscripción directamente)
const auth = await sdk.authenticateCard(card, {
  callbackUrl: 'https://tuapp.com/3ds',  // Requerido en producción para 3DS redirect
});

let token: string | undefined;

if (auth.data?.authType === '3ds' && auth.data.redirectUrl) {
  // Producción — este es el único flujo posible en producción
  token = auth.data.token;
  window.location.href = auth.data.redirectUrl;

} else if (auth.data?.authType === '3ds' && !auth.data.redirectUrl) {
  // Staging — 3DS modal completado inline, token disponible
  token = auth.data.token;

} else if (auth.data?.authType === 'none') {
  // Solo en staging — este flujo nunca ocurre en producción
  token = auth.data.token;
}

// Enviar `token` al backend
if (token) {
  await fetch('/api/suscripcion', {
    method: 'POST',
    body: JSON.stringify({ token, merchantId: 'tu-merchant-id' }),
  });
}

Tipos exportados

import type {
  SdkConfig,
  SdkInitOptions,
  SdkInitializationResult,
  ValidateCardRequest,
  ValidateCardResult,
  ValidateCardError,
  ValidateCardSuccessData,
  GetBinInfoResult,
  AuthType,
  AuthenticateCardOptions,
  AuthenticateCardResult,
  AuthenticateCardResultData,
  CardBrand,
  BinInfoResult,
  SdkEnvironment,
} from 'tumipay-cards-js';

Licencia

MIT