JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 448
  • Score
    100M100P100Q112235F
  • License MIT

The most comprehensive Node.js SDK for Paystack - Complete, Type-safe, and Spec-compliant with full OpenAPI coverage and webhook verification.

Package Exports

  • @alexasomba/paystack-node
  • @alexasomba/paystack-node/webhooks

Readme

@alexasomba/paystack-node

npm version license

TypeScript-first Paystack API client for Node.js, generated from this repo’s OpenAPI spec.

This package provides:

  • A typed low-level client (createPaystackClient) backed by openapi-fetch.
  • Ergonomic operation helpers generated from operationId (transaction_initialize, transferrecipient_update, ...).
  • Built-in webhook signature verification.

Why this SDK

  • Spec-driven: Generated from the OpenAPI spec in this repo (keeps surface area aligned with the spec).
  • Production-friendly: Built-in timeoutMs and safe retry defaults (idempotent methods only).
  • Safe retries for POST: Optional idempotencyKey support to prevent duplicate operations.
  • Better debugging: PaystackApiError includes status and requestId when available.
Supported Modules (31/31)
  • Charge
  • Customers
  • Plans
  • Products
  • Subscriptions
  • Transactions
  • Verify Payments (Transaction verification)
  • Transfers
  • Dedicated Virtual Accounts
  • Apple Pay
  • Subaccounts
  • Transaction Splits
  • Settlements
  • Transfers Control (OTP settings; under Transfers)
  • Transfer Recipients
  • Bulk Charges
  • Refunds
  • Verification (Resolve Account / Validate Account / Resolve Card BIN)
  • Miscellaneous
  • Disputes
  • Control Panel (Payment session timeout)
  • Terminal
  • Virtual Terminal
  • Direct Debit
  • Payment Pages
  • Payment Requests (Invoices)
  • Integration
  • Balance
  • Banks
  • Orders
  • Storefronts

Install

pnpm add @alexasomba/paystack-node

Usage

import {
  assertOk,
  createPaystack,
  PaystackApiError,
  toPaystackApiError,
} from "@alexasomba/paystack-node";

const paystack = createPaystack({
  secretKey: process.env.PAYSTACK_SECRET_KEY!,
  // Optional reliability knobs
  timeoutMs: 30_000,
  retry: { retries: 2 },
  // Optional: auto-add Idempotency-Key on POST requests
  idempotencyKey: "auto",
});

// ergonomic operation wrappers (generated from operationId)
const result = await paystack.transaction_initialize({
  body: {
    email: "customer@example.com",
    amount: 5000,
  },
});

try {
  const data = assertOk(result);
  console.log(data);
} catch (e) {
  if (e instanceof PaystackApiError) {
    // Useful for support/debugging
    console.error("Paystack requestId:", e.requestId);
  }
  throw e;
}

ESM Requirement

This package is ESM-only. Ensure your package.json has "type": "module".

Webhooks

Webhook signature verification requires the raw request body.

import { verifyPaystackWebhookSignature } from "@alexasomba/paystack-node/webhooks";

const ok = verifyPaystackWebhookSignature({
  rawBody: req.rawBody,
  signature: req.headers["x-paystack-signature"] as string,
  secret: process.env.PAYSTACK_SECRET_KEY!,
});

Low-level client usage

If you prefer calling by path/method:

import { createPaystackClient } from "@alexasomba/paystack-node";

const client = createPaystackClient({
  secretKey: process.env.PAYSTACK_SECRET_KEY!,
});

const { data, error } = await client.POST("/transaction/initialize", {
  body: { email: "customer@example.com", amount: 5000 },
});

Coverage

The Node SDK currently generates ~119 typed operations from the bundled OpenAPI spec. For missing/incorrect endpoints, please open an issue in the monorepo.

Used By

This SDK is used in production by:

License

MIT