Skip to main content
payaza-node-sdk is the official server-side SDK for the Payaza API. It is written in TypeScript, ships its own types, and has no runtime dependencies.
This is a server-side SDK. Never use it in a browser or mobile app, because it needs your API key. To take payments in the browser, use the Web SDK.

Requirements

  • Node.js 18 or later
  • A Payaza business account with API keys. See Authentication.

Installation

Get your API key

1

Open the dashboard

Log in at business.payaza.africa and go to Settings > Developers.
2

Generate keys

Click Generate Keys. Turn on Test Mode for a sandbox key. Live keys are available after KYB approval.
3

Store it as an environment variable

.env

Initialize the client

Client options

The SDK handles two details that trip up most direct integrations. It base64-encodes your key and sends it as Authorization: Payaza <encoded-key>, and it keeps the fixed /live path in the base URL. The environment option, not the URL, decides whether you are in test or live mode.

Collect payments

Charge a card

Use the cards on the test cards page while in test mode.
A timeout is not a failure. If a charge times out or your server loses the reply, the customer may already have been debited. Check the status with the same reference before you retry, and never retry with a new reference:

Virtual accounts

Static (reusable) accounts use account_type: "Static" and need bvn and bvn_validated. See Virtual accounts.

Mobile money

Mobile money, XOF and ZAR collections live under payaza.mobileMoneyCollections: processCollection(), processOtp(), getTransactionStatus() and fundTestAccount(). See Mobile money collections for the fields per country.

Send money

The sum of every credit_amount must equal payout_amount, and each transaction_reference must be unique. See Transfers for every payout rail.

Verify webhooks

Payaza signs each webhook with HMAC-SHA512 over the raw body and sends it in the x-payaza-signature header. Verify it against the raw body, before you parse it.
Set your test and live webhook URLs under Settings > Developers > Webhooks. See Webhooks.

Handle errors

Every failure (an API error, a network error or a timeout) throws PayazaError.
status is empty for network errors and timeouts. Treat those as unknown, not failed, and check the transaction status before retrying. See Errors for common causes.

Resources

Every resource follows the same payaza.<resource>.<method>() shape. Request and response types are exported from the package root:
For the fields of each endpoint, see the API reference.

Build faster with AI

Connect the Payaza MCP server to Claude, Cursor or VS Code so your assistant can read these docs while it writes payaza-node-sdk code for you.

Source and support

GitHub

Source code, changelog and issues.

Discord

Ask the Payaza developer community.