Node.js SDK (@watenga/node)

The official Node.js library for the Watenga API. Handles authentication, automatic retries, and typed error parsing so you can focus on your product instead of HTTP plumbing.

Installation

bash

npm install @watenga/node
# or
yarn add @watenga/node
# or
pnpm add @watenga/node

Requires Node.js 16 or higher. Works with both CommonJS and ESM. Full TypeScript support is built in — no separate @types package needed.

Initialisation

Create a client with your secret key. Use sandbox keys (sk_test_) during development and live keys (sk_live_) only after KYC approval.

typescript

import Watenga from '@watenga/node';
// or: const { Watenga } = require('@watenga/node');

const watenga = new Watenga('sk_test_YOUR_KEY', {
  // Optional configuration:
  baseUrl: 'https://api.watenga.africa', // default — change for self-hosted
  timeout: 30000, // ms, default 30000
  maxRetries: 2,  // auto-retry on 5xx, default 2
});

Available resources

Resource	Purpose
`watenga.checkout`	Create payment sessions
`watenga.transactions`	List, retrieve, refund
`watenga.paymentLinks`	Create and manage payment links
`watenga.payouts`	Request withdrawals
`watenga.account`	Balance and profile
`Watenga.Webhooks`	Static class for webhook verification

typescript

// Create a checkout session
const checkout = await watenga.checkout.create({
  amount: 25.0,
  currency: 'USD',
  merchantTransactionId: 'ORD-1001',
  returnUrl: 'https://yoursite.com/thank-you',
  notificationUrl: 'https://yoursite.com/webhooks/watenga',
});

// List and retrieve transactions
const { data, hasMore, nextCursor } = await watenga.transactions.list({ limit: 20 });
const txn = await watenga.transactions.retrieve('txn_...');

// Refund a transaction (full or partial)
await watenga.transactions.refund('txn_...', { amount: 10.0, reason: 'customer request' });

// Payment links
const link = await watenga.paymentLinks.create({ title: 'Donation', amount: 5.0, currency: 'USD' });

// Request a payout
await watenga.payouts.request({ amount: 100.0, currency: 'USD', method: 'bank_transfer' });

// Account balance and profile
const balance = await watenga.account.balance();

Error handling

typescript

try {
  const checkout = await watenga.checkout.create({ /* ... */ });
} catch (err) {
  if (err.code === 'KYC_REQUIRED') {
    // Handle KYC not approved
  } else if (err.code === 'DUPLICATE_REQUEST') {
    // Handle duplicate merchantTransactionId
  } else {
    // Unexpected error
    console.error(err.message, err.statusCode);
  }
}

All errors thrown by the SDK are WatengaError instances with:

err.message — human-readable description
err.code — machine-readable error code (see the Errors reference)
err.statusCode — HTTP status code
err.raw — the full raw API response

TypeScript types

Every request and response shape is exported for use in your own code.

typescript

import type {
  CreateCheckoutParams,
  CheckoutResponse,
  Transaction,
  PaymentLink,
  AccountBalance,
  WatengaError,
} from '@watenga/node';

Webhook verification

Verify every inbound webhook with the raw request body before acting on it. Never trust an unverified payload.

typescript

import { Webhooks } from '@watenga/node';

// In your Express/Hono/Fastify webhook handler.
// Watenga signs every delivery with the 'Watenga-Signature' header
// (format: t=<unix>,v1=<hmac-sha256-hex>). constructEvent verifies it for you.
const event = Webhooks.constructEvent(
  req.rawBody,                       // must be the raw string — not parsed JSON
  req.headers['watenga-signature'],
  process.env.WATENGA_WEBHOOK_SECRET,
);

// event is the verified envelope: { id, object: 'event', type, created, data }
if (event.type === 'payment.capture.completed') {
  // fulfil the order — event.data holds the transaction object
}

Versioning

The SDK version is independent of the API version. SDK 1.x supports API version 2026-01-01. See the package on npm.