Introduction
The API is for business accounts. All requests go to this base address and send and receive JSON:
Base URL
https://paranthropus-api.vercel.appExamples are in cURL, Node.js, Python, PHP, Go and Java, plus our Node.js SDK. Pick a language on any example and every example on the page switches to it.
Every response has the same outer shape. On success:
{ "success": true, "data": { ... } }Payments are asynchronous. A new collection or payout starts as pending while the customer approves it on their phone or the network sends the money. You learn the result from a webhook, or by checking the transaction.
Authentication
Create API keys in your dashboard under Business → Developers. Each key is shown once, so copy it somewhere safe. Keep it on your server: never put it in a website, an app or a public code repository.
Send the key in the Authorization header of every request:
Authorization: Bearer para_test_...para_test_...keys simulate everything. They never move real money and work straight away.para_live_...keys move real money. You can create them once your business has been verified.- If a key leaks, revoke it in the dashboard and create a new one. Revoking takes effect immediately.
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 below also has a Node.js SDK tab. The package is on npm as paranthropus.
Test mode
With a test key, nothing is sent to the mobile networks. Transactions finish by themselves a few seconds after you create them:
- A phone number ending in
0000(for example+256700000000) always fails. - Any other valid phone number succeeds.
- Test balances are always
1,000,000in each currency, and test payouts do not touch your real wallets.
Safe retries (Idempotency-Key)
Networks drop connections. To retry a request without charging or paying twice, send an Idempotency-Key header on every POST. Use something unique to the action, like your order number.
Idempotency-Key: order-1042If we have already seen that key on your account, we return the first response again (same status code and body) and do nothing else. Keys can be up to 100 characters.
Fees and amounts
- All amounts are whole numbers in the wallet currency:
25000means UGX 25,000. - Collections: the customer is asked to pay
total(amount + fees), and your wallet receives exactlyamount. - Payouts: your wallet is charged
total, and the phone receives exactlyamount. - The fees for each transaction are returned in the response, so you always know the final total.
Request a payment
POST/v1/merchant/collections
Sends a mobile money prompt to the customer's phone. They approve it with their PIN, and the money lands in your wallet for that currency.
| Field | Description |
|---|---|
currencystringrequired | One of UGX, KES, TZS, RWF or CDF. It decides the country and the wallet used. |
amountintegerrequired | A positive whole number in that currency. No decimals. |
phonestringrequired | The mobile money number, e.g. +256701234567. A local number (0701234567) also works. |
descriptionstring | Shown in your dashboard. Up to 140 characters. |
Request
curl https://paranthropus-api.vercel.app/v1/merchant/collections \
-H "Authorization: Bearer para_test_..." \
-H "Idempotency-Key: order-1042" \
-H "Content-Type: application/json" \
-d '{
"currency": "UGX",
"amount": 25000,
"phone": "+256701234567",
"description": "Order 1042"
}'Response · 201 Created
{
"success": true,
"data": {
"id": "6f1c2a7e-3b0d-4d7a-9a51-2f6e8c1d4b90",
"reference": "PRN-8F3K2Q91",
"type": "collection",
"status": "pending",
"currency": "UGX",
"amount": 25000,
"provider_fee": 500,
"platform_fee": 0,
"total": 25500,
"method": "mobile_money",
"phone": "+256701234567",
"description": "Order 1042",
"idempotency_key": "order-1042",
"mode": "test",
"created_at": "2026-11-19T09:30:00.000Z",
"completed_at": null
}
}The same phone number can get at most 5 payment prompts every 10 minutes. More than that returns too_many_prompts.
Send a payout
POST/v1/merchant/payouts
Sends money from your wallet to a mobile money number, for refunds, salaries, suppliers or winnings. The total is held in your wallet straight away and released again if the payout fails.
| Field | Description |
|---|---|
currencystringrequired | One of UGX, KES, TZS, RWF or CDF. It decides the country and the wallet used. |
amountintegerrequired | A positive whole number in that currency. No decimals. |
phonestringrequired | The mobile money number, e.g. +256701234567. A local number (0701234567) also works. |
descriptionstring | Shown in your dashboard. Up to 140 characters. |
Request
curl https://paranthropus-api.vercel.app/v1/merchant/payouts \
-H "Authorization: Bearer para_test_..." \
-H "Idempotency-Key: salary-2026-11-amina" \
-H "Content-Type: application/json" \
-d '{
"currency": "KES",
"amount": 4500,
"phone": "+254712345678",
"description": "November salary"
}'The response is a transaction with "type": "payout" and "status": "pending". If your wallet cannot cover the amount plus fees, you get insufficient_balance and nothing is sent.
Check a transaction
GET/v1/merchant/transactions/{reference}
Returns the latest status of one of your transactions. If it is still pending, we ask the network for an update first.
Request
curl https://paranthropus-api.vercel.app/v1/merchant/transactions/PRN-8F3K2Q91 \
-H "Authorization: Bearer para_test_..."The response is a transaction. A test key only finds test transactions, and a live key only finds live ones. Webhooks are the better way to wait for a result. If you poll, wait at least 5 seconds between checks.
Get balances
GET/v1/merchant/balances
Returns the balance of each of your five wallets.
Request
curl https://paranthropus-api.vercel.app/v1/merchant/balances \
-H "Authorization: Bearer para_test_..."Response · 200 OK
{
"success": true,
"data": {
"balances": [
{ "currency": "UGX", "available": 4250000, "reserved": 12000 },
{ "currency": "KES", "available": 86400, "reserved": 0 },
{ "currency": "TZS", "available": 1920000, "reserved": 0 },
{ "currency": "RWF", "available": 512000, "reserved": 0 },
{ "currency": "CDF", "available": 2300000, "reserved": 0 }
]
}
}available is what you can spend. reserved is held for payouts that have not finished yet.
The transaction object
Collections, payouts, transaction checks and webhooks all return this object.
| Field | Meaning |
|---|---|
id | Our id for the transaction. |
reference | Unique reference like PRN-8F3K2Q91. Use it to look the transaction up. |
type | "collection" or "payout". |
status | "pending", "success", "failed" or "reversed". Only "success" means the money has moved. |
currency | The wallet currency. |
amount | The amount you asked for. |
provider_fee | The network charge added on top. |
platform_fee | The Paranthropus fee added on top. |
total | amount + provider_fee + platform_fee. |
method | "mobile_money". |
phone | The phone number in international format. |
description | Your description, or "Collection" / "Payout". |
idempotency_key | The Idempotency-Key you sent, if any. |
mode | "test" or "live", matching the key you used. |
created_at | When it was created (ISO 8601, UTC). |
completed_at | When it finished, or null while pending. |
A few more fields may appear (for example for transfers in your dashboard). Ignore fields you do not need.
Webhooks
Add your webhook address (it must start with https://) under Business → Developers. You get a signing secret starting with para_whsec_, shown once. When a transaction finishes, we POST this to your address:
Webhook body
{
"event": "collection.succeeded",
"data": { "reference": "PRN-8F3K2Q91", "status": "success", ... }
}Events:
collection.succeededandcollection.failedpayout.succeededandpayout.failed
Check the signature
Every delivery has this header:
Paranthropus-Signature: t=1763544600,v1=5f2b9c...t is the time we sent it (Unix seconds). v1 is the hex HMAC-SHA256 of <t>.<raw body>, using your signing secret. Compute it yourself, compare in constant time, and reject old timestamps:
Example
// npm install paranthropus express
import express from 'express';
import { Paranthropus, WebhookSignatureError } from 'paranthropus';
const app = express();
const paranthropus = new Paranthropus(process.env.PARANTHROPUS_SECRET_KEY);
const SECRET = process.env.PARANTHROPUS_WEBHOOK_SECRET; // para_whsec_...
// Read the raw body: the signature covers the exact bytes we sent.
app.post('/paranthropus/webhook', express.raw({ type: 'application/json' }), (req, res) => {
let event;
try {
// Checks the signature and the timestamp (5 minutes), then parses the JSON.
event = paranthropus.webhooks.verify(req.body, req.get('Paranthropus-Signature'), SECRET);
} catch (error) {
if (error instanceof WebhookSignatureError) return res.status(400).send('bad signature');
throw error;
}
// event.event is e.g. "collection.succeeded"; event.data is the transaction.
// Mark your order as paid here, using event.data.reference.
res.sendStatus(200);
});Retries
Reply with any 2xx status within 10 seconds. Otherwise we try again after 1, 2, 4, 8 … minutes, up to 10 tries. You can see every delivery in your dashboard. The same event can arrive more than once, so use data.reference to make sure you only fulfil an order once.
Errors
Errors use the normal HTTP status codes and always have the same shape:
{
"success": false,
"error": { "code": "insufficient_balance", "message": "Not enough money in this wallet for the amount plus fees." }
}Write your code against error.code, which does not change. error.message is written for people and may change.
| Status | Code | What happened |
|---|---|---|
| 400 | invalid_currency | currency is missing or not one of the five. |
| 400 | invalid_amount | amount is missing, zero, negative or not a whole number. |
| 400 | invalid_phone | The phone number is not valid for that country. |
| 400 | below_minimum | The amount is under the minimum for that currency. |
| 400 | above_maximum | The amount (including fees, for collections) is over the maximum. |
| 400 | insufficient_balance | Your wallet cannot cover a payout plus its fees. |
| 401 | invalid_api_key | The key is missing, wrong or revoked. |
| 403 | kyc_required | Live keys only work once your business is verified. |
| 403 | account_frozen | The account is frozen. Contact support. |
| 404 | not_found | No transaction with that reference for this key, or the endpoint does not exist. |
| 429 | too_many_prompts | Too many payment requests to one phone number (5 every 10 minutes). |
| 502 | provider_refused | The mobile network refused the request. Nothing was charged. |
| 500 | server_error | Something went wrong on our side. It is safe to retry with the same Idempotency-Key. |
Countries and limits
Each currency belongs to one country, and the phone number must be from that country. Minimums depend on the currency and are returned in the below_minimum error message. Maximums per transaction:
| Country | Currency | Networks | Maximum |
|---|---|---|---|
| Uganda | UGX | MTN, Airtel | 5,000,000 |
| Kenya | KES | Safaricom, Airtel | 70,000 |
| Tanzania | TZS | Airtel, Tigo, Vodacom, Halotel | 5,000,000 |
| Rwanda | RWF | MTN, Airtel | 5,000,000 |
| DR Congo | CDF | Airtel, Orange, Vodacom M-Pesa, Africell | 5,000,000 |
There are no daily or monthly caps. Need help with your integration? Use the support chat in your dashboard.