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-Keyon everyPOST, 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.