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.
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
Virtual accounts
account_type: "Static" and need bvn and bvn_validated. See Virtual accounts.
Mobile money
Mobile money, XOF and ZAR collections live underpayaza.mobileMoneyCollections: processCollection(), processOtp(), getTransactionStatus() and fundTestAccount(). See Mobile money collections for the fields per country.
Send money
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 thex-payaza-signature header. Verify it against the raw body, before you parse it.
Handle errors
Every failure (an API error, a network error or a timeout) throwsPayazaError.
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 samepayaza.<resource>.<method>() shape.
Request and response types are exported from the package root:
Build faster with AI
Connect the Payaza MCP server to Claude, Cursor or VS Code so your assistant can read these docs while it writespayaza-node-sdk code for you.
Source and support
GitHub
Source code, changelog and issues.
Discord
Ask the Payaza developer community.