One way to take money,four ways to receive it.

Never done this before? Start here.

Skip ahead if you already integrate payment gateways for a living.

Some words you'll see everywhere

Everything is one of four actions

The entire library is these four verbs. Every gateway uses the same ones.

Every one of them answers in the same shape, no matter which gateway you used:

{
  success: true,              // did it work?
  transactionId: 'pi_3Nk...', // the receipt number — save this
  status: 'succeeded',        // the gateway's own wording
  amount: 1000,
  currency: 'usd',
  gatewayResponse: { ... }    // the untouched raw reply, if you need it
}

Install

npm install bdpayments

That's everything for SSLCommerz, bKash and Nagad — they need no extra software. Only add Stripe's own package if you use Stripe:

npm install stripe   # only if you use Stripe

The one decision to make first

Before writing any code, work out which of these describes you. It changes where your secret keys live — and almost nothing else.

Side by side

Mode A — Single company

One business, one set of keys. Tell BDPayments about them once when your app boots.

Every payment ends up in the same place, so one set of keys covers everything.

1. Put your keys in environment variables

   Never type secret keys directly into your code — anyone who reads your repository would see them. Keep them in a .env file that you never commit.

   # .env  — add this file to .gitignore!
   STRIPE_API_KEY=sk_test_...
   
   BKASH_APP_KEY=...
   BKASH_APP_SECRET=...
   BKASH_USERNAME=...
   BKASH_PASSWORD=...
   BKASH_SANDBOX=true

   Copy

   That alone is enough — BDPayments reads these automatically. The next step is only if you prefer setting them in code.

2. Or call configure() once at startup

   Useful when your keys come from a secrets manager rather than the environment.

   import { configure } from 'bdpayments';
   
   configure({
     stripe: { apiKey: process.env.STRIPE_API_KEY },
     bkash: {
       appKey:    process.env.BKASH_APP_KEY,
       appSecret: process.env.BKASH_APP_SECRET,
       username:  process.env.BKASH_USERNAME,
       password:  process.env.BKASH_PASSWORD,
       sandbox:   true,
     },
   });

   Copy

3. Take a payment — no keys needed here

   From now on every call finds the credentials by itself.

   import { charge } from 'bdpayments';
   
   const payment = await charge({
     gateway: 'bkash',
     amount: 500,
     invoiceNumber: 'INV-001',
     callbackURL: 'https://myshop.com/bkash/callback',
   });
   
   // Send the customer here to approve the payment
   console.log(payment.bkashURL);

   Copy

Mode B — Multi-tenant SaaS

Many businesses on one platform, each with their own merchant account. Money must reach the right one.

Three separate destinations, so three separate sets of keys — and the lanes must never cross.

1. Collect each tenant's keys when they sign up

   Rahim opens his own bKash merchant account and pastes those keys into your dashboard. Store them encrypted — they are as sensitive as passwords.

   // A tenants table, credentials encrypted at rest
   await db.tenants.update(tenantId, {
     bkash: encrypt({
       appKey:    '...',
       appSecret: '...',
       username:  '...',
       password:  '...',
       sandbox:   false,
     }),
   });

   Copy

2. Look them up and pass them with the payment

   Keys given directly to a call always win over anything global. This single feature is the whole of multi-tenant support.

   import { charge } from 'bdpayments';
   
   async function chargeForTenant(tenantId, order) {
     const creds = decrypt(await db.tenants.getBkash(tenantId));
   
     return charge({
       gateway: 'bkash',
   
       // --- this tenant's credentials ---
       appKey:    creds.appKey,
       appSecret: creds.appSecret,
       username:  creds.username,
       password:  creds.password,
       sandbox:   creds.sandbox,
   
       // --- the payment itself ---
       amount: order.total,
       invoiceNumber: order.id,
       callbackURL: `https://platform.com/cb/${tenantId}`,
     });
   }

   Copy

3. Works identically for every gateway

   Same idea, different key names. Nothing else about your code changes.

   // Stripe — one tenant, one account
   await charge({ gateway: 'stripe', apiKey: creds.apiKey,
                  amount: 1000, currency: 'usd' });
   
   // SSLCommerz — one tenant, one store
   await charge({ gateway: 'sslcommerz',
                  storeId: creds.storeId, storePassword: creds.storePassword,
                  sandbox: false, amount: 1000, transactionId: 'TXN-1',
                  successUrl: '...', failUrl: '...', cancelUrl: '...' });
   
   // Nagad — one tenant, one merchant + key pair
   await charge({ gateway: 'nagad',
                  merchantId: creds.merchantId,
                  publicKey: creds.publicKey, privateKey: creds.privateKey,
                  amount: 500, orderId: 'ORD-1' });

   Copy

Built to keep tenants apart

Speeding things up must never mean mixing two tenants' money. Here is what the library does about that, so you don't have to:

How keys are found

Three places, checked in order. The first one that has a key wins — which is what lets a tenant override your defaults.

So a platform can keep its own keys as the default and still let individual tenants bring theirs:

// Platform default, set once at startup
configure({ stripe: { apiKey: process.env.PLATFORM_STRIPE_KEY } });

// Tenants without their own account use the platform's
await charge({ gateway: 'stripe', amount: 1000, currency: 'usd' });

// Tenants with their own account override it, just for this call
await charge({ gateway: 'stripe', apiKey: tenant.stripeKey,
               amount: 1000, currency: 'usd' });

If a required key is missing you get told exactly which one, before any network call:

ConfigurationError: Missing required credentials for "bkash": appSecret, password.
Provide them via configure(), per-call options, or environment variables.

The payment journey

What actually happens between "customer clicks Pay" and "order marked paid".

Redirect gateways — SSLCommerz & Nagad

The customer leaves your site to pay, then comes back.

bKash — approve, then finish

bKash splits it into two calls: you create the payment, the customer approves it in the bKash app, then you complete it.

Stripe — one step

With a saved card, a single charge() completes the payment. No redirect, no second call.

The four gateways

Each one loads only when you actually use it, so unused gateways cost you nothing.

What each one can do

You can also ask at runtime:

import { getGatewayCapabilities } from 'bdpayments';

await getGatewayCapabilities('bkash');
// { charge: true, execute: true, refund: true, retrieve: true }

Charge — asking for money

Same function, four gateways. Only the extra fields differ. Add credentials to any of these if you're multi-tenant.

const payment = await charge({
  gateway: 'stripe',
  amount: 2000,          // 2000 = $20.00 — always the smallest unit (cents)
  currency: 'usd',
  paymentMethod: 'pm_card_visa',
  confirm: true,
  description: 'Order #1234',
  metadata: { orderId: '1234' },
});

payment.status; // "succeeded"

const payment = await charge({
  gateway: 'sslcommerz',
  amount: 1000,          // 1000 = 1000 BDT (not the smallest unit)
  currency: 'BDT',
  transactionId: 'TXN-001',   // your own unique order reference
  successUrl: 'https://myshop.com/success',
  failUrl:    'https://myshop.com/fail',
  cancelUrl:  'https://myshop.com/cancel',
  customerName: 'Rahim Uddin',
  customerEmail: 'rahim@example.com',
});

// Send the customer here to pay
redirect(payment.gatewayPageURL);

const payment = await charge({
  gateway: 'bkash',
  amount: 500,                    // 500 BDT
  invoiceNumber: 'INV-001',       // your own order reference
  payerReference: '01700000000',  // customer's bKash number
  callbackURL: 'https://myshop.com/bkash/callback',
});

redirect(payment.bkashURL);   // customer approves here
// then call execute() with payment.paymentID

const payment = await charge({
  gateway: 'nagad',
  amount: 500,               // 500 BDT
  orderId: 'ORD-001',        // your own order reference
  callbackURL: 'https://myshop.com/nagad/callback',
});

redirect(payment.callBackUrl);

Execute — finishing a bKash payment

Only bKash needs this. It is the step where money actually moves.

import { execute } from 'bdpayments';

const result = await execute({
  gateway: 'bkash',
  paymentID: 'TR0011...',   // from charge()
});

result.status;  // "Completed"
result.trxID;   // save this — you need it to refund

Refund — giving money back

import { refund } from 'bdpayments';

// Full refund
await refund({ gateway: 'stripe', transactionId: 'pi_...' });

// Partial refund — $5.00 of a larger payment
await refund({ gateway: 'stripe', transactionId: 'pi_...', amount: 500 });

// bKash needs both IDs: the payment's and the transaction's
await refund({
  gateway: 'bkash',
  transactionId: 'TR0011...',  // paymentID from charge()
  trxID: 'BGH7DS8...',         // trxID from execute()
  amount: 200,
  reason: 'Customer requested',
});

Retrieve — checking what really happened

The only trustworthy answer to "did they pay?".

import { retrieve } from 'bdpayments';

const details = await retrieve({
  gateway: 'stripe',
  transactionId: 'pi_...',
});

details.success;   // true
details.status;    // "succeeded"
details.amount;    // 1000

Validating an SSLCommerz return

When SSLCommerz sends the customer back, it includes a val_id. Hand that to retrieve() and it checks directly with SSLCommerz's servers.

const validation = await retrieve({
  gateway: 'sslcommerz',
  valId: req.body.val_id,   // from the callback or IPN
});

if (validation.success) {
  await markOrderPaid(validation.transactionId);
}

When the network hiccups

The scariest moment in payments: you asked for money, and never heard back. Did it go through?

await charge({
  gateway: 'stripe',
  amount: 1000,
  currency: 'usd',
  idempotencyKey: `order-${order.id}`,   // same key = charged once
});

Timeouts

Requests give up after 30 seconds instead of hanging forever. Adjust per gateway if you need to:

configure({ stripe: { apiKey: '...', timeoutMs: 10000 } });

Webhooks & IPN

The gateway phoning your server directly to report a payment. More reliable than the customer's browser — but you must check the call is genuine.

import { verifySslcommerzIpn, retrieve } from 'bdpayments';

app.post('/ipn/sslcommerz', async (req, res) => {
  // 1. Is this really from SSLCommerz?
  if (!verifySslcommerzIpn(req.body)) return res.sendStatus(400);

  // 2. Confirm the status with SSLCommerz itself
  const payment = await retrieve({
    gateway: 'sslcommerz',
    valId: req.body.val_id,
  });

  // 3. Only now is it safe to fulfil the order
  if (payment.success) await markOrderPaid(payment.transactionId);

  res.sendStatus(200);
});

import { parseNagadCallback, retrieve } from 'bdpayments';

const cb = parseNagadCallback(req.query);
// { orderId, paymentRefId, status, amount, verified: false, raw }

const payment = await retrieve({
  gateway: 'nagad',
  transactionId: cb.paymentRefId,
});

When things go wrong

Every failure throws a PaymentError with a code you can branch on — never a vague string.

import { charge, PaymentError, GatewayNotFoundError, ConfigurationError }
  from 'bdpayments';

try {
  await charge({ gateway: 'stripe', amount: 1000, currency: 'usd' });
} catch (error) {
  if (error instanceof ConfigurationError) {
    console.log('Missing keys:', error.missingKeys);      // ["apiKey"]
  } else if (error instanceof GatewayNotFoundError) {
    console.log('Try one of:', error.supportedGateways);
  } else if (error instanceof PaymentError) {
    console.log(error.gateway);  // "stripe"
    console.log(error.code);     // "CHARGE_FAILED"
    console.log(error.status);   // HTTP status, or null
  }
}

Before you take real money

API reference

Environment variables

The lowest-priority way to supply credentials — ideal for single-company setups.

TypeScript

Types ship with the package. Options are narrowed by gateway, so fields belonging to another gateway are rejected as you type.

import { charge, execute, type PaymentResult } from 'bdpayments';

const result: PaymentResult = await charge({
  gateway: 'stripe',
  amount: 1000,
  currency: 'usd',
  paymentMethod: 'pm_card_visa',
});

await charge({
  gateway: 'stripe',
  amount: 1000,
  currency: 'usd',
  invoiceNumber: 'INV-1',   // ✗ Error: bKash-only field
});

await charge({
  gateway: 'bkash',
  amount: 500,              // ✗ Error: invoiceNumber is required
});

await execute({ gateway: 'bkash', paymentID: 'TR0011...' });   // ✓

Anything the types don't model goes through extra, forwarded to the gateway untouched.