@ng-pay/paystack

Paystack adapter for the ng-pay unified Nigerian fintech SDK.

Installation

npm install @ng-pay/core @ng-pay/paystack

Quick start

import { PaystackProvider } from "@ng-pay/paystack";
import { toKobo } from "@ng-pay/core";

const paystack = new PaystackProvider({
  secretKey: process.env.PAYSTACK_SECRET_KEY!,
});

Configuration

const paystack = new PaystackProvider({
  secretKey: "sk_live_...", // required — must start with sk_live_ or sk_test_
  preferredBank: "wema-bank", // optional — bank for virtual accounts (default: 'wema-bank')
  timeoutMs: 30_000, // optional — request timeout in ms (default: 30000)
  maxRetries: 3, // optional — retry attempts on 5xx errors (default: 3)
});

Supported banks for virtual accounts:

• wema-bank — Wema Bank (default, most widely available)
• titan-paystack — Titan Trust Bank
• sterling-bank — Sterling Bank

Payments

// Initialize — returns a URL to redirect your customer to
const payment = await paystack.initializePayment({
  amount: { amount: toKobo(5000), currency: "NGN" }, // ₦5,000
  customer: {
    email: "[email protected]",
    firstName: "Adaobi",
    lastName: "Nwosu",
  },
  reference: "order_123", // optional
  callbackUrl: "https://yourapp.com/payment/callback",
  channels: ["card", "bank_transfer"], // optional
});

// Redirect your user
console.log(payment.authorizationUrl);

// Verify after callback
const result = await paystack.verifyPayment("order_123");
console.log(result.status); // 'success' | 'failed' | 'pending' | 'abandoned'

Virtual accounts (NUBAN)

const account = await paystack.createVirtualAccount({
  customer: {
    email: "[email protected]",
    firstName: "Adaobi",
    lastName: "Nwosu",
    phone: "08012345678",
  },
  // Override bank for this specific account:
  metadata: { preferredBank: "titan-paystack" },
});

console.log(account.accountNumber); // "0123456789"
console.log(account.bankName); // "Titan Trust Bank"

Transfers (payouts)

// Step 1: create a recipient
const recipient = await paystack.createTransferRecipient({
  name: "Adaobi Nwosu",
  accountNumber: "0123456789",
  bankCode: "058", // GTBank
});

// Step 2: send money
const transfer = await paystack.initiateTransfer({
  amount: { amount: toKobo(1000), currency: "NGN" }, // ₦1,000
  recipientCode: recipient.recipientCode,
  description: "Refund - order_123",
});

// Step 3: verify
const status = await paystack.verifyTransfer(transfer.reference);

Banks & account resolution

const banks = await paystack.getBanks();
// [{ name: 'GTBank', code: '058', ... }, ...]

const account = await paystack.resolveAccount("0123456789", "058");
// { accountName: 'ADAOBI NWOSU', accountNumber: '0123456789', ... }

Webhooks

import express from "express";

const app = express();

app.post(
  "/webhooks/paystack",
  express.raw({ type: "application/json" }), // must be raw body
  (req, res) => {
    const signature = req.headers["x-paystack-signature"] as string;
    const rawBody = req.body.toString();

    if (!paystack.verifyWebhook(rawBody, signature)) {
      return res.status(401).send("Invalid signature");
    }

    const event = paystack.parseWebhookEvent(JSON.parse(rawBody));

    if (event.event === "charge.success") {
      console.log("Payment received:", event.reference);
    }

    res.sendStatus(200);
  },
);

Or use the middleware package for a cleaner integration — see @ng-pay/middleware.

Links

• GitHub
• Paystack API docs
• npm — @ng-pay/core