@kothatech/ssl-integration-kit

A lightweight, production-ready Node.js SDK for integrating the SSLCommerz payment gateway directly on your server. Built and maintained by Kotha.

Features

• 🚀 Zero Dependencies (besides node-fetch): Lightweight and fast.
• 💳 Payment Initiation: Start checkout sessions easily.
• 🔒 IPN Hash Verification: Authenticate Instant Payment Notification callbacks cryptographically using MD5 hash comparison.
• ✅ Transaction Validation: Securely query SSLCommerz validation servers server-to-server.
• 🛠 Sandbox & Live Modes: Toggle sandbox environment with a single boolean flag.

Installation

Install the package via npm:

npm install @kothatech/ssl-integration-kit

Quick Start

1. Initialize the Client

Import the integration class and configure it with your SSLCommerz credentials:

const { SslCommerzIntegration } = require('@kothatech/ssl-integration-kit');

const sslcommerz = new SslCommerzIntegration({
  store_id: 'your_store_id',
  store_passwd: 'your_store_password',
  is_sandbox: true // Set to false for production / live mode
});

Usage Guide

2. Initiate a Payment Session

Call initiatePayment() with the required payment and customer metadata. It will return a JSON response containing GatewayPageURL to redirect your customer to.

app.post('/api/pay', async (req, res) => {
  try {
    const session = await sslcommerz.initiatePayment({
      total_amount: 100,
      currency: 'BDT',
      tran_id: 'TXN_' + Date.now(),
      success_url: 'https://yoursite.com/api/payment/success',
      fail_url: 'https://yoursite.com/api/payment/fail',
      cancel_url: 'https://yoursite.com/api/payment/cancel',
      ipn_url: 'https://yoursite.com/api/payment/ipn',
      cus_name: 'John Doe',
      cus_email: '[email protected]',
      cus_phone: '01711000000',
      cus_add1: 'Dhaka',
      cus_city: 'Dhaka',
      cus_country: 'Bangladesh',
      shipping_method: 'NO',
      product_name: 'Test Product',
      product_category: 'General',
      product_profile: 'general'
    });

    if (session.GatewayPageURL) {
      // Send the payment page URL back to the frontend
      res.json({ gateway_url: session.GatewayPageURL });
    } else {
      res.status(400).json({ error: 'Failed to initiate payment session', details: session });
    }
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

3. Handle Instant Payment Notification (IPN) Callbacks

When a transaction status changes, SSLCommerz hits your server's ipn_url via a POST request. You must verify the authenticity of the payload before updating your database.

app.post('/api/payment/ipn', (req, res) => {
  try {
    // 1. Verify that the IPN signature is authentic and untampered
    const isValid = sslcommerz.verifyIpnHash(req.body);
    
    if (isValid) {
      const { status, val_id, tran_id, amount } = req.body;
      
      if (status === 'VALID' || status === 'VALIDATED') {
        console.log(`Payment successful for Transaction: ${tran_id}. Val_ID: ${val_id}`);
        // TODO: Deliver product/service in database
      }
      
      res.status(200).send('IPN Received and Verified');
    } else {
      res.status(400).send('Invalid signature');
    }
  } catch (error) {
    res.status(500).send('Internal Server Error');
  }
});

4. Validate Transaction Manually (Server-to-Server)

To double-check the details of a successful transaction (such as inside the success callback route), call validateTransaction() with the val_id received from the gateway:

app.post('/api/payment/success', async (req, res) => {
  const { val_id, tran_id } = req.body;

  try {
    const verification = await sslcommerz.validateTransaction(val_id);
    
    if (verification.status === 'VALID' || verification.status === 'VALIDATED') {
      res.send(`<h1>Payment Success! Order Verified.</h1><p>Transaction ID: ${tran_id}</p>`);
    } else {
      res.status(400).send('<h1>Payment Verification Failed</h1>');
    }
  } catch (error) {
    res.status(500).send('Error verifying payment');
  }
});

License

This project is licensed under the MIT License.