📦 HimoSoft Payments SDK for Node.js & TypeScript

Welcome to the official HimoSoft Payments SDK for Node.js, React, Vue, Next.js, and TypeScript. This zero-dependency, high-performance package allows you to integrate HimoSoft's secure payment gateway into any JavaScript or TypeScript project.

⚡ Key Features

• 🛡️ Secure HMAC-SHA256 Signatures: Sealing payload strings using exact hash matches.
• 🕒 Replay Attack Protection: Auto-embedded timestamp validation.
• 📋 Metadata Schema Verification: Ensures required merchant tracking properties are validated client-side.
• 🌐 Cross-Runtime Signature Engine: Synchronously leverages Node's native crypto module on servers, and seamlessly falls back to asynchronous Web Crypto API on modern secure Edge environments (like Cloudflare Workers or Next.js Edge Runtime).
• 🚀 Zero-Dependency Native Fetch: Built entirely on modern native fetch (requires Node.js >= 18 or compatible Edge/Web environments) to prevent package bloating or Guzzle-like dependency version conflicts.
• ⚡ Dual CJS / ESM Distribution: Built to export both CommonJS (require) and ES Modules (import) natively, with complete TypeScript types (.d.ts).

🔒 CRITICAL Security Guidelines

[!WARNING] NEVER initialize HimoSoftPaymentsClient inside frontend-only React, Vue, Svelte components, or plain client-side browser files. Doing so will expose your apiSecret in raw JavaScript bundles served to the public. Always invoke SDK methods inside secure server-side environments (e.g. Next.js Server Actions, Next.js API Routes, Express.js backend servers, NestJS controllers, Nuxt Server Routes, or SvelteKit +page.server.ts files).

📦 Installation

To install this package in your project, copy the integration-package/nodejs folder or add it locally:

npm install -e ./integration-package/nodejs

🚀 Quickstart Guides

1. TypeScript & ES Modules (Next.js, NestJS, Modern JS)

Creating a payment and retrieving its status asynchronously:

import { HimoSoftPaymentsClient, HimoSoftException } from 'himosoft-payments';

// Initialize Client (Store keys securely in process.env)
const client = new HimoSoftPaymentsClient(
    process.env.HIMOSOFT_API_KEY!,
    process.env.HIMOSOFT_API_SECRET!,
    "https://pay.himosoft.com.bd" // Base gateway URL
);

async function checkoutFlow() {
    try {
        const payment = await client.createPayment({
            amount: "1250.00",
            currency: "BDT",
            reference_id: "INV-99082",
            description: "Enterprise Plan License",
            redirect_url: "https://yourwebsite.com/success",
            
            // Required Customer Metadata
            customer_id: "CUST-TS-102",
            customer_email: "[email protected]",
            customer_name: "Himel Rana",
            
            // Required Product Metadata
            product_name: "Annual Dedicated CPU Cluster",
            product_price: "1250.00",
            product_quantity: 1,
            
            // Optional Fields (System fallbacks will be auto-merged if omitted)
            customer_phone: "01316100897",
            customer_address: "Dhaka, Bangladesh"
        });
        
        console.log("Checkout URL:", payment.checkout_url);
        
        // Retrieve Status Later
        const statusInfo = await client.getPaymentStatus(payment.id);
        console.log("Current Status:", statusInfo.status);
        
    } catch (e) {
        if (e instanceof HimoSoftException) {
            console.error("HimoSoft SDK Failure:", e.message);
        }
    }
}

2. CommonJS / Legacy JavaScript (Express, plain Node.js)

const { HimoSoftPaymentsClient, HimoSoftException } = require('himosoft-payments');

const client = new HimoSoftPaymentsClient(
    process.env.HIMOSOFT_API_KEY,
    process.env.HIMOSOFT_API_SECRET,
    "https://pay.himosoft.com.bd"
);

async function run() {
    try {
        const payment = await client.createPayment({
            amount: "300.00",
            currency: "BDT",
            reference_id: "INV-CJS-77",
            description: "Standard Plan Buy",
            redirect_url: "https://yourwebsite.com/success",
            customer_id: "CUST-JS-202",
            customer_email: "[email protected]",
            customer_name: "JS CJS Coder",
            product_name: "Starter Shared Hosting Bundle",
            product_price: "300.00",
            product_quantity: 1
        });
        
        console.log("Checkout URL:", payment.checkout_url);
    } catch (e) {
        if (e instanceof HimoSoftException) {
            console.error("SDK Error:", e.message);
        }
    }
}
run();

📖 API Reference Guide

HimoSoftPaymentsClient Initialization

const client = new HimoSoftPaymentsClient(apiKey, apiSecret, baseUrl);

1. Create Payment

await client.createPayment(params: HimoSoftPaymentParams);

HimoSoftPaymentParams Details:

• amount: string - Payment amount (e.g. "500.00")
• currency: string - "BDT" or "USD"
• reference_id: string - Your unique invoice / reference ID
• description: string - Description of invoice
• redirect_url: string - Success redirect URL
• customer_id: string - Required
• customer_email: string - Required
• customer_name: string - Required
• product_name: string - Required
• product_price: string - Required
• product_quantity: number - Required
• idempotency_key: string (optional) - Secure UUID generated automatically if empty
• customer_phone: string (optional) - Merged with fallback if empty
• customer_address: string (optional) - Merged with fallback if empty
• product_image: string (optional) - Merged with fallback if empty
• product_url: string (optional) - Merged with fallback if empty
• custom_metadata: Record<string, any> (optional) - Custom tags

2. Get Payment Status (Reconcile)

await client.getPaymentStatus(paymentId: string);

3. Database Status Only Check

await client.verifyPayment(paymentId: string);

4. Force Live Gateway Reconciliation Check

await client.recheckPayment(paymentId: string);

5. Cancel Pending Session

await client.cancelPayment(paymentId: string);

6. Verify Webhook Signature (Callback protection)

import { HimoSoftPaymentsClient } from 'himosoft-payments';

// Inside your API/Webhook endpoint handler (e.g. Express or Next.js API Routes):
const payload = req.body; // Parsed JSON body object
const signatureHeader = req.headers['x-signature'] as string || '';
const timestampHeader = req.headers['x-timestamp'] as string || '';

// Verify incoming webhook signature to protect against tampering
const isValid = await HimoSoftPaymentsClient.verifyWebhookSignature(
    payload,
    signatureHeader,
    timestampHeader,
    process.env.HIMOSOFT_API_SECRET!
);

if (isValid) {
    // Process the webhook event securely
} else {
    // Reject request (401 Unauthorized / tampered)
}

🛡️ Robust Exception Handling

The SDK exposes granular exception classes inheriting from HimoSoftException:

import {
    HimoSoftException,
    HimoSoftAuthException,
    HimoSoftValidationException,
    HimoSoftApiException
} from 'himosoft-payments';

try {
    const payment = await client.createPayment({...});
} catch (e) {
    if (e instanceof HimoSoftAuthException) {
        // Invalid keys or signature failures
    } else if (e instanceof HimoSoftValidationException) {
        // Missing parameters locally prior to connection
    } else if (e instanceof HimoSoftApiException) {
        // Gateway responded with error status
        console.error("HTTP Code:", e.statusCode);
        console.error("Gateway Body:", e.responseBody);
    } else if (e instanceof HimoSoftException) {
        // Base fallback error
    }
}