RohoPay Node.js SDK

Official Node.js / TypeScript SDK for RohoPay — mobile-money (MTN, Airtel, M-Pesa) and card (Visa, Mastercard) payments across East Africa.

Install

npm install rohopay-sdk
# or
pnpm add rohopay-sdk

Quick start

import { RohoPay } from "rohopay-sdk";

const rohopay = new RohoPay({
  apiKey: process.env.ROHOPAY_API_KEY!,
  baseUrl: "https://api.rohopay.com", // optional, defaults to this (LIVE)
  // timeout: 30000,        // ms, optional
  // maxRetries: 3,         // optional
  // fetchImpl: customFetch // optional, for testing
});

// Collect mobile money
const txn = await rohopay.collect({
  phone: "256700123456",
  amount: 50000, // in UGX (smallest unit)
  currency: "UGX",
  description: "Order #1001",
  callback_url: "https://your-app.com/webhooks/rohopay",
  idempotency_key: crypto.randomUUID(), // optional; auto-generated if omitted
});
console.log(txn.internal_reference, txn.status);

// Card checkout (3D-Secure)
const card = await rohopay.checkout({
  amount: 75000,
  customer_name: "Jane Mukasa",
  customer_email: "[email protected]",
  return_url: "https://your-app.com/checkout/return",
  card_number: "4111111111111111",
  card_expiry: "10/26",
  card_cvv: "123",
});
// redirect the user to card.payment_url

Methods

| Method | Endpoint | |--------|----------| | collect(params) | POST /api/v1/collect | | disburse(params) (live mode only) | POST /api/v1/disburse | | checkout(params) | POST /api/v1/checkout | | getTransaction(reference) | GET /api/v1/transactions/:reference | | listTransactions(params?) | GET /api/v1/transactions | | listAll(params?) | async generator, auto-paginates listTransactions | | getBalance() | GET /api/v1/wallet/balance | | verifyWebhook(rawBody, sig, secret) | — | | constructEvent(rawBody, sig, secret, tolerance?) | — |

Exported enums & constants

• TransactionStatus — PENDING, SUCCESSFUL, FAILED
• PaymentMethod — MOBILE_MONEY, CARD
• TransactionType — COLLECTION, DISBURSEMENT
• Environment — TEST, LIVE
• CURRENCIES — Set of UGX, KES, TZS, NGN, GHS, USD, EUR
• LIVE_BASE_URL, SANDBOX_BASE_URL, WEBHOOK_SIGNATURE_HEADER

Errors

All errors extend RohoPayError and carry { message, httpStatus?, code?, requestId? }: AuthenticationError (401), InvalidRequestError (400/404/422), IdempotencyError (409), RateLimitError (429), APIError (>=500), APIConnectionError (network/timeout), SignatureVerificationError (webhooks).

Verify webhooks

import { RohoPay } from "rohopay-sdk";

const rohopay = new RohoPay({ apiKey: process.env.ROHOPAY_API_KEY! });
const rawBody = req.readBody(); // raw, unparsed string
const signature = req.headers["x-rohopay-signature"];

// Boolean check:
if (!rohopay.verifyWebhook(rawBody, signature, process.env.ROHOPAY_WEBHOOK_SECRET!)) {
  return res.status(401).send("invalid signature");
}

// Or parse + verify in one step (throws SignatureVerificationError):
const event = rohopay.constructEvent(rawBody, signature, process.env.ROHOPAY_WEBHOOK_SECRET!, 300);

The gateway signs outgoing webhooks automatically with the X-RohoPay-Signature header (sha256=<HMAC-SHA256 of raw body>). Your webhook secret is HMAC(APP_SECRET, "webhook:<userID>") — fetch it from Dashboard → Webhooks (the webhook_secret field) and pass it as the secret argument.