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';

Overview

Country Configuration

Sdk

TumiPay Cards JS

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

Overview

Country Configuration

​TumiPay Cards JS

​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

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