@plutosone/ibmb-bank

A robust, enterprise-grade NestJS and TypeScript SDK for seamlessly integrating with the IBMB APIs. This SDK handles everything from authentication to AES-256-GCM encryption, providing a strictly typed and structured developer experience.

Features

• End-to-End Encryption: Built-in AES-256-GCM payload encryption and response decryption.
• Automated Authentication: Seamless JWT token generation, verification, and in-memory token reuse.
• Strictly Typed API: Complete TypeScript definitions for all requests and responses, mapped to a highly ergonomic flat structure.
• Reliable Transport: HTTP/2-first transport implementation with automatic HTTP/1.1 fallback.
• NestJS Native: Designed perfectly for NestJS integration, exposing cleanly decoupled API services.

Installation

Install the package via your preferred package manager:

# Using npm
npm install "@plutosone/ibmb-bank"

# Using yarn
yarn add "@plutosone/ibmb-bank"

# Using pnpm
pnpm add "@plutosone/ibmb-bank"

Configuration

To initialize the client, provide your connection details and keys:

import { IBMBClient } from '@plutosone/ibmb-bank';

const client = new IBMBClient({
  baseURL: process.env.IBMB_BASE_URL || 'https://ibmb-host.example.com',
  organization: process.env.IBMB_ORGANIZATION || 'PLUTOS',
  secretKey: process.env.IBMB_SECRET_KEY,         // For generating tokens
  encryptionKey: process.env.GCM_ENCRYPTION_KEY,  // 32-byte base64 encoded GCM Key
});

Environment Settings (Optional but Recommended)

You can further control network behaviors using environment variables:

IBMB_USE_HTTP2=true
IBMB_ALLOW_H2C=false
IBMB_ALLOW_HTTP1_FALLBACK=true
IBMB_HTTP_TIMEOUT_MS=15000

Usage Guide

You can authenticate the client manually before making transaction calls, or let the SDK handle authentication automatically on-the-fly.

1. Authentication (Auto vs. Manual)

Option A: Auto-Authentication (Recommended)

You can pass auth: 'auto' directly in your transaction request payload. The SDK will automatically handle generating, storing, and refreshing the JWT token.

• In-Memory Caching: The token is securely cached for 1 hour in-memory.
• Deduplication: In-flight token requests are automatically de-duplicated, preventing multiple parallel transaction calls from triggering duplicate token generation API requests.

const fetchResult = await client.transaction.fetch({
  auth: 'auto', // Automatically logs in and caches the token for 1 hour
  url: 'nb://pay?ver=1.0&mode=QR&orgId=IBMB...',
  mobile: '919876543210',
  // ...other fields
});

Option B: Manual Authentication

Alternatively, you can authenticate manually for specific scopes before making your transaction calls:

// Generate and set the token in-memory manually
await client.authenticate(['fetch', 'pay', 'check', 'onus']);

2. Fetch API (POST /ibmb/fetch)

Used to fetch transaction context before processing.

const fetchResult = await client.transaction.fetch({
  url: 'nb://pay?ver=1.0&mode=QR&orgId=IBMB&Tts=2026-05-08T11:59:23+05:30&rId=ABC0120240000000001&expiry=36000',
  mobile: '919876543210',
  GEOCODE: '12.9716,77.5946',
  LOCATION: '12345678-1234-1234-1234-123456789012KAIN',
  IP: '192.168.1.1',
  ID: 'device-id-12345',
  OS: 'Android',
  APP: 'MyApp',
  BROWSER: 'Chrome',
});

console.log(fetchResult.data);

3. Pay API (POST /ibmb/pay)

Executes a payment using a flat payload mapping specifically designed for ergonomic integration.

const payResult = await client.transaction.pay({
  correlationKey: 'paJbeyVer=1',
  transactionRefID: 'PXY126141A7OB6QXC07F',
  transactionTxnID: 'BAN496142A229BFSHSKM',
  transactionTime: '2026-05-22T18:14:45+05:30',
  expiryMs: 86400,
  initiationMode: 'QR',
  netBType: 'RETAIL',
  paID: 'PTS01',
  paName: 'Plutos',
  merchantCode: '2789',
  merchantID: 'PTS01TAMERCHA22',
  merchantName: 'Plutos Merchant',
  successUrl: 'https://reqtxninit.com/return-url/success-landing-page-url/',
  failureUrl: 'https://reqtxninit.com/return-url/failure-landing-page-url/',
  result: 'SUCCESS',
  errCode: '',
  errReason: '',
  amount: 987,
  currency: 'INR',
  mobile: '919897656658',
  acCutomerName: 'suresh',
  acNumber: '',
  acIfc: '',
  acType: 'SAVINGS',
  payType: 'FULL',
  tpvCustName: 'SanjayRamasamyTPVValue',
  tpvAcNum: '1234567890',
  tpvIfsc: 'ICIC0001234',
  os: 'ANDRIOD',
  browser: 'CHROME',
  app: 'HDFC',
  geocode: '02.4536,02.5343',
  location: 'Chennai',
  state: 'TAMIL NADU',
  country: 'INDIA',
  pincode: '600001',
  ip: '10.20.110',
  deviceID: 'API123'
});

console.log(payResult.data);

4. Check API (POST /ibmb/check)

Checks the real-time status of an existing transaction.

const checkResult = await client.transaction.check({
  correlationKey: 'encrypted-correlation-key-from-prior-step',
  orgRefID: 'PJS0160671115DCIHEIA',
  orgTxnID: 'BTS0160671115DCIHEIA',
  orgTxnDate: '2026-03-09T11:15:35+05:30',
  orgTxnAmt: 5,
  initiationMode: 'QR',
});

console.log(checkResult.data);

5. On-Us API (POST /ibmb/onus)

Handles On-Us ("intra-bank") transactions routing.

const onusResult = await client.transaction.onus({
  merchRefNo: 'MERCH001',
  bankRefNo: 'BOU21',
  onusRefNo: 'BOU21ONUS60691V3X567890123456X7E13Z',
  ts: '2026-02-02T10:00:00+05:30',
  category: '01',
  bankMid: 'MID001',
  mName: 'Merchant Name',
  amount: 1500.25,
  currency: 'INR',
  netBType: 'RETAIL',
  IFSC: 'PLUT0000001',
  ACNUM: '1234567890',
  ACTYPE: 'SAVINGS',
  PAYTYPE: 'FULL',
  CUSTNAME: 'Ravi Kumar',
});

console.log(onusResult.data);

Local Test Harness

If you are contributing to or testing this SDK, the package includes a thin NestJS app to expose the SDK APIs locally.

# Start the test harness in development mode
npm run start:dev

# Run unit tests
npm test

# Run e2e tests
npm run test:e2e

Error Handling

Errors from the upstream IBMB APIs are caught and wrapped cleanly in an IbmbUpstreamError. This makes it incredibly easy to parse HTTP error status codes and API error reasoning directly from the thrown exception block.

License

Copyright © Plutos One. All Rights Reserved.