bd-pay-kit

TypeScript-first, backend-oriented SDK for Bangladesh payment gateway integrations.

bd-pay-kit gives Node.js applications a single public entry point for bKash, SSLCommerz, Nagad, and Rocket, while keeping provider-specific details available when you need them.

Current status

| Gateway | Status | Notes | | --- | --- | --- | | bKash | Implemented | Token grant/refresh, agreements, payments, payment queries, transaction search, refunds, and refund-status flows are available. | | SSLCommerz | Implemented | Init payment, validate payment, query by session or transaction, refund initiation, refund query, and IPN hash verification are available. | | Nagad | Conservative | The package exports NagadClient, validates verified setup requirements, and exposes guarded runtime methods that intentionally fail fast until official merchant/API docs are available. | | Rocket | Conservative | The package exports RocketClient and models the verified manual merchant-payment flow. It does not expose a verified live backend Rocket API client. |

Install

Published package:

npm install bd-pay-kit

Local repository development:

corepack pnpm install
npm run build

Requirements:

• Node.js 18.18 or newer
• pnpm 10 for local monorepo work

Public imports

Direct client imports:

import {
  BkashClient,
  SSLCommerzClient,
  NagadClient,
  RocketClient,
} from "bd-pay-kit";

Factory import:

import { createGateway } from "bd-pay-kit";

The SDK also re-exports selected shared/core public types, helpers, and error classes.

Quick start

Direct client usage:

import { BkashClient } from "bd-pay-kit";

const bkash = new BkashClient({
  environment: "sandbox",
  username: process.env.BKASH_USERNAME!,
  password: process.env.BKASH_PASSWORD!,
  appKey: process.env.BKASH_APP_KEY!,
  appSecret: process.env.BKASH_APP_SECRET!,
  callbackBaseUrl: "https://merchant.example.com/webhooks/bkash/payment",
});

const payment = await bkash.createPayment({
  agreementId: "agreement-id",
  payerReference: "payer-reference",
  amount: "100.00",
  merchantInvoiceNumber: "INV-1001",
});

Factory usage:

import { createGateway } from "bd-pay-kit";

const sslcommerz = createGateway("sslcommerz", {
  environment: "sandbox",
  storeId: process.env.SSLCOMMERZ_STORE_ID!,
  storePassword: process.env.SSLCOMMERZ_STORE_PASSWORD!,
});

const session = await sslcommerz.initPayment({
  totalAmount: "100.00",
  currency: "BDT",
  transactionId: "INV-1001",
  successUrl: "https://merchant.example.com/webhooks/sslcommerz/success",
  failUrl: "https://merchant.example.com/webhooks/sslcommerz/fail",
  cancelUrl: "https://merchant.example.com/webhooks/sslcommerz/cancel",
  customer: {
    name: "Test User",
    email: "[email protected]",
    addressLine1: "Dhaka",
    city: "Dhaka",
    postcode: "1207",
    country: "Bangladesh",
    phone: "01700000000",
  },
  shippingMethod: "NO",
  product: {
    name: "Order payment",
    category: "general",
    profile: "general",
  },
});

createGateway()

createGateway() currently supports:

• "bkash"
• "sslcommerz"
• "nagad"
• "rocket"

The factory is a convenience layer. Direct client construction remains fully supported.

Supported gateways

bKash

Implemented tokenized-checkout flows:

• grantToken()
• refreshToken()
• createAgreement()
• executeAgreement()
• queryAgreement()
• cancelAgreement()
• createPayment()
• executePayment()
• createPaymentWithAgreement()
• executePaymentWithAgreement()
• queryPayment()
• searchTransaction()
• refundPayment()
• refundStatus()

SSLCommerz

Implemented hosted-checkout flows:

• initPayment()
• validatePayment()
• queryBySession()
• queryByTransaction()
• initiateRefund()
• refundQuery()
• verifyIpn()

Nagad

Current package surface:

• describeSetup()
• guarded createPayment()
• guarded verifyPayment()
• guarded queryPayment()
• verifyCallback()
• validateWebhook()
• verifyNotification()

The runtime payment methods are intentionally blocked until official merchant/API documentation is verified in the repo.

Rocket

Current package surface:

• describeMerchantPayment()
• manual-flow createPayment()
• guarded verifyPayment()
• guarded queryPayment()
• verifyNotification()
• validateWebhook()

Rocket currently models the documented manual merchant-payment flow only. It does not claim a verified live backend API integration.

Examples

The repository includes backend-only example apps:

• examples/express for an Express server integration example
• examples/nextjs for Next.js App Router route-handler examples

Each example uses environment variables and ships with .env.example placeholders only.

Sandbox vs production

• bKash includes a built-in sandbox base URL. Production requires an explicit baseUrl because live endpoints are merchant-specific.
• SSLCommerz defaults to the official sandbox and live base URLs and also allows an explicit baseUrl override.
• Nagad does not expose verified public runtime base URLs in the current package because the repo does not yet verify a stable public backend API contract.
• Rocket does not expose backend base URLs because the current package only models the documented manual merchant-payment flow.

Backend safety

This SDK is designed for server-side Node.js usage.

Do not expose gateway credentials, secrets, callback verification logic, payment verification flows, or refund operations to the browser. Keep secrets on the backend, and use environment variables or a secure secret manager in real deployments.

Package structure

packages/
  core/         shared transport, base abstractions, errors
  shared/       normalized enums, interfaces, helpers
  bkash/        bKash implementation
  sslcommerz/   SSLCommerz implementation
  nagad/        conservative Nagad package
  rocket/       conservative Rocket package
  sdk/          public npm package entry point
examples/
  express/      Express backend example
  nextjs/       Next.js route-handler example
tests/          mocked and integration-style test coverage

Development scripts

Useful root scripts:

• npm run typecheck
• npm run build
• npm test
• npm run pack:sdk
• npm run clean

Versioning and releases

The public package is currently in the pre-1.0 release line.

• the publishable package is packages/sdk
• internal workspace packages remain private
• check CHANGELOG.md for release notes
• expect cautious iteration while the public API stabilizes toward 1.0.0

License

This repository is licensed under the MIT License. See LICENSE.