Skip to main content
A payout sends money from the account that owns the API key out of PrimePay, to an Airtel Money or TNM Mpamba number or to a bank account. The dashboard’s payout page uses the same rules.

​
How a payout works

Unlike a transfer, a payout depends on the network or bank, so it isn’t always final straight away:
1

Reserve

PrimePay checks the request, then reserves the amount plus the fee from your available balance.
2

Send

The payout goes to the network or bank. Its status is processing.
3

Result

When they answer, the status becomes success, or failed. If a payout fails, the amount and the fee go back to your available balance.
An answer can take a few seconds or longer. PrimePay keeps checking a processing payout until it gets a clear answer, and never marks it failed just because the network was slow. If a network or bank isn’t connected yet, the payout is still accepted: it waits as processing with the money reserved, and goes out as soon as the connection is live. Check the result with GET /v1/payouts/{reference}. Payouts need a full secret key from a listed server address; payments-only keys are refused. Every POST needs an Idempotency-Key header (up to 64 characters). A repeat of the same payout returns 200 with Idempotent-Replayed: true and is never paid twice; the same key for a different payout returns 422 idempotency_key_reused.

​
Limits and fees

PrimePay can change limits and fees. The fee is paid on top of the amount and shown in the response as fee; the recipient always gets amount.

​
Payout errors