FinTech Backend SDK

A TypeScript SDK for integrating with the FinTech API. Handles authentication, token management, and API requests.

Setup

1. Install dependencies:

   npm install

2. Create .env file from template:

   cp .env.example .env

3. Configure your credentials in .env:

   API_BASE_URL=https://14.141.212.169:4091
   AUTH_ENDPOINT=/GetAccessTokenV1
      
   ENTITY_ID=your_entity_id
   CLIENT_USER=your_username
   CLIENT_PWD=your_password
      
   IV_KEY=your_iv_key
   SECRET_KEY=your_secret_key

Quick Start

Using FinTechService (Recommended)

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

const service = new FinTechService();

// Just pass the request data - headers are auto-generated!
const canRequest: CreateCANRequest = {
  apiType: "CAN-REG",
  reqEvent: "CR",
  proofUploadByCan: "Y",
  onlineAccessFlag: "Y",
  holdType: "SI",
  invCategory: "I",
  taxStatus: "01",
  holderCount: 1,
  holderList: [
    // ... holder details
  ],
  bnkList: [
    // ... bank details
  ],
  nomSec: {
    nomOptFlag: "N"
  }
};

const result = await service.createCAN(canRequest);

console.log(result);

What gets sent to the API (automatically wrapped):

{
  "reqHeader": {
    "entityId": "from .env",
    "version": "2.9",
    "reqTS": "2024-06-06 10:20:09",
    "apiType": "CAN-REG",
    "uniqueId": "1000000001"
  },
  "reqBody": {
    "data": {
      "apiType": "CAN-REG",
      "reqEvent": "CR",
      "proofUploadByCan": "Y",
      ...
    }
  }
}

Headers are automatically generated:

• entityId — From .env (ENTITY_ID_HEADER)
• version — Fixed as 2.9
• reqTS — Auto-generated current timestamp (format: YYYY-MM-DD HH:MM:SS)
• apiType — Set by SDK (CAN-REG)
• uniqueId — Auto-generated unique identifier (increments for each request)

Using ApiClient (Low-level)

import { ApiClient } from 'fintech-sdk';

const client = new ApiClient();

const result = await client.post(
  "/APIFinTechCANCreateService",
  {
    field1: "value1",
    field2: "value2"
  },
  {
    entityId: "entity_123",
    version: "1.0",
    reqTS: "2026-06-12",
    apiType: "CREATE",
    uniqueId: "unique_id_123"
  }
);

console.log(result);

Authentication Flow

1. ApiClient automatically calls /GetAccessTokenV1 on first API request
2. Uses ENTITY_ID, CLIENT_USER, and CLIENT_PWD from .env
3. Receives access token and stores it
4. Token is automatically included in all subsequent requests via Authorization header
5. Custom headers (entityId, version, reqTS, apiType, uniqueId) are passed per API call
6. Subsequent requests reuse the token (no need to re-authenticate)

API Methods

GET Request

const data = await client.get<ResponseType>("/endpoint", {
  entityId: "entity_123",
  version: "1.0",
  reqTS: "2026-06-12",
  apiType: "READ",
  uniqueId: "unique_id_123"
});

POST Request

const data = await client.post<ResponseType>("/endpoint", {
  field1: "value1",
  field2: "value2"
}, {
  entityId: "entity_123",
  version: "1.0",
  reqTS: "2026-06-12",
  apiType: "CREATE",
  uniqueId: "unique_id_123"
});

DELETE Request

const data = await client.delete<ResponseType>("/endpoint", {
  entityId: "entity_123",
  version: "1.0",
  reqTS: "2026-06-12",
  apiType: "DELETE",
  uniqueId: "unique_id_123"
});

Note: Headers (3rd parameter) are optional but recommended for proper API requests.

Environment Variables

All configuration is managed through .env file:

| Variable | Description | Required | |----------|-------------|----------| | API_BASE_URL | Base API URL | Yes | | AUTH_ENDPOINT | Authentication endpoint path | Yes | | ENTITY_ID | Entity ID for authentication | Yes | | CLIENT_USER | Client username | Yes | | CLIENT_PWD | Client password | Yes | | IV_KEY | Initialization Vector for encryption | Yes | | SECRET_KEY | Secret key for encryption | Yes |

Available Services

FinTechService

import { FinTechService } from 'fintech-sdk';

const service = new FinTechService();

createService(data, headers)

• Endpoint: POST /APIFinTechCANCreateService
• Parameters:
  • data (object): Request payload
  • headers (object): Custom headers (entityId, version, reqTS, apiType, uniqueId)
• Returns: Response data
• Authentication: Automatic (via SDK)

Example:

const result = await service.createService(
  { transactionId: "123", amount: 500 },
  {
    entityId: "entity_123",
    version: "1.0",
    reqTS: "2026-06-12",
    apiType: "CREATE",
    uniqueId: "unique_id_123"
  }
);

Endpoints (Reference)

Authentication

• POST /GetAccessTokenV1
  • Handled automatically by SDK
  • Request body: { entityId, clientUser, clientPwd }
  • Response: { accessToken: string }

API

• POST /APIFinTechCANCreateService
  • Authenticated with token from /GetAccessTokenV1
  • Called via FinTechService.createService()
  • Request body: Custom data structure
  • Response: API response data

Building

npm run build

This generates TypeScript declaration files and compiled JavaScript in the dist/ folder.

Project Structure

src/
├── client/
│   └── ApiClient.ts       # HTTP client with automatic authentication
└── index.ts               # Public exports

Publishing to npm

1. Update the version in package.json
2. Build the project: npm run build
3. Create an npm account at npmjs.com
4. Login to npm: npm login
5. Publish: npm publish

Token Management

• Automatic Authentication: Token is obtained automatically on first API call
• Token Caching: Token is reused for all subsequent requests (performance optimization)
• Token Expiration Handling: If token expires (401 error):
  • SDK automatically clears the expired token
  • SDK re-authenticates with /GetAccessTokenV1
  • SDK retries the original request
  • No manual intervention needed!

Security Notes

• Never commit .env file to version control
• .env is automatically git-ignored
• All sensitive credentials must be stored in .env
• Token is stored in memory (session-based, not persistent)

License

MIT