API docs · 3 of 14

Node.js SDK

Our official library for Node.js 18 or newer is the quickest way to start. It has no other dependencies and includes TypeScript types.

Install

npm install paranthropus
  • Adds your key to every request and sends an Idempotency-Key on every POST, so retries never charge or pay twice.
  • Retries by itself after a dropped connection, a timeout or a server error. Errors like a low balance are not retried.
  • Checks webhook signatures for you.

Quick start

import { Paranthropus } from 'paranthropus';

// Keep the key on your server, in an environment variable.
const paranthropus = new Paranthropus(process.env.PARANTHROPUS_SECRET_KEY); // para_test_... or para_live_...

// Ask a customer to pay. They approve the prompt on their phone.
const collection = await paranthropus.collections.create(
  { currency: 'UGX', amount: 25000, phone: '+256701234567', description: 'Order 1042' },
  { idempotencyKey: 'order-1042' },
);

// Send money to a phone.
const payout = await paranthropus.payouts.create(
  { currency: 'KES', amount: 4500, phone: '+254712345678', description: 'November salary' },
  { idempotencyKey: 'salary-2026-11-amina' },
);

// Check a transaction, and read your wallet balances.
const latest = await paranthropus.transactions.get(collection.reference);
const balances = await paranthropus.balances.list();

Every failed request throws a ParanthropusError with the HTTP status and the error code. If the request never reached us (no internet, timeout), status is 0 and code is connection_error or timeout.

Handling errors

import { ParanthropusError } from 'paranthropus';

try {
  await paranthropus.payouts.create({ currency: 'UGX', amount: 50000, phone: '+256701234567' });
} catch (error) {
  if (error instanceof ParanthropusError && error.code === 'insufficient_balance') {
    // Top up the UGX wallet first.
  } else {
    throw error;
  }
}

Each endpoint page also has a Node.js SDK tab. The package is on npm as paranthropus.