@enviabledev/paystack-api

A modern, fully-typed, and efficient Node.js library for interacting with the Paystack API. Built with TypeScript, it provides a clean, class-based interface to all Paystack resources, complete with robust error handling and helper utilities. This library is developed and maintained by Enviable Transport Services Software Developemnt Team.

Table of Contents

- Features
- Installation
- Getting Started
- API Reference
- Bulk Charge
- Charge
- Control Panel
- Customer
- Dedicated NUBAN
- Miscellaneous
- Payment Page
- Payment Request
- Plan
- Refund
- Settlement
- Subaccount
- Subscription
- Transaction
- Transfer
- Transfer Control
- Transfer Recipient
- Verification
- Helpers
- Handling Webhooks
- Fee Calculator
- Error Handling
- Contributing
- License

Features

- Complete API Coverage: All Paystack API endpoints are mapped to intuitive methods
- Fully-Typed: Written in TypeScript to provide static typing and autocompletion for all payloads and responses
- Modern Syntax: Uses async/await for clean, readable, and non-blocking asynchronous code
- Robust Error Handling: Provides custom error classes to easily distinguish between API errors, network issues, and other exceptions
- Helpful Utilities: Includes helpers for webhook signature verification and fee calculation

Installation

``bash
npm install @enviabledev/paystack-api
`

Getting Started

To get started, initialize the client with your Paystack secret key.

`javascript
import paystack from '@enviabledev/paystack-api';

// Initialize the client with your secret key
const paystackClient = paystack('YOUR_PAYSTACK_SECRET_KEY');

// Example: Verify a transaction
async function verifyTransaction(reference) {
try {
const response = await paystackClient.transaction.verify(reference);
console.log(response.data.status); // e.g., 'success'
console.log(response.data.customer.email);
} catch (error) {
console.error(error);
}
}

verifyTransaction('your_transaction_reference');
`

API Reference

This library provides access to all Paystack API resources through the paystackClient object.

$3

Handles batch processing of charges.

- paystackClient.bulkCharge.create(payload): Initiates a new bulk charge
- Payload: CreateBulkChargePayload - An object with a charges property, which is an array of objects containing authorization (string), amount (number), and optional reference (string)

- paystackClient.bulkCharge.list(params): Lists bulk charge batches
- Params: ListBulkChargesParams (optional) for pagination (perPage, page) and filtering (status, from, to)

- paystackClient.bulkCharge.get(id): Retrieves a single bulk charge batch
- ID: The batch ID or code (string)

- paystackClient.bulkCharge.getCharges(id, params): Retrieves all charges within a batch
- ID: The batch ID or code (string)
- Params: ListBulkChargeChargesParams (optional) for pagination and filtering

- paystackClient.bulkCharge.pause(batchCode): Pauses a running bulk charge batch

- paystackClient.bulkCharge.resume(batchCode): Resumes a paused bulk charge batch

$3

Handles tokenization and charging of payment instruments.

- paystackClient.charge.tokenize(payload): Creates a reusable token from card details
- Payload: TokenizePayload with email and a card object (number, cvv, expiry_month, expiry_year)

- paystackClient.charge.charge(payload): Initiates a new charge
- Payload: ChargePayload with email, amount, and payment details (e.g., authorization_code, pin, bank)

- paystackClient.charge.submitPin(payload): Submits a PIN to continue a charge
- Payload: SubmitPinPayload with pin and reference

- paystackClient.charge.submitOtp(payload): Submits an OTP to complete a charge
- Payload: SubmitOtpPayload with otp and reference

- paystackClient.charge.submitPhone(payload): Submits a phone number to continue a charge
- Payload: SubmitPhonePayload with phone and reference

- paystackClient.charge.submitBirthday(payload): Submits a birthday to continue a charge
- Payload: SubmitBirthdayPayload with birthday (YYYY-MM-DD) and reference

- paystackClient.charge.submitAddress(payload): Submits an address to continue a charge
- Payload: SubmitAddressPayload with reference, address, city, state, and zip_code

- paystackClient.charge.checkCharge(reference): Checks the status of a pending charge

$3

Manages integration settings.

- paystackClient.controlPanel.getSessionTimeout(): Gets the payment session timeout for your integration

- paystackClient.controlPanel.updateSessionTimeout(payload): Updates the payment session timeout
- Payload: UpdateSessionTimeoutPayload with timeout in seconds

$3

Manages customer information.

- paystackClient.customer.create(payload): Creates a new customer
- Payload: CreateCustomerPayload containing email, and optional first_name, last_name, phone, metadata

- paystackClient.customer.list(params): Lists customers
- Params: ListCustomersParams (optional) for pagination and filtering

- paystackClient.customer.get(id): Retrieves a customer's details
- ID: The customer's ID or email (string)

- paystackClient.customer.update(id, payload): Updates a customer's details
- Payload: UpdateCustomerPayload

- paystackClient.customer.validate(id, payload): Validates a customer's identity
- Payload: ValidateCustomerPayload

- paystackClient.customer.setRiskAction(payload): Whitelists or blacklists a customer
- Payload: SetRiskActionPayload with customer (code or email) and risk_action ('allow' or 'deny')

- paystackClient.customer.deactivateAuthorization(payload): Deactivates a customer's authorization
- Payload: DeactivateAuthorizationPayload with authorization_code

$3

Manages dedicated virtual bank accounts.

- paystackClient.nuban.create(payload): Creates a dedicated virtual account
- Payload: CreateNubanPayload for a new or existing customer

- paystackClient.nuban.list(params): Lists dedicated virtual accounts
- Params: ListNubansParams (optional) for filtering

- paystackClient.nuban.get(id): Retrieves a single dedicated virtual account
- ID: The dedicated account ID (number)

- paystackClient.nuban.requery(params): Requeries a dedicated virtual account to check for transfers
- Params: RequeryNubanParams with account_number, provider_slug, and date

- paystackClient.nuban.deactivate(id): Deactivates a dedicated virtual account

- paystackClient.nuban.removeSplit(payload): Removes a split configuration from a dedicated account
- Payload: RemoveNubanSplitPayload with account_number

- paystackClient.nuban.listAvailableProviders(): Gets a list of available providers for dedicated accounts

$3

Accesses miscellaneous data like banks and countries.

- paystackClient.misc.listBanks(params): Gets a list of all supported banks
- Params: ListBanksParams (optional) for filtering by country, currency, etc.

- paystackClient.misc.listCountries(): Gets a list of all supported countries

- paystackClient.misc.listStates(params): Gets a list of states for a country
- Params: ListStatesParams with country code

$3

Manages hosted payment pages.

- paystackClient.paymentPage.create(payload): Creates a new payment page
- Payload: CreatePaymentPagePayload with name and other optional fields

- paystackClient.paymentPage.list(params): Lists payment pages
- Params: ListPaymentPagesParams (optional) for pagination and date range filtering

- paystackClient.paymentPage.get(id): Retrieves a payment page
- ID: The page ID or slug (string)

- paystackClient.paymentPage.update(id, payload): Updates a payment page
- Payload: UpdatePaymentPagePayload

- paystackClient.paymentPage.checkSlugAvailability(slug): Checks if a URL slug is available

- paystackClient.paymentPage.addProducts(id, payload): Adds products to a payment page
- ID: The page ID (number)
- Payload: AddProductsToPaymentPagePayload with an array of product IDs

$3

Manages professional invoices.

- paystackClient.paymentRequest.create(payload): Creates a new payment request (invoice)
- Payload: CreatePaymentRequestPayload with customer, amount, and due_date

- paystackClient.paymentRequest.list(params): Lists payment requests
- Params: ListPaymentRequestsParams (optional) for filtering

- paystackClient.paymentRequest.get(id): Retrieves a payment request
- ID: The payment request ID or code (string)

- paystackClient.paymentRequest.verify(code): Verifies the payment status of a payment request

- paystackClient.paymentRequest.notify(id): Sends a notification reminder for a payment request

- paystackClient.paymentRequest.getTotals(): Gets total payment request volume and paid count

- paystackClient.paymentRequest.finalize(id): Finalizes a draft payment request

- paystackClient.paymentRequest.update(id, payload): Updates a payment request
- Payload: UpdatePaymentRequestPayload

- paystackClient.paymentRequest.archive(id): Archives a payment request

$3

Manages subscription plans.

- paystackClient.plan.create(payload): Creates a new subscription plan
- Payload: CreatePlanPayload with name, amount, and interval

- paystackClient.plan.list(params): Lists subscription plans
- Params: ListPlansParams (optional) for filtering

- paystackClient.plan.get(id): Retrieves a subscription plan
- ID: The plan ID or code (string)

- paystackClient.plan.update(id, payload): Updates a subscription plan
- Payload: UpdatePlanPayload

$3

Manages refunds for transactions.

- paystackClient.refund.create(payload): Initiates a refund for a transaction
- Payload: CreateRefundPayload with transaction reference and optional amount

- paystackClient.refund.list(params): Lists refunds
- Params: ListRefundsParams (optional) for filtering

- paystackClient.refund.get(id): Retrieves a single refund
- ID: The refund ID (number)

$3

Retrieves settlement information.

- paystackClient.settlement.list(params): Lists settlements made to your bank accounts
- Params: ListSettlementsParams (optional) for filtering

- paystackClient.settlement.getTransactions(id, params): Gets transactions associated with a settlement
- ID: The settlement ID (number)
- Params: ListSettlementTransactionsParams (optional)

$3

Manages subaccounts for split payments.

- paystackClient.subaccount.create(payload): Creates a new subaccount
- Payload: CreateSubaccountPayload with business_name, settlement_bank, account_number, and percentage_charge

- paystackClient.subaccount.list(params): Lists subaccounts
- Params: ListSubaccountsParams (optional)

- paystackClient.subaccount.get(id): Retrieves a subaccount
- ID: The subaccount ID or code (string)

- paystackClient.subaccount.update(id, payload): Updates a subaccount
- Payload: UpdateSubaccountPayload

$3

Manages customer subscriptions.

- paystackClient.subscription.create(payload): Creates a new subscription
- Payload: CreateSubscriptionPayload with customer and plan

- paystackClient.subscription.list(params): Lists subscriptions
- Params: ListSubscriptionsParams (optional) for filtering by customer or plan

- paystackClient.subscription.get(id): Retrieves a subscription
- ID: The subscription ID or code (string)

- paystackClient.subscription.enable(payload): Enables a subscription
- Payload: ToggleSubscriptionPayload with code and token

- paystackClient.subscription.disable(payload): Disables a subscription
- Payload: ToggleSubscriptionPayload with code and token

- paystackClient.subscription.generateManageLink(code): Generates a link to manage a subscription

- paystackClient.subscription.sendManageEmail(code): Sends a subscription management email

$3

Manages financial transactions.

- paystackClient.transaction.initialize(payload): Initializes a new transaction
- Payload: InitializeTransactionPayload with email and amount

- paystackClient.transaction.verify(reference): Verifies the status of a transaction

- paystackClient.transaction.list(params): Lists transactions
- Params: ListTransactionsParams (optional) for pagination and filtering

- paystackClient.transaction.get(id): Retrieves a transaction
- ID: The transaction ID (number)

- paystackClient.transaction.chargeAuthorization(payload): Charges a customer using a saved authorization
- Payload: ChargeAuthorizationPayload with email, amount, and authorization_code

- paystackClient.transaction.viewTimeline(id): Gets the timeline of a transaction
- ID: The transaction ID or reference (string)

- paystackClient.transaction.totals(params): Gets transaction totals
- Params: ListTransactionsParams (optional) for date range filtering

- paystackClient.transaction.export(params): Exports a list of transactions
- Params: ListTransactionsParams (optional) for filtering

$3

Manages money transfers to bank accounts.

- paystackClient.transfer.create(payload): Initiates a new transfer
- Payload: CreateTransferPayload with source, amount, and recipient

- paystackClient.transfer.list(params): Lists transfers
- Params: ListTransfersParams (optional)

- paystackClient.transfer.get(idOrCode): Retrieves a transfer

- paystackClient.transfer.finalize(payload): Finalizes a transfer that requires an OTP
- Payload: FinalizeTransferPayload with transfer_code and otp

- paystackClient.transfer.bulk(payload): Initiates a bulk transfer
- Payload: BulkTransferPayload

- paystackClient.transfer.verify(reference): Verifies the status of a transfer

$3

Manages transfer settings and balance.

- paystackClient.transferControl.checkBalance(): Checks the available balance on your integration

- paystackClient.transferControl.getBalanceLedger(): Gets the balance ledger for your integration

- paystackClient.transferControl.resendOtp(payload): Resends an OTP for a transfer
- Payload: ResendOtpPayload with transfer_code and reason

- paystackClient.transferControl.disableOtp(): Disables the OTP requirement for transfers

- paystackClient.transferControl.finalizeDisableOtp(payload): Finalizes the process of disabling OTP
- Payload: FinalizeDisableOtpPayload with otp

- paystackClient.transferControl.enableOtp(): Enables the OTP requirement for transfers

$3

Manages transfer recipients.

- paystackClient.transferRecipient.create(payload): Creates a new transfer recipient
- Payload: CreateTransferRecipientPayload with type and name

- paystackClient.transferRecipient.createBulk(payload): Creates multiple transfer recipients in bulk
- Payload: CreateBulkTransferRecipientsPayload

- paystackClient.transferRecipient.list(params): Lists transfer recipients
- Params: ListTransferRecipientsParams (optional)

- paystackClient.transferRecipient.get(idOrCode): Retrieves a transfer recipient

- paystackClient.transferRecipient.update(idOrCode, payload): Updates a transfer recipient
- Payload: UpdateTransferRecipientPayload

- paystackClient.transferRecipient.remove(idOrCode): Deletes a transfer recipient

$3

Verifies customer and payment details.

- paystackClient.verification.resolveAccount(payload): Resolves a bank account to get the account holder's name
- Payload: ResolveAccountPayload with account_number and bank_code

- paystackClient.verification.validateAccount(payload): Validates a bank account
- Payload: ValidateAccountPayload

- paystackClient.verification.resolveBin(bin): Gets information about a card's Bank Identification Number (BIN)
- BIN: The first 6 digits of the card number (string)

Helpers

$3

The library provides an Express middleware to securely handle incoming webhook events. It verifies the Paystack signature and emits an event.

`javascript
import express from 'express';
import paystack from '@enviabledev/paystack-api';

const app = express();
const paystackClient = paystack('YOUR_PAYSTACK_SECRET_KEY');

// Use the middleware to verify and parse webhooks
// IMPORTANT: This must be placed before any other body-parsing middleware like express.json()
app.post('/webhook', paystackClient.events.middleware);

// Listen for a specific event
paystackClient.events.on('charge.success', (data) => {
console.log('Charge successful!');
console.log(data); // The event data object
});

// Start your server
app.listen(3000, () => console.log('Server running on port 3000'));
`

$3

The FeeHelper class calculates the total amount to charge a customer to cover Paystack's processing fees.

`javascript
import paystack from '@enviabledev/paystack-api';

const FeeHelper = paystack.feeHelper; // Get the FeeHelper class

// Use default Paystack fees
const feeCalculator = new FeeHelper();

// The amount you want to receive in kobo
const desiredAmountKobo = 10000; // ₦100.00

// The amount you need to charge the customer
const amountToCharge = feeCalculator.addFeesTo(desiredAmountKobo);
console.log(amountToCharge); // e.g., 10152 (₦101.52)
`

Error Handling

The library throws custom errors to help you handle different failure scenarios gracefully:

- PaystackAPIError: Thrown for errors from the Paystack API (e.g., invalid input, authentication failure). Contains statusCode and responseData.
- NetworkError: Thrown for network-related issues (e.g., timeouts, no connection).
- PaystackError: A base class for all library errors.

`javascript
import paystack from '@enviabledev/paystack-api';
const { PaystackAPIError, NetworkError } = paystack.errors;

const paystackClient = paystack('YOUR_SECRET_KEY');

async function getCustomer() {
try {
const customer = await paystackClient.customer.get('non_existent_id');
} catch (error) {
if (error instanceof PaystackAPIError) {
console.error(API Error: ${error.message});
console.error(Status Code: ${error.statusCode});
if (error.statusCode === 404) {
console.log("This customer could not be found.");
}
} else if (error instanceof NetworkError) {
console.error(Network Error: ${error.message});
// You could implement retry logic here
} else {
console.error(An unexpected error occurred:, error);
}
}
}

getCustomer();
``

Contributing

This is a note to all team members, update the readme file when you make any changes to an endpoint or add a new endpoint

License

MIT