FinTech CAN SDK

A TypeScript SDK for integrating with FinTech Client Account Number (CAN) registration APIs. Built with automatic authentication, token management, AES encryption, and TypeScript support.

Key Features:

• 🔐 Automatic authentication token management
• 🔒 AES-128/192/256-CBC encryption with PKCS7 padding
• 🚀 Automatic request header generation (version, timestamp, unique ID)
• 📦 TypeScript declarations included
• ♻️ Token caching and auto-refresh on expiration
• 🛡️ URL-safe Base64 encoding
• 🔄 Request/response interceptors for custom logic

Installation

npm install fintech-can-sdk

Quick Start

1. Set Environment Variables

The SDK reads credentials from environment variables. Set these in your backend:

# API Configuration
API_BASE_URL=https://14.141.212.169:4091
AUTH_ENDPOINT=/GetAccessTokenV1

# Authentication
ENTITY_ID=your_entity_id
CLIENT_USER=your_username
CLIENT_PWD=your_password

# Encryption Keys (for AES-128/192/256 encryption)
SECRET_KEY=your_secret_key_16_24_or_32_chars
IV_KEY=your_iv_key_16_chars
ENTITY_ID_HEADER=your_entity_id_for_headers

2. Use FinTechService (Recommended)

import { FinTechService } from 'fintech-can-sdk';

const service = new FinTechService();

const payload = {
  apiType: "CAN-REG",
  reqEvent: "CR",
  proofUploadByCan: "Y",
  onlineAccessFlag: "Y",
  holdType: "SI",
  invCategory: "I",
  taxStatus: "01",
  holderCount: 1,
  holderList: [
    {
      holderSeqNo: "1",
      holderName: "John Doe",
      // ... more fields
    }
  ],
  bnkList: [
    {
      bankSeqNo: "1",
      bankCode: "0001",
      // ... more fields
    }
  ]
};

const result = await service.createCAN(payload);
console.log(result);

What gets sent to the API (automatically generated):

{
  "reqHeader": {
    "entityId": "from ENTITY_ID_HEADER env",
    "version": "1.00",
    "reqTS": "2026-06-16 14:30:45",
    "apiType": "CAN-REG",
    "uniqueId": "1000000001"
  },
  "reqBody": {
    "data": {
      "encryptedData": "base64-encoded-aes-encrypted-payload"
    }
  }
}

Headers are automatically handled:

• entityId — From ENTITY_ID_HEADER environment variable
• version — Fixed as 1.00 (per API spec)
• reqTS — Auto-generated current timestamp (format: YYYY-MM-DD HH:MM:SS)
• apiType — Automatically set to "CAN-REG"
• uniqueId — Auto-generated unique identifier (increments per request)
• Authorization — Token from authentication endpoint (auto-managed)

Using ApiClient (Low-level)

import { ApiClient } from 'fintech-can-sdk';

const client = new ApiClient();

const result = await client.post(
  "/APIFinTechCANCreateService",
  {
    // Your request payload
    apiType: "CAN-REG",
    // ... other fields
  }
);

console.log(result);

API Methods

POST Request

const data = await client.post<ResponseType>("/endpoint", {
  field1: "value1",
  field2: "value2"
});

GET Request

const data = await client.get<ResponseType>("/endpoint");

DELETE Request

const data = await client.delete<ResponseType>("/endpoint");

How It Works

Authentication Flow

1. On first API call, SDK automatically authenticates with /GetAccessTokenV1
2. Uses ENTITY_ID, CLIENT_USER, and CLIENT_PWD from environment
3. Token is cached and reused for all subsequent requests
4. If token expires (401), SDK auto-refreshes and retries
5. All automatic — no manual token management needed!

Encryption

The SDK automatically encrypts sensitive data:

• Algorithm: AES with CBC mode and PKCS7 padding
• Key Size: Dynamic selection based on SECRET_KEY length:
  • 16 characters → AES-128
  • 24 characters → AES-192
  • 32 characters → AES-256
• IV: From IV_KEY environment variable (16 characters)
• Encoding: URL-safe Base64 (compatible with Java implementations)

Request Structure

All requests are automatically wrapped in the expected format:

{
  "reqHeader": {
    "entityId": "string",
    "version": "1.00",
    "reqTS": "YYYY-MM-DD HH:MM:SS",
    "apiType": "CAN-REG",
    "uniqueId": "number"
  },
  "reqBody": {
    "data": {
      "encryptedData": "base64-encoded-encrypted-payload"
    }
  }
}

Environment Variables

| Variable | Description | Example | Required | |----------|-------------|---------|----------| | API_BASE_URL | FinTech API endpoint | https://14.141.212.169:4091 | ✓ | | AUTH_ENDPOINT | Authentication path | /GetAccessTokenV1 | ✓ | | ENTITY_ID | Entity ID for auth | your_entity_id | ✓ | | CLIENT_USER | Username for auth | your_username | ✓ | | CLIENT_PWD | Password for auth | your_password | ✓ | | ENTITY_ID_HEADER | Entity ID for headers | your_entity_id | ✓ | | SECRET_KEY | AES encryption key | 16, 24, or 32 chars | ✓ | | IV_KEY | AES initialization vector | 16 characters | ✓ |

Usage Examples

Express.js Backend

import express from 'express';
import { FinTechService } from 'fintech-can-sdk';

const app = express();
const service = new FinTechService();

app.post('/api/register-can', async (req, res) => {
  try {
    const payload = req.body;
    const result = await service.createCAN(payload);
    res.json(result);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

app.listen(3001);

React Frontend (call backend endpoint)

const response = await fetch('http://localhost:3001/api/register-can', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(payload)
});

const result = await response.json();
console.log(result);

Note: The frontend only calls the backend API. All credentials and encryption keys stay on the backend only!

Error Handling

try {
  const result = await service.createCAN(payload);
} catch (error) {
  if (error.message.includes('Missing authentication')) {
    console.error('Missing env credentials');
  } else if (error.message.includes('Failed to authenticate')) {
    console.error('Auth failed - check credentials');
  } else {
    console.error('API error:', error.message);
  }
}

Exported Classes & Types

FinTechService

Main service class for CAN registration operations.

import { FinTechService } from 'fintech-can-sdk';
const service = new FinTechService();
const result = await service.createCAN(payload);

ApiClient

Low-level HTTP client (used internally, can be imported directly if needed).

import { ApiClient } from 'fintech-can-sdk';
const client = new ApiClient();
const result = await client.post('/endpoint', data);

EncryptionUtil

Encryption utilities (for advanced use cases).

import { EncryptionUtil } from 'fintech-can-sdk';
const encrypted = EncryptionUtil.encrypt(data, secretKey, ivKey);
const decrypted = EncryptionUtil.decrypt(encrypted, secretKey, ivKey);

HeaderBuilder

Header generation utilities (used internally).

import { HeaderBuilder } from 'fintech-can-sdk';
const headers = HeaderBuilder.buildHeaders('CAN-REG');

Best Practices

✅ Do:

• Store all credentials in environment variables
• Use HTTPS for all API calls
• Keep SECRET_KEY and IV_KEY secure
• Use appropriate AES key sizes (16, 24, or 32 characters)
• Handle token expiration gracefully (SDK does this automatically)

❌ Don't:

• Commit .env files to version control
• Pass credentials to frontend code
• Hardcode API keys or passwords
• Share encryption keys in public repositories
• Use weak or short encryption keys

TypeScript Support

Full TypeScript support with included type definitions:

import { FinTechService, CreateCANRequest, CanRegistrationResponse } from 'fintech-can-sdk';

const service = new FinTechService();
const payload: CreateCANRequest = { /* ... */ };
const result: CanRegistrationResponse = await service.createCAN(payload);

Security

• ✓ Credentials only in environment variables
• ✓ AES encryption for sensitive data
• ✓ HTTPS communication with API
• ✓ Token stored in memory only (not persistent)
• ✓ Automatic token refresh on expiration
• ✓ No hardcoded secrets in code

Support & Issues

For issues, questions, or feature requests, please refer to the official documentation or contact support.

License

MIT

License

MIT