> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payaza.africa/llms.txt
> Use this file to discover all available pages before exploring further.

# Node.js SDK

> Call the Payaza API from your Node.js or TypeScript server: collect payments, send transfers, manage accounts and verify webhooks.

`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.

> [!WARNING]
>
> 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](https://docs.payaza.africa/api-reference/libraries/websdk.md).

## Requirements

* Node.js 18 or later
* A Payaza business account with API keys. See [Authentication](https://docs.payaza.africa/guides/authentication.md).

## Installation

```bash npm theme={null}
npm install payaza-node-sdk
```

```bash yarn theme={null}
yarn add payaza-node-sdk
```

```bash pnpm theme={null}
pnpm add payaza-node-sdk
```

## Get your API key

**1. Open the dashboard**

Log in at [business.payaza.africa](https://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**

```bash .env theme={null}
PAYAZA_PUBLIC_KEY=your_test_public_key
PAYAZA_WEBHOOK_SECRET=your_webhook_secret
```

## Initialize the client

```ts ESM / TypeScript theme={null}
import { Payaza } from "payaza-node-sdk";

const payaza = new Payaza({
  publicKey: process.env.PAYAZA_PUBLIC_KEY!,
  environment: "test", // "test" while you build, "live" when you go live
});

const { data: accounts } = await payaza.account.view();
console.log(accounts);
```

```js CommonJS theme={null}
const { Payaza } = require("payaza-node-sdk");

const payaza = new Payaza({
  publicKey: process.env.PAYAZA_PUBLIC_KEY,
  environment: "test",
});
```

### Client options

| Option | Type | Default | Description |
| - | - | - | - |
| `publicKey` | `string` | Required | Your raw Payaza public key, exactly as copied from the dashboard. Do not base64-encode it yourself. |
| `environment` | `"test" \| "live"` | `"test"` | Must match the mode of your key. Sent as the `X-TenantID` header. |
| `productId` | `string` | `"app"` | Sent as `X-ProductID` on the mobile money endpoints that need it. |
| `baseUrl` | `string` | `https://api.payaza.africa/live` | Override the API host, for example to point at a mock server in tests. |
| `timeoutMs` | `number` | `30000` | Per-request timeout in milliseconds. |

> [!NOTE]
>
> 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

```ts theme={null}
const reference = `ORD${Date.now()}`.slice(0, 15); // unique, 15 characters or fewer

const result = await payaza.cards.charge({
  service_payload: {
    first_name: "Ada",
    last_name: "Obi",
    email_address: "ada@example.com",
    phone_number: "+2348012345678",
    amount: 5000,
    transaction_reference: reference,
    currency: "NGN",
    description: "Order #1042",
    card: {
      cardNumber: "5111111111111118", // sandbox test card
      expiryMonth: "01",
      expiryYear: "39",
      securityCode: "100",
    },
    callback_url: "https://yourapp.com/payments/callback",
  },
});

if (result.do3dsAuth) {
  // The issuer wants 3-D Secure. Render result.threeDsHtml in the customer's browser.
} else if (result.paymentCompleted) {
  // Charged. Confirm with a webhook or getTransactionStatus before you fulfil.
}
```

Use the cards on the [test cards](https://docs.payaza.africa/guides/testcards.md) page while in test mode.

> [!WARNING]
>
> **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:
>
> ```ts theme={null}
> const status = await payaza.cards.getTransactionStatus(reference);
> console.log(status.data.transaction_status);
> ```

### Virtual accounts

```ts theme={null}
const account = await payaza.virtualAccounts.create({
  account_type: "Dynamic", // single use, amount locked, expires
  account_name: "Order 1042",
  bank_code: "140",
  account_reference: "ord1042va",
  customer_first_name: "Ada",
  customer_last_name: "Obi",
  customer_email: "ada@example.com",
  transaction_amount: "5000",
  expires_in_minutes: "30",
});

console.log(account.data.account_number); // show this to your customer

// Test mode only: simulate the customer's bank transfer
await payaza.virtualAccounts.fundTestAccount({
  account_name: account.data.account_name,
  account_number: account.data.account_number,
  initiation_transaction_reference: "ord1042va",
  transaction_amount: "5000",
  currency: "NGN",
  source_account_number: "0123456789",
  source_account_name: "Ada Obi",
  source_bank_name: "Test Bank",
});
```

Static (reusable) accounts use `account_type: "Static"` and need `bvn` and `bvn_validated`. See [Virtual accounts](https://docs.payaza.africa/guides/virtual-accounts.md).

### Mobile money

Mobile money, XOF and ZAR collections live under `payaza.mobileMoneyCollections`: `processCollection()`, `processOtp()`, `getTransactionStatus()` and `fundTestAccount()`. See [Mobile money collections](https://docs.payaza.africa/guides/momo-collections.md) for the fields per country.

## Send money

```ts theme={null}
// 1. Resolve the beneficiary's name first
const enquiry = await payaza.account.nameEnquiry({
  service_payload: { currency: "NGN", bank_code: "000013", account_number: "9207067319" },
});

// 2. Send the transfer
await payaza.transfers.initiate({
  transaction_type: "nuban", // NGN. Use "mobile_money" or a local rail for other currencies.
  service_payload: {
    payout_amount: 100,
    transaction_pin: Number(process.env.PAYAZA_TRANSACTION_PIN),
    account_reference: "1010000009", // from payaza.account.view()
    currency: "NGN",
    payout_beneficiaries: [
      {
        credit_amount: 100,
        account_number: "9207067319",
        account_name: enquiry.response_content.account_name,
        bank_code: "000013",
        narration: "Invoice 482",
        transaction_reference: "TRF20261116001", // unique, at least 10 characters
        sender: {
          sender_name: "Your Business",
          sender_phone_number: "08012345678",
          sender_address: "12 Allen Avenue, Ikeja",
        },
      },
    ],
  },
});

// 3. Check how it landed
const status = await payaza.transfers.getStatus("TRF20261116001");
```

The sum of every `credit_amount` must equal `payout_amount`, and each `transaction_reference` must be unique. See [Transfers](https://docs.payaza.africa/guides/transfers.md) 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.

```ts theme={null}
import express from "express";
import { verifyWebhookSignature } from "payaza-node-sdk";

const app = express();

app.post("/webhooks/payaza", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.header("x-payaza-signature") ?? "";

  if (!verifyWebhookSignature(req.body, signature, process.env.PAYAZA_WEBHOOK_SECRET!)) {
    return res.status(401).send("Invalid signature");
  }

  const event = JSON.parse(req.body.toString("utf-8"));
  // Payaza can send the same event more than once. Use the transaction reference
  // as an idempotency key so you only fulfil once.
  res.sendStatus(200);
});
```

Set your test and live webhook URLs under **Settings > Developers > Webhooks**. See [Webhooks](https://docs.payaza.africa/guides/webhooks.md).

## Handle errors

Every failure (an API error, a network error or a timeout) throws `PayazaError`.

```ts theme={null}
import { PayazaError } from "payaza-node-sdk";

try {
  await payaza.transfers.initiate({ /* ... */ });
} catch (error) {
  if (error instanceof PayazaError) {
    console.error(error.message);  // message from the API or the SDK
    console.error(error.status);   // HTTP status, when the API answered
    console.error(error.response); // full response body, for logs
  }
  throw error;
}
```

`status` is empty for network errors and timeouts. Treat those as **unknown**, not failed, and check the transaction status before retrying. See [Errors](https://docs.payaza.africa/guides/errors.md) for common causes.

## Resources

Every resource follows the same `payaza.<resource>.<method>()` shape.

| Resource | Methods |
| - | - |
| `account` | `view`, `getTransactionStatus`, `getBankCodes`, `nameEnquiry` |
| `transfers` | `initiate`, `getStatus` |
| `cards` | `charge`, `getTransactionStatus`, `getRefundStatus` |
| `virtualAccounts` | `create`, `getStatus`, `getTransactionStatus`, `fundTestAccount` |
| `mobileMoneyCollections` | `processCollection`, `processOtp`, `getTransactionStatus`, `fundTestAccount` |
| `authCaptureVoid` | `authorize`, `capture`, `void`, `get`, `list` |
| `refunds` | `initiate`, `history` |
| `chargebacks` | `list`, `acceptOrReject`, `history` |
| `subAccounts` | `create`, `get` |
| `eurAccounts` | `requestUser`, `requestCorporate`, `listRequests`, `getRequest`, `acceptableIds`, `list` |
| `branches` | `list` |
| `splitSettlements` | `create`, `list`, `update`, `delete` |
| `subscriptionPlans` | `create`, `list`, `get`, `update` |
| `subscriptions` | `create`, `get`, `list`, `chargeNow`, `createCustomCharge`, `cancel`, `pause`, `resume`, `changePlan`, `upcomingCharges`, `chargeHistory`, `eventHistory`, `listInvoices`, `getInvoice` |

Request and response types are exported from the package root:

```ts theme={null}
import type { InitiateTransferRequest, CardChargeResponse } from "payaza-node-sdk";
```

For the fields of each endpoint, see the [API reference](https://docs.payaza.africa/api-reference/introduction).

## Build faster with AI

Connect the [Payaza MCP server](https://docs.payaza.africa/ai/mcp.md) 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

> [card] [GitHub](https://github.com/78-Financials/payaza-node-sdk)
>
> Source code, changelog and issues.

> [card] [Discord](https://discord.gg/hayas4mVx)
>
> Ask the Payaza developer community.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.