pay-pak (Node.js)

pay-pak is a unified Node.js/TypeScript SDK for accepting payments through Pakistani payment gateways: JazzCash, EasyPaisa, Safepay, NayaPay (plus PayFast and Raast scaffolds).

One API for every gateway. Every driver verifies callback signatures with constant-time comparison and never fakes flows it does not support.

TypeScript port of the Python pay-pak package.

npm install pay-pak

import { PayPak, PaymentRequest } from 'pay-pak';

const paypak = new PayPak();
const request = new PaymentRequest({ amount: 150_00, orderId: 'ORDER-1001' });

await paypak.gateway('jazzcash').checkout(request);        // hosted redirect
await paypak.gateway('jazzcash').charge(request);           // direct wallet
await paypak.gateway('jazzcash').verifyCallback(inbound);   // signed callback

Requirements

• Node.js 18+ (native fetch and crypto)
• Zero core runtime dependencies

Installation

Core package

npm install pay-pak

Optional adapters

npm install express          # for pay-pak/express
npm install fastify          # for pay-pak/fastify
npm install next             # for pay-pak/nextjs
npm install ioredis          # for pay-pak/redis (multi-worker cache)

Quick start

1. Set environment variables

Copy .env.example to .env:

PAKPAY_MODE=sandbox
PAKPAY_GATEWAY=jazzcash

JAZZCASH_MERCHANT_ID=your_merchant_id
JAZZCASH_PASSWORD=your_password
JAZZCASH_INTEGRITY_SALT=your_salt
JAZZCASH_RETURN_URL=https://your-app.com/payments/jazzcash/return

2. Start a payment

import { PayPak, PaymentRequest } from 'pay-pak';

const paypak = new PayPak();
const request = new PaymentRequest({
  amount: 150_00,              // PKR 150.00 — always integer paisa
  orderId: 'ORDER-1001',
  description: 'Blue Widget x1',
});

const { redirectUrl } = await paypak.gateway('jazzcash').checkout(request);
// Redirect customer to redirectUrl

3. Verify the callback

import { toInboundRequest } from 'pay-pak/express'; // or fastify / nextjs

app.post('/payments/jazzcash/return', async (req, res) => {
  const inbound = await toInboundRequest(req);
  const result = await paypak.gateway('jazzcash').verifyCallback(inbound);

  if (result.isPaid()) {
    // fulfil order result.orderId
  }
  res.send('OK');
});

Framework integration

Express

import express from 'express';
import { createPakpayRouter, toInboundRequest } from 'pay-pak/express';
import { PayPak } from 'pay-pak';

const app = express();
const paypak = new PayPak();

app.use(express.urlencoded({ extended: true }));
app.use(express.json());
app.use(createPakpayRouter({ prefix: 'pakpay', cache: paypak.getCache() }));

Fastify

import Fastify from 'fastify';
import { pakpayRedirectPlugin } from 'pay-pak/fastify';

const fastify = Fastify();
await fastify.register(pakpayRedirectPlugin, {
  prefix: '/pakpay',
  cache: paypak.getCache(),
});

Next.js App Router

// app/pakpay/redirect/[token]/route.ts
import { redirectHandler } from 'pay-pak/nextjs';

export const GET = redirectHandler({ cache: paypak.getCache() });

Gateway capability matrix

| Gateway | checkout | charge | refund | status | verify | |-----------|:--------:|-----------------|:------:|:------:|---------------------| | jazzcash | ✅ | ✅ Mobile Wallet | ✅ | ✅ | HMAC pp_SecureHash | | easypaisa | ✅ | ✅ Mobile Account| ❌ | ✅ | HMAC return signature | | safepay | ✅ | ❌ | ✅ | ✅ | X-SFPY-Signature webhook | | nayapay | ✅ | ❌ | ❌ | ✅ | HMAC signature | | payfast | 🚧 | 🚧 | 🚧 | 🚧 | 🚧 | | raast | 🚧 | 🚧 | 🚧 | 🚧 | 🚧 |

Package exports

| Import | Purpose | |---------------------|----------------------------------------------| | pay-pak | Core SDK | | pay-pak/express | Express router + toInboundRequest | | pay-pak/fastify | Fastify plugin + toInboundRequest | | pay-pak/nextjs | App Router handler + toInboundRequest | | pay-pak/redis | RedisCache for multi-worker deployments |

Security model

• Amounts are always integer paisa — never floats
• Callbacks are signature-verified before any field is trusted
• Hosted checkout uses one-time redirect tokens (600s TTL)
• Unsupported flows raise UnsupportedFlowException — never fake success
• Safepay webhooks include replay protection (300s window)

Testing

npm test

55 tests cover signature parity (matching Python vectors), driver flows, redirect tokens, manager factory, and framework adapters.

npm run demo

Publishing

See docs/PUBLISHING.md.

License

MIT — see LICENSE.