The official Node.js SDK for the Paystack API: fully typed, dual ESM/CJS, zero dependencies.
- Node.js 18 or later - the SDK uses the native
fetchAPI available since Node 18 - No additional runtime dependencies
npm install @paystack/paystack-sdk
# or
pnpm add @paystack/paystack-sdkimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const result = await paystack.transaction.initialize({
amount: 100_000, // kobo
email: "customer@example.com",
});
console.log(result.data.authorization_url);import { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY });
const result = await paystack.transaction.initialize({
amount: 100_000,
email: "customer@example.com",
});
console.log(result.data.authorization_url);// TypeScript with "module": "CommonJS" - tsc compiles import to require()
import { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const result = await paystack.transaction.initialize({
amount: 100_000,
email: "customer@example.com",
});
console.log(result.data.authorization_url);const { Paystack } = require("@paystack/paystack-sdk");
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY });
paystack.transaction
.initialize({ amount: 100_000, email: "customer@example.com" })
.then((result) => console.log(result.data.authorization_url));Pass options to the Paystack constructor:
const paystack = new Paystack({
secretKey: "sk_live_xxxxxxxxxxxx", // required
});| Option | Type | Required | Default |
|---|---|---|---|
secretKey |
string |
✅ | N/A |
Every method returns Promise<ApiResponse<T>>, mirroring the Paystack API envelope:
interface ApiResponse<T> {
status: boolean;
message: string;
data: T; // fully typed per endpoint
}The data field is typed to the exact response shape for each endpoint:
const { data } = await paystack.transaction.initialize({ amount: 100_000, email: "..." });
// ^? TransactionInitializeData - { authorization_url, access_code, reference }Import model types directly when you need them explicitly:
import type { TransactionInitializeBody, TransactionInitializeData } from "@paystack/paystack-sdk/models";List and filter endpoints accept a strongly-typed query object instead of a generic record:
import type { TransactionListQuery } from "@paystack/paystack-sdk/models";
const query: TransactionListQuery = {
per_page: 20,
page: 1,
status: "success", // "success" | "failed" | "abandoned" | "reversed"
from: "2024-01-01",
to: "2024-12-31",
};
const transactions = await paystack.transaction.list(query);Failed API calls throw an ApiError with the HTTP status, status text, and the parsed response body:
import { Paystack, ApiError } from "@paystack/paystack-sdk";
try {
const result = await paystack.transaction.initialize({
amount: 100_000,
email: "customer@example.com",
});
} catch (err) {
if (err instanceof ApiError) {
console.error(err.status); // HTTP status code, e.g. 400
console.error(err.statusText); // e.g. "Bad Request"
console.error(err.payload); // parsed JSON response body
}
}Requests that exceed the SDK timeout throw a native DOMException with name: "AbortError".
The SDK exposes one property per API resource on the Paystack instance.
| Resource | Property | Description | Methods |
|---|---|---|---|
| TransactionApi | paystack.transaction |
A collection of endpoints for managing payments | 9 |
| ChargeApi | paystack.charge |
A collection of endpoints for configuring and managing the payment channels when initiating a payment | 7 |
| BulkChargeApi | paystack.bulkCharge |
A collection of endpoints for creating and managing multiple recurring payments | 6 |
| SubaccountApi | paystack.subaccount |
A collection of endpoints for creating and managing accounts for sharing a transaction with | 4 |
| SplitApi | paystack.split |
A collection of endpoints for spliting a transaction and managing the splits | 6 |
| TerminalApi | paystack.terminal |
A collection of endpoints for building delightful in-person payment experiences | 8 |
| VirtualTerminalApi | paystack.virtualTerminal |
A collection of endpoints for building in-person payments without a physical terminal | 9 |
| CustomerApi | paystack.customer |
A collection of endpoints for creating and managing customers on an integration | 12 |
| DirectDebitApi | paystack.directDebit |
A collection of endpoints for managing Direct Debit | 2 |
| DedicatedVirtualAccountApi | paystack.dedicatedVirtualAccount |
A collection of endpoints for creating and managing payment accounts for customers | 9 |
| ApplePayApi | paystack.applePay |
A collection of endpoints for managing application's top-level domain or subdomain accepting payment via Apple Pay | 3 |
| PlanApi | paystack.plan |
A collection of endpoints for creating and managing recurring payment configuration | 4 |
| SubscriptionApi | paystack.subscription |
A collection of endpoints for creating and managing recurring payments | 7 |
| TransferRecipientApi | paystack.transferRecipient |
A collection of endpoints for creating and managing beneficiaries that you send money to | 6 |
| TransferApi | paystack.transfer |
A collection of endpoints for automating sending money to beneficiaries | 11 |
| BalanceApi | paystack.balance |
A collection of endpoints gaining insights into the amount on an integration | 2 |
| PaymentRequestApi | paystack.paymentRequest |
A collection of endpoints for managing invoices for the payment of goods and services | 9 |
| ProductApi | paystack.product |
A collection of endpoints for creating and managing inventories | 5 |
| StorefrontApi | paystack.storefront |
A collection of endpoints for creating and managing storefronts | 11 |
| OrderApi | paystack.order |
A collection of endpoints for creating and managing orders | 5 |
| PageApi | paystack.page |
A collection of endpoints for creating and managing links for the collection of payment for products | 6 |
| SettlementApi | paystack.settlement |
A collection of endpoints for gaining insights into payouts | 2 |
| IntegrationApi | paystack.integration |
A collection of endpoints for managing some settings on an integration | 2 |
| RefundApi | paystack.refund |
A collection of endpoints for creating and managing transaction reimbursement | 4 |
| DisputeApi | paystack.dispute |
A collection of endpoints for managing transactions complaint made by customers | 8 |
| BankApi | paystack.bank |
A collection of endpoints for managing bank details | 3 |
| MiscellaneousApi | paystack.miscellaneous |
A collection of endpoints that provides utility functions | 3 |
Detailed method signatures, parameters, and response types for each resource are documented in docs/.
⚠️ This SDK is auto-generated from the Paystack OpenAPI specification. Do not edit files insrc/directly - they will be overwritten on the next generation run.
To propose a change to an API method, request body, response type, or query parameter, open an issue or pull request against the Paystack OpenAPI specification.
Bug reports and documentation improvements for this SDK are welcome via GitHub Issues.
MIT © Paystack