Payouts
Quote and send money from your TeePay balance to mobile wallets and bank accounts.
Payouts move money from your TeePay balance to a mobile wallet or bank account in Tanzania. Every payout is a two-step operation, so you always see the exact cost before money moves.
Quote
curl https://api.teepay.me/v1/disbursements/quote \
-H "Authorization: Bearer $TEEPAY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"money": { "amount": 2500000, "currency": "TZS" },
"destination": { "channel": "mobile", "name": "Juma Ali", "phone": "255712345678" },
"narration": "Supplier payment October"
}'For a bank account use { "channel": "bank", "name": "…", "bank": "…", "account": "0123456789" }.
Note that in payout requests money.amount is an integer in minor units.
{
"id": "q_4f2c…",
"expires_at": "2026-10-28T10:02:00Z",
"currency": "TZS",
"amount_minor": "2500000",
"merchant_fee_minor": "50000",
"provider_fee_minor": "30000",
"total_minor": "2550000"
}total_minor is what leaves your balance: the amount plus your fee. Provider costs are included in
your fee. A quote expires after two minutes and never moves money.
Confirm
curl https://api.teepay.me/v1/disbursements \
-H "Authorization: Bearer $TEEPAY_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "quote_id": "q_4f2c…", "idempotency_key": "payout-2026-10-0001" }'TeePay reserves the total from your balance before sending. The response is the payout with its
public_reference and status.
Outcomes
| Response | Meaning | What to do |
|---|---|---|
200 | The payout was sent and its current state is returned. | Wait for payout.completed or read it. |
202 | The provider's answer was uncertain. The reservation is kept. | Read the payout. Never retry with a new idempotency_key. |
409 | The quote expired or the key was reused with another quote. | Request a new quote. |
422 | Invalid destination, insufficient balance or over a limit. | Fix and quote again. |
Webhooks: payout.completed, payout.failed, payout.reversed.
Requirements
- Live environment and approved payouts for your account (
features.disbursement_create). disbursement:createto quote and send;disbursement:readto list and read.- Your payout limits (minimum, maximum and daily) apply to every quote.