Sdk

TumiPay Cards JS

JavaScript/TypeScript SDK for secure credit and debit card tokenization.

Installation

npm install tumipay-cards-js

Quick Start

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

const sdk = new TumiPayCardPaymentSDK({
  environment: 'staging',
  currency: 'COP',
});

await sdk.initialize({ merchantId: 'your-merchant-id' });

const validation = sdk.validateCard({
  cardNumber: '4111111111111111',
  cardHolderName: 'John Doe',
  expirationMonth: '12',
  expirationYear: '29',
  cvv: '123',
});

if (validation.status) {
  const tokenResult = await sdk.generateSubscriptionToken({
    cardNumber: '4111111111111111',
    cardHolderName: 'John Doe',
    expirationMonth: '12',
    expirationYear: '29',
    cvv: '123',
  });
  // tokenResult.data.token → subscription token
}

---

Standard Response

All methods return the same envelope:

{
  code: string;      // "SUCCESS" or error code
  status: boolean;   // true = success
  message: string;   // Human-readable description
  data?: T;          // Payload (when status is true)
  errors?: Array<{   // Only in validateCard when status is false
    code: string;
    field: string;
    message: string;
  }>;
}

---

Constructor

new TumiPayCardPaymentSDK({
  environment: 'staging' | 'production',
  currency: string,   // e.g. "COP", "USD"
})

Does not make network calls. Only configures the instance.

---

initialize({ merchantId })

Fetches merchant configuration from the TumiPay server and prepares the SDK for operation.

Must be called before generateSubscriptionToken and getBinInfo.

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

Response

{
  "initialized": true,
  "code": "SUCCESS",
  "status": true,
  "message": "Configuración obtenida correctamente",
  "data": {
    "payment_provider": {
      "external_merchant_id": "1c038e84ed014abb94eb229447f3684d",
      "public_key": "e7c352d9a067475f90bfd92301265efe",
      "environment": "uat"
    },
    "otp_config": {
      "id_credentials": "9c642a3e5034468693fbf2830146c08c",
      "public_key": "55ced6048f19446aa0f0ae26dcf10abf",
      "private_key": "6aaa48606fde4a10aef6833627c9677f"
    }
  }
}

Error Codes

Code	Description	How to Fix
INVALID_MERCHANT_ID	merchantId is empty or not provided	Ensure a valid merchantId is passed
APP_CONFIGURATION_ERROR	Failed to retrieve configuration from server	Check connectivity and that the merchantId exists in TumiPay
SDK_INIT_ERROR	Generic initialization error	Check the error message for more details

---

validateCard(request)

Validates card data locally — no network calls. Does not require initialization.

Parameters

Field	Type	Required	Description
cardNumber	string	✅	Card number (13–19 digits)
cardHolderName	string	✅	Cardholder name (min. 2 characters)
expirationMonth	string	✅	Expiry month: "01"–"12"
expirationYear	string	✅	Expiry year: "YY" or "YYYY"
cvv	string	✅	CVV: 3 digits (4 for Amex)

Response — success

{
  "code": "SUCCESS",
  "status": true,
  "message": "Tarjeta válida",
  "data": {
    "bin": "411111",
    "brand": "visa",
    "lastFourDigits": "1111",
    "maskedCard": "****1111"
  }
}

Response — validation error

{
  "code": "CARD_EXPIRED",
  "status": false,
  "message": "La validación de la tarjeta falló",
  "errors": [
    { "code": "CARD_EXPIRED", "field": "expiration", "message": "La tarjeta ha expirado" }
  ]
}

Supported Brands

Brand	Pattern
visa	Starts with 4, 13–16 digits
mastercard	Starts with 51–55, 16 digits
amex	Starts with 34 or 37, 15 digits
discover	Starts with 6011 or 65, 16 digits
diners	Starts with 300–305, 36 or 38, 14 digits
jcb	Starts with 2131, 1800 or 35, 15–16 digits

Error Codes

Code	Field	Description	How to Fix
CARD_NUMBER_EMPTY	cardNumber	Card number is empty	Provide the card number
CARD_NUMBER_INVALID_FORMAT	cardNumber	Non-numeric characters found	Use digits only, no spaces or dashes
CARD_NUMBER_INVALID_LENGTH	cardNumber	Length outside 13–19 range	Verify the full card number is entered
CARD_NUMBER_LUHN_FAILED	cardNumber	Fails Luhn algorithm	The card number is invalid; double-check it
CARDHOLDER_NAME_EMPTY	cardHolderName	Cardholder name is empty	Provide the name as shown on the card
CARDHOLDER_NAME_TOO_SHORT	cardHolderName	Name shorter than 2 characters	Enter the cardholder’s full name
EXPIRY_MONTH_INVALID	expirationMonth	Month outside 01–12	Use format "01" to "12"
EXPIRY_YEAR_INVALID	expirationYear	Year not provided	Provide the expiration year
CARD_EXPIRED	expiration	Card is expired	Use a card with a valid expiration date
CVV_EMPTY	cvv	CVV is empty	Provide the security code
CVV_INVALID_LENGTH	cvv	CVV has wrong length	Use 3 digits (4 for American Express)
BRAND_NOT_ALLOWED	cardNumber	Unsupported card brand	Use Visa, Mastercard, Amex, Discover, Diners or JCB

---

generateSubscriptionToken(card)

Generates a subscription token via Kushki. Requires prior initialization.

Kushki credentials are sourced automatically from the context loaded in initialize().

Parameters

Field	Type	Required	Description
cardNumber	string	✅	Card number
cardHolderName	string	✅	Cardholder name
expirationMonth	string	✅	Expiry month
expirationYear	string	✅	Expiry year
cvv	string	✅	CVV
documentNumber	string	➖	Document number (optional, required in some markets)
email	string	➖	Email address (optional)

Response

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

Error Codes

Code	Description	How to Fix
SDK_NOT_INITIALIZED	initialize() was not called first	Call sdk.initialize({ merchantId }) before this method
MISSING_PUBLIC_KEY	public_key missing in configuration response	Verify the merchant has a payment provider configured
MISSING_CURRENCY	currency not set in constructor	Pass currency when creating the SDK instance

---

getBinInfo(bin)

Fetches bank, brand, and card type from Kushki. Requires prior initialization.

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

Parameters

Field	Type	Required	Description
bin	string	✅	First 6 digits of the card number (or full number)

Response

{
  "code": "SUCCESS",
  "status": true,
  "message": "Información de BIN obtenida correctamente",
  "data": {
    "brand": "visa",
    "bank": "JPMORGAN CHASE BANK, N.A.",
    "cardType": "credit"
  }
}

Error Codes

Code	Description	How to Fix
SDK_NOT_INITIALIZED	initialize() was not called first	Call sdk.initialize({ merchantId }) before this method
INVALID_BIN	BIN has fewer than 6 digits	Provide at least the first 6 digits of the card number

---

Helper Methods

sdk.isInitialized()  // boolean — true if initialize() succeeded
sdk.getConfig()      // { environment, currency }

---

TypeScript Types

import type {
  SdkConfig,
  SdkInitOptions,
  SdkInitializationResult,
  ValidateCardRequest,
  ValidateCardResult,
  ValidateCardError,
  ValidateCardSuccessData,
  GenerateTokenResult,
  GetBinInfoResult,
} from 'tumipay-cards-js';

---

Utility Functions

import {
  validateCardNumber,
  validateCard,
  detectCardBrand,
  getCardBrand,
  luhnCheck,
  formatCardNumber,
  formatExpiry,
  maskCardNumber,
  ALLOWED_CARD_BRANDS,
} from 'tumipay-cards-js';