@alexasomba/paystack-node

TypeScript-first Paystack API client for Node.js, generated from the official Paystack OpenAPI spec.

Features

• Spec-driven Accuracy: Generated directly from the Paystack OpenAPI specification.
• 100% Type-safe: Full TypeScript support with generated types for every endpoint, request, and response.
• Smart Retries: Automatic retries for transient failures with exponential backoff and jitter.
• Retry-After Compliance: Automatically respects Paystack Retry-After headers on rate limit responses.
• Sophisticated Idempotency: Built-in support for manual, static, or automatic UUID-based idempotency keys on POST requests.
• Detailed Error Handling: PaystackError preserves Paystack code, type, meta, request ID, HTTP status, and the raw response body.
• Webhook Verification: Timing-safe webhook signature verification helper included.

Install

pnpm add @alexasomba/paystack-node

Agent Skills

This package ships TanStack Intent skills for agent-assisted Paystack integration:

npx @tanstack/intent@latest list
npx @tanstack/intent@latest install --map
npx @tanstack/intent@latest load @alexasomba/paystack-node#paystack-node-api-operations

Useful skills include paystack-node-client-setup, paystack-node-api-operations, paystack-node-operation-discovery, paystack-node-typed-payloads, paystack-node-responses-errors, paystack-node-retries-idempotency, paystack-node-transport-testing, and paystack-node-webhooks.

Authenticate requests with your Paystack secret key:

process.env.PAYSTACK_SECRET_KEY="sk_test_...";

Quick Start

import{createPaystack,assertOk}from"@alexasomba/paystack-node";constpaystack=createPaystack({secretKey: process.env.PAYSTACK_SECRET_KEY!,idempotencyKey: "auto",});constresult=awaitpaystack.transaction_initialize({body: {email: "customer@example.com",amount: 5000,},});constdata=assertOk(result);console.log(data.authorization_url);

assertOk returns the successful Paystack payload and throws a structured PaystackError for non-2xx responses or { status: false } envelopes.

API Basics

• Base URL: https://api.paystack.co
• HTTPS is required for all requests.
• Requests and responses are JSON-based.
• Most successful responses follow the status, message, data, and optional meta envelope described in Paystack-API/0a-Introduction.md.
• Amounts are usually sent in currency subunits such as kobo, pesewas, or cents. Check the module docs for currency-specific rules.

Authentication & Environments

• Server-side SDKs should use your secret key (sk_test_* or sk_live_*).
• Browser SDKs should use only your public key (pk_test_* or pk_live_*).
• Send server-side API credentials as Authorization: Bearer YOUR_SECRET_KEY.
• Test and live modes use different keys and isolated environments.
• Rotate keys if they are exposed, and never commit secret keys to source control.
• If you enable IP whitelisting in Paystack, requests from non-whitelisted IPs will be blocked.

Advanced Configuration

The createPaystack helper accepts PaystackClientOptions:

constpaystack=createPaystack({secretKey: "sk_...",timeoutMs: 30_000,retry: {retries: 3,minDelayMs: 500,retryOnStatuses: [429,500,503],},idempotencyKey: "auto",headers: {"X-My-App": "v1.0.0",},});

Stable Type Exports

This SDK exports stable grouped client slices and curated request/query/response aliases so downstream integrations do not need to reconstruct types from ReturnType<typeof createPaystack>, paths, or operations.

import{createPaystack,typePaystack,typePaystackTransactionClient,typePaystackSubscriptionClient,typeTransactionInitializePayload,typeTransactionChargeAuthorizationPayload,typeSubscriptionCreatePayload,typeSubscriptionListQueryParams,typeRefundCreatePayload,}from"@alexasomba/paystack-node";constpaystack: Paystack=createPaystack({secretKey: process.env.PAYSTACK_SECRET_KEY!,});consttransactionClient: PaystackTransactionClient=paystack.transaction;constsubscriptionClient: PaystackSubscriptionClient=paystack.subscription;consttx: TransactionInitializePayload={email: "customer@example.com",amount: 5000,};constchargeAuthorization: TransactionChargeAuthorizationPayload={email: "customer@example.com",amount: 2500,authorization_code: "AUTH_123",};constsubscriptionCreate: SubscriptionCreatePayload={customer: "CUS_123",plan: "PLN_123",};constsubscriptionList: SubscriptionListQueryParams={customer: 123,};constrefundCreate: RefundCreatePayload={transaction: "TRX_123",amount: 1000,};

Notable aliases include transaction initialize / charge authorization / verify; subscription create / list / disable / enable / fetch / manage link / manage email; customer fetch / create / update; plan list / create / update / fetch; product list / create / update / fetch; dispute list / fetch; refund create / fetch; payment request create / fetch; terminal send-event; and verification helpers for account resolution, account validation, and card BIN lookup.

Client slices include PaystackTransactionClient, PaystackCustomerClient, PaystackSubscriptionClient, PaystackPlanClient, PaystackProductClient, PaystackDisputeClient, and PaystackRefundClient.

Grouped methods reflect supported generated OpenAPI operations. Unsupported helpers such as subscription.update are intentionally not part of the public SDK surface.

Webhooks

Use the webhook helper when validating server-to-server events from Paystack. Pass the raw request body, not a parsed JSON object.

import{verifyPaystackWebhookSignature}from"@alexasomba/paystack-node/webhooks";constisValid=verifyPaystackWebhookSignature({rawBody: req.body,signature: req.headers["x-paystack-signature"],secret: process.env.PAYSTACK_SECRET_KEY!,});

Handling Pagination

List endpoints expose pagination controls through query params like perPage, page, next, and previous. Response headers are still available when you need manual pagination control.

Pagination

• Paystack supports both offset pagination and cursor pagination.
• Offset pagination uses page and perPage.
• Cursor pagination uses use_cursor=true plus next or previous cursors returned in meta.
• Cursor pagination is especially useful for large or frequently changing datasets.
• The exact meta shape varies by endpoint and pagination mode.

constresult=awaitpaystack.customer_list({query: {perPage: 20}});constcustomers=assertOk(result);consttotal=result.response.headers.get("x-total-count");

Error Handling

import{toPaystackApiError}from"@alexasomba/paystack-node";constresult=awaitpaystack.transaction_initialize({/* ... */});consterror=toPaystackApiError(result);if(error){console.error(`Status ${error.status}: ${error.message}`);console.error(`Paystack code: ${error.code}`);console.error(`Paystack type: ${error.type}`);console.error(`Paystack Request ID: ${error.requestId}`);console.error(error.raw);}

Use error.code and error.type for branching on validation, processor, and API failures. The requestId is useful when correlating logs or escalating an issue with Paystack support, while error.raw / error.body keeps the original response envelope available for diagnostics.

Errors

• Paystack uses conventional HTTP status codes such as 200, 201, 400, 401, 404, and 5xx.
• Error responses typically include status, message, type, code, and optional diagnostic meta information.
• Error types described in Paystack-API/0d-Errors.md include api_error, validation_error, and processor_error.
• For charge and verify flows, always inspect the returned response body and status fields, not just the HTTP code.

Coverage

This SDK is generated from the SDK spec in this monorepo and currently tracks the full set of generated typed operations for the Paystack-API-aligned contract.

Modules

For this SDK, these schema families are exposed through generated TypeScript types in src/openapi-types.ts and operation helpers in src/operations.ts.

Module	Schema / model family
Transactions	Transaction*
Verify Payments (Transaction verification)	VerifyResponse / TransactionFetchResponse
Charges	Charge*
Bulk Charges	BulkCharge*
Subaccounts	Subaccount*
Transaction Splits	Split*
Terminal	Terminal*
Virtual Terminal	VirtualTerminal*
Customers	Customer*
Direct Debit	DirectDebit*
Dedicated Virtual Accounts	DedicatedNuban* / DedicatedVirtualAccount*
Apple Pay	ApplePay*
Plans	Plan*
Subscriptions	Subscription*
Transfer Recipients	TransferRecipient*
Transfers	Transfer*
Transfers Control (OTP settings; under Transfers)	TransferEnable* / TransferDisable* / TransferFinalize*
Balance	Balance*
Payment Requests (Invoices)	PaymentRequest*
Verification (Resolve Account / Validate Account / Resolve Card BIN)	Verification*
Products	Product*
Storefronts	Storefront*
Orders	Order*
Payment Pages	Page*
Settlements	Settlement*
Integration	Integration*
Control Panel (Payment session timeout; under Integration)	ControlPanel*
Refunds	Refund*
Disputes	Dispute*
Banks	Bank*
Miscellaneous	Miscellaneous* / Currency

Module Examples

These are intentionally short examples. Use them as entry points, then expand the request bodies with the typed fields exposed by your editor and src/openapi-types.ts.

Transactions

consttx=awaitpaystack.transaction_initialize({body: {email: "customer@example.com",amount: 5000},});

Verify Payments (Transaction verification)

constverified=awaitpaystack.transaction_verify({params: {path: {reference: "ref_123"}},});

Charges

awaitpaystack.charge_create({body: {email: "customer@example.com",amount: 5000,bank: {code: "057",account_number: "0001234567"},},});

Bulk Charges

awaitpaystack.bulkCharge_initiate({body: [{authorization: "AUTH_xxx",amount: 5000,reference: "bulk-ref-1"}],});

Subaccounts

awaitpaystack.subaccount_create({body: {business_name: "Acme Stores",settlement_bank: "057",account_number: "0001234567",percentage_charge: 10,},});

Transaction Splits

awaitpaystack.split_create({body: {name: "Main split",type: "percentage",currency: "NGN",subaccounts: []},});

Terminal

constterminals=awaitpaystack.terminal_list();

Virtual Terminal

awaitpaystack.virtualTerminal_create({body: {name: "Web checkout terminal"},});

Customers

awaitpaystack.customer_create({body: {email: "customer@example.com",first_name: "Ada",last_name: "Lovelace"},});

Direct Debit

awaitpaystack.directdebit_initialize({body: {email: "customer@example.com",amount: 5000,bank_code: "057"},});

Dedicated Virtual Accounts

awaitpaystack.dedicatedAccount_assign({body: {customer: 12345,preferred_bank: "wema-bank"},});

Apple Pay

awaitpaystack.applePay_registerDomain({body: {domainName: "example.com"},});

Plans

awaitpaystack.plan_create({body: {name: "Starter",amount: 500000,interval: "monthly"},});

Subscriptions

awaitpaystack.subscription_create({body: {customer: "CUS_xxx",plan: "PLN_xxx"},});

Transfer Recipients

awaitpaystack.transferrecipient_create({body: {type: "nuban",name: "Ada Lovelace",account_number: "0001234567",bank_code: "057",currency: "NGN",},});

Transfers

awaitpaystack.transfer_create({body: {source: "balance",amount: 5000,recipient: "RCP_xxx",reason: "Vendor payout"},});

Transfers Control (OTP settings; under Transfers)

awaitpaystack.transfer_enableOtp();

Balance

constbalance=awaitpaystack.balance_fetch();

Payment Requests (Invoices)

awaitpaystack.paymentRequest_create({body: {customer: "CUS_xxx",amount: 5000,description: "Consulting invoice"},});

Verification (Resolve Account / Validate Account / Resolve Card BIN)

awaitpaystack.bank_resolveAccountNumber({params: {query: {account_number: "0001234567",bank_code: "057"}},});

Products

awaitpaystack.product_create({body: {name: "T-shirt",description: "Cotton tee",price: 5000,currency: "NGN"},});

Storefronts

conststorefronts=awaitpaystack.storefront_list();

Orders

awaitpaystack.order_create({body: {customer: "CUS_xxx",items: []},});

Payment Pages

awaitpaystack.page_create({body: {name: "Event Ticket",amount: 5000,description: "Landing page for ticket sales"},});

Settlements

constsettlements=awaitpaystack.settlement_list();

Integration

consttimeout=awaitpaystack.integration_fetchPaymentSessionTimeout();

Control Panel (Payment session timeout; under Integration)

awaitpaystack.integration_updatePaymentSessionTimeout({body: {timeout: 20},});

Refunds

awaitpaystack.refund_create({body: {transaction: 123456789,amount: 5000},});

Disputes

constdisputes=awaitpaystack.dispute_list();

Banks

constbanks=awaitpaystack.bank_list({params: {query: {country: "nigeria"}}});

Miscellaneous

constcountries=awaitpaystack.miscellaneous_listCountries();

Related SDKs

• @alexasomba/paystack-browser - Optimized for browser fetches.
• @alexasomba/paystack-axios - For projects using Axios.

Used By

• Better Auth Paystack Plugin: A comprehensive Paystack plugin for Better Auth.

Source

• Monorepo source: alexasomba/paystack-openapi
• Standalone SDK repo: https://github.com/alexasomba/paystack-node

License

MIT