TumiPay Card Payment SDK

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

Installation

npm install tumipay-cards-js

Quick Start

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

// Create instance
const sdk = new TumiPayCardPaymentSDK({
  baseUrl: 'https://api.tumipay.co/v1',
  apiKey: 'your-api-key',
  solutionId: 'CARD_PAYMENT_SOLUTION_V1',
  environment: 'test',
  currency: 'COP'
});

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

// Validate card
const result = await sdk.validateCard({
  cardNumber: '4532015112830366',
  cvv: '123',
  expirationMonth: '12',
  expirationYear: '2025',
  cardHolderName: 'John Doe'
});

// Create token
const token = await sdk.createToken({
  cardNumber: '4532015112830366',
  cvv: '123',
  expirationMonth: '12',
  expirationYear: '2025',
  cardHolderName: 'John Doe'
});

SDK Methods

1. `initialize(options: InitializeOptions): Promise<void>`

Initializes the SDK with the merchant ID. This method automatically retrieves all necessary configurations from the server.

Request

interface InitializeOptions {
  merchantId: string;  // Unique merchant ID
}

Field Specifications:

Field	Type	Length	Required	Description
`merchantId`	string	-	✅ Yes	Unique merchant identifier (UUID format)

Example:

await sdk.initialize({
  merchantId: 'merchant-123-abc'
});

Response

Promise<void>  // Resolves when initialization is successful

Error Codes

Code	Description	Solution
`MERCHANT_NOT_FOUND`	Merchant ID does not exist	Verify the provided ID
`INVALID_MERCHANT_ID`	Invalid merchant ID format	Must be a valid UUID
`MERCHANT_INACTIVE`	Merchant disabled or inactive	Contact support
`CONFIG_RETRIEVAL_ERROR`	Error retrieving configuration from server	Check connectivity
`MISSING_CREDENTIALS`	Missing credentials in server configuration	Contact support
`NETWORK_ERROR`	Connection error with server	Check your internet connection
`SDK_ALREADY_INITIALIZED`	SDK was already initialized	No need to initialize again

Error handling example:

try {
  await sdk.initialize({ merchantId: 'merchant-123' });
  console.log('SDK initialized successfully');
} catch (error) {
  switch (error.code) {
    case 'MERCHANT_NOT_FOUND':
      console.error('Merchant ID not found');
      break;
    case 'MERCHANT_INACTIVE':
      console.error('Merchant inactive, contact support');
      break;
    case 'NETWORK_ERROR':
      console.error('Connection error, try again');
      break;
    default:
      console.error('Unknown error:', error.message);
  }
}

2. `validateCard(card: CardData): Promise<ResultValidation>`

Validates card data without creating the token. Useful for real-time validation while the user enters data.

Request

interface CardData {
  cardNumber: string;        // Card number (13-19 digits)
  cvv: string;              // Security code (3-4 digits)
  expirationMonth: string;  // Expiration month (01-12)
  expirationYear: string;   // Expiration year (YY or YYYY)
  cardHolderName: string;   // Cardholder name (minimum 3 characters)
}

Field Specifications:

Field	Type	Length	Required	Description
`cardNumber`	string	13-19 digits	✅ Yes	Card number (must pass Luhn validation). Only numeric characters allowed.
`cvv`	string	3-4 digits	✅ Yes	Card security code. 3 digits for Visa/Mastercard, 4 digits for Amex. Only numeric characters.
`expirationMonth`	string	2 characters	✅ Yes	Card expiration month (01-12). Must be zero-padded (e.g., “01”, “12”).
`expirationYear`	string	2 or 4 characters	✅ Yes	Card expiration year. Accepts YY (e.g., “25”) or YYYY (e.g., “2025”) format.
`cardHolderName`	string	Min: 3 chars	✅ Yes	Cardholder full name as shown on the card. Must contain at least 3 characters.

Example:

const result = await sdk.validateCard({
  cardNumber: '4532015112830366',
  cvv: '123',
  expirationMonth: '12',
  expirationYear: '2025',
  cardHolderName: 'John Doe'
});

Response

interface ResultValidation {
  isValid: boolean;           // true if all data is valid
  errors?: ValidationError[]; // Array of errors (only if isValid is false)
  cardBrand?: string;        // Card brand: 'visa', 'mastercard', 'amex', etc.
}

interface ValidationError {
  field: string;      // Field with error: 'cardNumber', 'cvv', 'expirationMonth', etc.
  code: string;       // Error code
  message: string;    // Descriptive error message
}

Successful response:

{
  isValid: true,
  cardBrand: 'visa',
  errors: []
}

Response with errors:

{
  isValid: false,
  cardBrand: 'unknown',
  errors: [
    {
      field: 'cardNumber',
      code: 'INVALID_CARD_NUMBER',
      message: 'Card number is invalid'
    },
    {
      field: 'cvv',
      code: 'INVALID_CVV_LENGTH',
      message: 'CVV must be 3 or 4 digits'
    }
  ]
}

Error Codes by Field

cardNumber:

Code	Description
`CARD_NUMBER_REQUIRED`	Card number is required
`INVALID_CARD_NUMBER`	Invalid card number (Luhn algorithm fails)
`INVALID_CARD_LENGTH`	Incorrect length (must be 13-19 digits)
`CARD_NUMBER_NOT_NUMERIC`	Only numbers allowed
`UNSUPPORTED_CARD_BRAND`	Unsupported card brand

cvv:

Code	Description
`CVV_REQUIRED`	CVV is required
`INVALID_CVV_LENGTH`	CVV must be 3 digits (Visa/MC) or 4 (Amex)
`CVV_NOT_NUMERIC`	CVV can only contain numbers

expirationMonth:

Code	Description
`EXPIRATION_MONTH_REQUIRED`	Expiration month is required
`INVALID_EXPIRATION_MONTH`	Invalid month (must be 01-12)
`EXPIRATION_MONTH_NOT_NUMERIC`	Month must be numeric

expirationYear:

Code	Description
`EXPIRATION_YEAR_REQUIRED`	Expiration year is required
`INVALID_EXPIRATION_YEAR`	Invalid year or incorrect format
`CARD_EXPIRED`	Card is already expired
`EXPIRATION_YEAR_TOO_FAR`	Expiration year too far in future (max 20 years)

cardHolderName:

Code	Description
`CARDHOLDER_NAME_REQUIRED`	Cardholder name is required
`CARDHOLDER_NAME_TOO_SHORT`	Name too short (minimum 3 characters)
`CARDHOLDER_NAME_INVALID`	Invalid characters in name

General:

Code	Description
`SDK_NOT_INITIALIZED`	Must call initialize() before validating
`VALIDATION_ERROR`	General validation error

Handling example:

const result = await sdk.validateCard(cardData);

if (result.isValid) {
  console.log(`Valid ${result.cardBrand} card`);
  // Continue with createToken
} else {
  console.error('Validation errors:');
  result.errors?.forEach(error => {
    console.error(`  - ${error.field}: ${error.message}`);
  });
  // Show errors to user in form
}

3. `createToken(request: TokenRequest): Promise<Token>`

Creates a secure token for the card. This method automatically validates before tokenizing.

Request

interface TokenRequest {
  cardNumber: string;        // Card number (13-19 digits)
  cvv: string;              // Security code (3-4 digits)
  expirationMonth: string;  // Expiration month (01-12)
  expirationYear: string;   // Expiration year (YY or YYYY)
  cardHolderName: string;   // Cardholder name
}

Field Specifications:

Field	Type	Length	Required	Description
`cardNumber`	string	13-19 digits	✅ Yes	Card number (must pass Luhn validation). Only numeric characters allowed.
`cvv`	string	3-4 digits	✅ Yes	Card security code. 3 digits for Visa/Mastercard, 4 digits for Amex. Only numeric characters.
`expirationMonth`	string	2 characters	✅ Yes	Card expiration month (01-12). Must be zero-padded (e.g., “01”, “12”).
`expirationYear`	string	2 or 4 characters	✅ Yes	Card expiration year. Accepts YY (e.g., “25”) or YYYY (e.g., “2025”) format.
`cardHolderName`	string	Min: 3 chars	✅ Yes	Cardholder full name as shown on the card. Must contain at least 3 characters.

Example:

const token = await sdk.createToken({
  cardNumber: '4532015112830366',
  cvv: '123',
  expirationMonth: '12',
  expirationYear: '2025',
  cardHolderName: 'John Doe'
});

Response

interface Token {
  token: string;              // Secure card token
  brand: string;              // Brand: 'visa', 'mastercard', 'amex', etc.
  lastFourDigits: string;     // Last 4 digits of card
  bin: string;                // First 6 digits (Bank Identification Number)
  expirationMonth: string;    // Expiration month (MM format)
  expirationYear: string;     // Expiration year (YYYY format)
  cardHolderName: string;     // Cardholder name
  security?: SecurityInfo;    // Security information (optional)
}

interface SecurityInfo {
  requiresAuthentication: boolean;  // If additional authentication was required
  authenticationType?: '3DS' | 'OTP';  // Type of authentication used
  authenticationStatus: 'completed' | 'not_required' | 'failed';
}

Successful response:

{
  token: 'tok_1a2b3c4d5e6f7g8h9i0j',
  brand: 'visa',
  lastFourDigits: '0366',
  bin: '453201',
  expirationMonth: '12',
  expirationYear: '2025',
  cardHolderName: 'John Doe',
  security: {
    requiresAuthentication: false,
    authenticationStatus: 'not_required'
  }
}

Error Codes

Data Validation:

Code	Description
`VALIDATION_FAILED`	Data validation failed (includes details)
`CARD_NUMBER_REQUIRED`	Card number missing
`INVALID_CARD_NUMBER`	Invalid card number
`CVV_REQUIRED`	CVV missing
`INVALID_CVV`	Invalid CVV
`CARD_EXPIRED`	Card expired
`CARDHOLDER_NAME_REQUIRED`	Cardholder name missing

Tokenization Errors:

Code	Description
`TOKENIZATION_FAILED`	Error creating token
`KUSHKI_SERVICE_UNAVAILABLE`	Tokenization service unavailable
`CARD_DECLINED`	Card declined by issuer
`CARD_BLOCKED`	Card blocked
`INSUFFICIENT_FUNDS`	Insufficient funds (online validation only)
`DUPLICATE_TRANSACTION`	Duplicate transaction
`FRAUD_DETECTION`	Transaction blocked by fraud detection

3DS/OTP Authentication Errors:

Code	Description
`AUTHENTICATION_REQUIRED`	Card requires 3DS or OTP authentication
`AUTHENTICATION_FAILED`	3DS/OTP authentication failed
`AUTHENTICATION_TIMEOUT`	Authentication timeout
`AUTHENTICATION_REJECTED`	User rejected authentication
`AUTHENTICATION_CANCELLED`	User cancelled authentication
`3DS_NOT_ENROLLED`	Card not enrolled in 3D Secure
`3DS_CHALLENGE_FAILED`	3D Secure challenge failed
`OTP_INVALID`	Invalid OTP code
`OTP_EXPIRED`	OTP code expired
`OTP_MAX_ATTEMPTS`	Maximum OTP attempts reached

Configuration Errors:

Code	Description
`SDK_NOT_INITIALIZED`	SDK not initialized
`MISSING_CONFIGURATION`	Required configuration missing
`INVALID_MERCHANT_CONFIG`	Invalid merchant configuration

Network Errors:

Code	Description
`NETWORK_ERROR`	Connection error
`TIMEOUT_ERROR`	Timeout error
`SERVICE_UNAVAILABLE`	Service temporarily unavailable

Error handling example:

try {
  const token = await sdk.createToken(cardData);
  
  console.log('Token created:', token.token);
  console.log(`   ${token.brand} **** ${token.lastFourDigits}`);
  
} catch (error) {
  switch (error.code) {
    // Validation errors
    case 'VALIDATION_FAILED':
      console.error('Invalid data:', error.details);
      break;
    case 'CARD_EXPIRED':
      console.error('Card expired');
      break;
    
    // Tokenization errors
    case 'CARD_DECLINED':
      console.error('Card declined by bank');
      break;
    case 'KUSHKI_SERVICE_UNAVAILABLE':
      console.error('Service unavailable, try later');
      break;
    case 'FRAUD_DETECTION':
      console.error('Transaction blocked for security');
      break;
    
    // 3DS/OTP authentication errors
    case 'AUTHENTICATION_FAILED':
      console.error('Could not authenticate card');
      break;
    case 'AUTHENTICATION_TIMEOUT':
      console.error('Authentication timeout');
      break;
    case '3DS_CHALLENGE_FAILED':
      console.error('3D Secure verification failed');
      break;
    case 'OTP_INVALID':
      console.error('Invalid OTP code');
      break;
    
    // Configuration errors
    case 'SDK_NOT_INITIALIZED':
      console.error('Must initialize SDK first');
      break;
    
    // Network errors
    case 'NETWORK_ERROR':
      console.error('Connection error, check your internet');
      break;
    case 'TIMEOUT_ERROR':
      console.error('Timeout, try again');
      break;
    
    default:
      console.error('Error:', error.message);
  }
}

4. `validateOTP(request: ValidateOTPRequest): Promise<ValidateOTPResponse>`

Validates the OTP (One-Time Password) code sent to the customer as part of the authentication process. This method is used when the transaction requires additional verification via temporary code.

Request

interface ValidateOTPRequest {
  otpValue: string;  // 3-6 digit OTP code sent to user
}

Field Specifications:

Field	Type	Length	Required	Description
`otpValue`	string	3-6 digits	✅ Yes	One-Time Password code sent to the customer. Only numeric characters allowed.

Example:

const result = await sdk.validateOTP({
  otpValue: '123456'
});

Response

interface ValidateOTPResponse {
  code: string;      // Server response code
  message: string;   // Descriptive validation message
  result: boolean;   // true if OTP is valid, false otherwise
}

Successful response:

{
  code: 'OTP000',
  message: 'OTP validated successfully',
  result: true
}

Error Codes

OTP Validation:

Code	Description
`OTP_REQUIRED`	OTP code is required
`INVALID_OTP`	Incorrect or invalid OTP code
`OTP_EXPIRED`	OTP code has expired
`OTP_MAX_ATTEMPTS`	Maximum number of attempts reached
`OTP_NOT_FOUND`	No active OTP session found
`OTP_ALREADY_USED`	This OTP code was already used

Format Validation Errors:

Code	Description
`VALIDATION_FAILED`	Data validation failed (includes details)
`OTP_INVALID_FORMAT`	Invalid OTP format (must be numeric)
`OTP_INVALID_LENGTH`	Incorrect OTP code length

Configuration Errors:

Code	Description
`SDK_NOT_INITIALIZED`	SDK not initialized
`MISSING_CONFIGURATION`	Required configuration missing
`INVALID_MERCHANT_CONFIG`	Invalid merchant configuration

Network Errors:

Code	Description
`NETWORK_ERROR`	Connection error
`TIMEOUT_ERROR`	Timeout error
`SERVICE_UNAVAILABLE`	Service temporarily unavailable

Error handling example:

try {
  const result = await sdk.validateOTP({
    otpValue: '123456'
  });
  
  console.log('OTP validated successfully:', result.message);
  // Continue with payment process
  
} catch (error) {
  switch (error.code) {
    // OTP validation errors
    case 'INVALID_OTP':
      console.error('Incorrect OTP code, try again');
      break;
    case 'OTP_EXPIRED':
      console.error('OTP code has expired, request a new one');
      break;
    case 'OTP_MAX_ATTEMPTS':
      console.error('Too many failed attempts, request a new code');
      break;
    case 'OTP_ALREADY_USED':
      console.error('This code was already used');
      break;
    case 'OTP_NOT_FOUND':
      console.error('No active OTP session');
      break;
    
    // Format errors
    case 'VALIDATION_FAILED':
      console.error('Invalid data:', error.details);
      break;
    case 'OTP_INVALID_FORMAT':
      console.error('OTP code must be numeric');
      break;
    case 'OTP_INVALID_LENGTH':
      console.error('OTP code must be between 3 and 6 digits');
      break;
    
    // Configuration errors
    case 'SDK_NOT_INITIALIZED':
      console.error('Must initialize SDK first');
      break;
    
    // Network errors
    case 'NETWORK_ERROR':
      console.error('Connection error, check your internet');
      break;
    case 'TIMEOUT_ERROR':
      console.error('Timeout, try again');
      break;
    
    default:
      console.error('Error:', error.message);
  }
}

Authentication Handling

The SDK automatically and internally handles all 3DS (3D Secure) and OTP authentication processes when the card requires it. For the client:

The createToken() method performs the entire authentication flow transparently
If authentication is successful, you’ll receive the token normally
If it fails, you’ll receive a specific error (see error codes above)

You don’t need to implement anything additional for 3DS or OTP. The SDK handles:

Detecting if the card requires authentication
Executing the 3DS or OTP flow as appropriate
Validating authentication with the bank
Returning the final token or a descriptive error

Example:

try {
  // SDK handles 3DS/OTP internally
  const token = await sdk.createToken(cardData);
  
  console.log('Token created successfully:', token.token);
  // Proceed with payment
  
} catch (error) {
  // Handle authentication errors if they occur
  if (error.code === 'AUTHENTICATION_FAILED') {
    console.error('Authentication failed');
  } else if (error.code === '3DS_CHALLENGE_FAILED') {
    console.error('User did not complete 3DS verification');
  }
  // See full list of error codes above
}

Test Cards

For test environment, use these cards:

Brand	Number	CVV	Result
Visa	`4532015112830366`	`123`	Approved
Visa	`4111111111111111`	`123`	Approved
Visa	`4000000000000002`	`123`	Declined
Mastercard	`5425233430109903`	`123`	Approved
Mastercard	`5555555555554444`	`123`	Approved
Amex	`374245455400126`	`1234`	Approved

Valid dates: Any future month/year (e.g., 12/2025)

Complete Example

TypeScript

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

const sdk = new TumiPayCardPaymentSDK({
  baseUrl: 'https://api.tumipay.co/v1',
  apiKey: process.env.TUMIPAY_API_KEY!,
  solutionId: 'CARD_PAYMENT_SOLUTION_V1',
  environment: 'test',
  currency: 'COP'
});

async function processPayment() {
  try {
    // 1. Initialize SDK
    await sdk.initialize({
      merchantId: process.env.MERCHANT_ID!
    });
    console.log('SDK initialized');

    const cardData = {
      cardNumber: '4532015112830366',
      cvv: '123',
      expirationMonth: '12',
      expirationYear: '2025',
      cardHolderName: 'John Doe'
    };

    // 2. Validate card (optional but recommended)
    const validation = await sdk.validateCard(cardData);
    
    if (!validation.isValid) {
      console.error('Validation failed:');
      validation.errors?.forEach(err => {
        console.error(`   ${err.field}: ${err.message}`);
      });
      return;
    }

    console.log(`Valid ${validation.cardBrand} card`);

    // 3. Create token
    const token = await sdk.createToken(cardData);
    
    console.log('Token created:', token.token);
    console.log(`   ${token.brand} **** ${token.lastFourDigits}`);
    console.log(`   Expires: ${token.expirationMonth}/${token.expirationYear}`);

    // Now use the token to process payment...
    
  } catch (error) {
    console.error('Error:', error.code, error.message);
  }
}

processPayment();

React with TypeScript

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

const sdk = new TumiPayCardPaymentSDK({
  baseUrl: 'https://api.tumipay.co/v1',
  apiKey: process.env.REACT_APP_TUMIPAY_API_KEY!,
  solutionId: 'CARD_PAYMENT_SOLUTION_V1',
  environment: 'test',
  currency: 'COP'
});

// Initialize once
await sdk.initialize({
  merchantId: process.env.REACT_APP_MERCHANT_ID!
});

function PaymentForm() {
  const [cardNumber, setCardNumber] = useState('');
  const [cvv, setCvv] = useState('');
  const [expirationMonth, setExpirationMonth] = useState('');
  const [expirationYear, setExpirationYear] = useState('');
  const [cardHolderName, setCardHolderName] = useState('');
  const [errors, setErrors] = useState<Record<string, string>>({});
  const [loading, setLoading] = useState(false);

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    setLoading(true);
    setErrors({});

    const cardData = {
      cardNumber,
      cvv,
      expirationMonth,
      expirationYear,
      cardHolderName
    };

    try {
      // Validate first
      const validation = await sdk.validateCard(cardData);
      
      if (!validation.isValid) {
        const newErrors: Record<string, string> = {};
        validation.errors?.forEach(err => {
          newErrors[err.field] = err.message;
        });
        setErrors(newErrors);
        setLoading(false);
        return;
      }

      // Create token
      const token = await sdk.createToken(cardData);
      
      console.log('Token:', token.token);
      alert('Payment successful!');
      
    } catch (error: any) {
      setErrors({ general: error.message });
    } finally {
      setLoading(false);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <div>
        <input
          type="text"
          placeholder="Card number"
          value={cardNumber}
          onChange={(e) => setCardNumber(e.target.value)}
        />
        {errors.cardNumber && <span className="error">{errors.cardNumber}</span>}
      </div>

      <div>
        <input
          type="text"
          placeholder="Cardholder name"
          value={cardHolderName}
          onChange={(e) => setCardHolderName(e.target.value)}
        />
        {errors.cardHolderName && <span className="error">{errors.cardHolderName}</span>}
      </div>

      <div>
        <input
          type="text"
          placeholder="MM"
          maxLength={2}
          value={expirationMonth}
          onChange={(e) => setExpirationMonth(e.target.value)}
        />
        <input
          type="text"
          placeholder="YYYY"
          maxLength={4}
          value={expirationYear}
          onChange={(e) => setExpirationYear(e.target.value)}
        />
        {errors.expirationMonth && <span className="error">{errors.expirationMonth}</span>}
        {errors.expirationYear && <span className="error">{errors.expirationYear}</span>}
      </div>

      <div>
        <input
          type="text"
          placeholder="CVV"
          maxLength={4}
          value={cvv}
          onChange={(e) => setCvv(e.target.value)}
        />
        {errors.cvv && <span className="error">{errors.cvv}</span>}
      </div>

      {errors.general && <div className="error">{errors.general}</div>}

      <button type="submit" disabled={loading}>
        {loading ? 'Processing...' : 'Pay'}
      </button>
    </form>
  );
}

export default PaymentForm;

Overview

Country Configuration

Sdk

TumiPay Card Payment SDK

Installation

Quick Start

SDK Methods

1. `initialize(options: InitializeOptions): Promise<void>`

Request

Response

Error Codes

2. `validateCard(card: CardData): Promise<ResultValidation>`

Request

Response

Error Codes by Field

3. `createToken(request: TokenRequest): Promise<Token>`

Request

Response

Error Codes

4. `validateOTP(request: ValidateOTPRequest): Promise<ValidateOTPResponse>`

Request

Response

Error Codes

Authentication Handling

Test Cards

Complete Example

TypeScript

React with TypeScript

Overview

Country Configuration

​TumiPay Card Payment SDK

​Installation

​Quick Start

​SDK Methods

​1. initialize(options: InitializeOptions): Promise<void>

​Request

​Response

​Error Codes

​2. validateCard(card: CardData): Promise<ResultValidation>

​Request

​Response

​Error Codes by Field

​3. createToken(request: TokenRequest): Promise<Token>

​Request

​Response

​Error Codes

​4. validateOTP(request: ValidateOTPRequest): Promise<ValidateOTPResponse>

​Request

​Response

​Error Codes

​Authentication Handling

​Test Cards

​Complete Example

​TypeScript

​React with TypeScript

TumiPay Card Payment SDK

Installation

Quick Start

SDK Methods

1. `initialize(options: InitializeOptions): Promise<void>`

Request

Response

Error Codes

2. `validateCard(card: CardData): Promise<ResultValidation>`

Request

Response

Error Codes by Field

3. `createToken(request: TokenRequest): Promise<Token>`

Request

Response

Error Codes

4. `validateOTP(request: ValidateOTPRequest): Promise<ValidateOTPResponse>`

Request

Response

Error Codes

Authentication Handling

Test Cards

Complete Example

TypeScript

React with TypeScript