TumiPay Cards JS

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

Sandbox Demo

Test the SDK interactively in UAT before integrating it in your application.

Cards SDK Demo

Try initialize(), validateCard(), getBinInfo(), and authenticateCard() with your UAT credentials and test cards.

Use your UAT merchantId, Token-Top, and Basic Auth credentials. The demo supports COP, PEN, and MXN.

Installation

npm install tumipay-cards-js

Quick Start

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

const sdk = new TumiPayCardPaymentSDK({
  environment: 'uat',
  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' | 'uat' | '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';

Overview

Country Configuration

Sdk

TumiPay Cards JS

Sandbox Demo

Cards SDK Demo

Installation

Quick Start

Standard Response

Constructor

`initialize({ merchantId })`

Response

Error Codes

`validateCard(request)`

Parameters

Response — success

Response — validation error

Supported Brands

Error Codes

`generateSubscriptionToken(card)`

Parameters

Response

Error Codes

`getBinInfo(bin)`

Parameters

Response

Error Codes

Helper Methods

TypeScript Types

Utility Functions

​TumiPay Cards JS

​Sandbox Demo

Cards SDK Demo

​Installation

​Quick Start

​Standard Response

​Constructor

​initialize({ merchantId })

​Response

​Error Codes

​validateCard(request)

​Parameters

​Response — success

​Response — validation error

​Supported Brands

​Error Codes

​generateSubscriptionToken(card)

​Parameters

​Response

​Error Codes

​getBinInfo(bin)

​Parameters

​Response

​Error Codes

​Helper Methods

​TypeScript Types

​Utility Functions

TumiPay Cards JS

Sandbox Demo

Installation

Quick Start

Standard Response

Constructor

`initialize({ merchantId })`

Response

Error Codes

`validateCard(request)`

Parameters

Response — success

Response — validation error

Supported Brands

Error Codes

`generateSubscriptionToken(card)`

Parameters

Response

Error Codes

`getBinInfo(bin)`

Parameters

Response

Error Codes

Helper Methods

TypeScript Types

Utility Functions