API documentation · v1

Accept and send mobile money with one API

Request payments from customers and send payouts to phones in five countries. Every request uses the same simple JSON, whichever country you are working in.

  • UGX · Uganda
  • KES · Kenya
  • TZS · Tanzania
  • RWF · Rwanda
  • CDF · DR Congo

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.app

Examples 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-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 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,000 in 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-1042

If 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: 25000 means UGX 25,000.
  • Collections: the customer is asked to pay total (amount + fees), and your wallet receives exactly amount.
  • Payouts: your wallet is charged total, and the phone receives exactly amount.
  • 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.

FieldDescription
currencystringrequiredOne of UGX, KES, TZS, RWF or CDF. It decides the country and the wallet used.
amountintegerrequiredA positive whole number in that currency. No decimals.
phonestringrequiredThe mobile money number, e.g. +256701234567. A local number (0701234567) also works.
descriptionstringShown in your dashboard. Up to 140 characters.
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.

FieldDescription
currencystringrequiredOne of UGX, KES, TZS, RWF or CDF. It decides the country and the wallet used.
amountintegerrequiredA positive whole number in that currency. No decimals.
phonestringrequiredThe mobile money number, e.g. +256701234567. A local number (0701234567) also works.
descriptionstringShown in your dashboard. Up to 140 characters.
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.

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.

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.

FieldMeaning
idOur id for the transaction.
referenceUnique 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.
currencyThe wallet currency.
amountThe amount you asked for.
provider_feeThe network charge added on top.
platform_feeThe Paranthropus fee added on top.
totalamount + provider_fee + platform_fee.
method"mobile_money".
phoneThe phone number in international format.
descriptionYour description, or "Collection" / "Payout".
idempotency_keyThe Idempotency-Key you sent, if any.
mode"test" or "live", matching the key you used.
created_atWhen it was created (ISO 8601, UTC).
completed_atWhen 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.succeeded and collection.failed
  • payout.succeeded and payout.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:

// 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.

StatusCodeWhat happened
400invalid_currencycurrency is missing or not one of the five.
400invalid_amountamount is missing, zero, negative or not a whole number.
400invalid_phoneThe phone number is not valid for that country.
400below_minimumThe amount is under the minimum for that currency.
400above_maximumThe amount (including fees, for collections) is over the maximum.
400insufficient_balanceYour wallet cannot cover a payout plus its fees.
401invalid_api_keyThe key is missing, wrong or revoked.
403kyc_requiredLive keys only work once your business is verified.
403account_frozenThe account is frozen. Contact support.
404not_foundNo transaction with that reference for this key, or the endpoint does not exist.
429too_many_promptsToo many payment requests to one phone number (5 every 10 minutes).
502provider_refusedThe mobile network refused the request. Nothing was charged.
500server_errorSomething 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:

CountryCurrencyNetworksMaximum
UgandaUGXMTN, Airtel5,000,000
KenyaKESSafaricom, Airtel70,000
TanzaniaTZSAirtel, Tigo, Vodacom, Halotel5,000,000
RwandaRWFMTN, Airtel5,000,000
DR CongoCDFAirtel, Orange, Vodacom M-Pesa, Africell5,000,000

There are no daily or monthly caps. Need help with your integration? Use the support chat in your dashboard.