Disbursements
Send money to mobile money accounts and bank accounts
The Disbursements API (Payouts) allows you to send money to mobile money accounts and bank accounts.
Payout Channels
Mobile Money
Send to Airtel Money, M-Pesa, Mixx by Yas, and HaloPesa
Bank Transfer
Send to 40+ Tanzanian banks including CRDB, NMB, NBC, ABSA, and more
Payout Flow
Ensure you have sufficient balance before creating payouts. The total amount (payout + fees) will be deducted immediately.
API Endpoints
| Endpoint | Method | Description |
|---|---|---|
/v1/payouts/send | POST | Create payout |
/v1/payouts | GET | List payouts |
/v1/payouts/{reference} | GET | Get payout status |
/v1/payouts/fee | GET | Calculate payout fee |
Payout Status
| Status | Description |
|---|---|
pending | Payout created, awaiting processing |
completed | Payout successful, recipient received funds |
failed | Payout failed (see failure_reason) |
reversed | Payout was reversed after completion |
If a payout fails, the funds are automatically returned to your balance.
List Payouts
Retrieve all payouts for your account with pagination.
GET /v1/payouts?limit=20&offset=0
Authorization: Bearer <api_key>Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | integer | 20 | Results per page (max 100) |
offset | integer | 0 | Pagination offset |
Response
{
"status": "success",
"code": 200,
"data": {
"items": [
{
"amount": {
"currency": "TZS",
"value": 5000
},
"api_version": "2026-01-25",
"channel": {
"provider": "airtel",
"type": "mobile_money"
},
"completed_at": "2026-01-25T01:06:52.322977Z",
"created_at": "2026-01-25T01:06:39.60131Z",
"external_reference": "fVJQRPGYbtN3",
"fees": {
"currency": "TZS",
"value": 1500
},
"id": "29faef0f-765f-4325-a674-6196f1d9232d",
"metadata": {
"employee_id": "EMP-001",
"payroll_id": "PAY-2026-01"
},
"narration": "Salary payment January 2026",
"object": "payout",
"recipient": {
"name": "John Doe",
"phone": "255781000000"
},
"reference": "667c9279-846f-4001-b046-fdecab204f4f",
"status": "completed",
"total": {
"currency": "TZS",
"value": 6500
}
}
],
"total": 16,
"limit": 20,
"offset": 0
}
}Get Payout Status
Retrieve the current status of a payout by its reference.
GET /v1/payouts/{reference}
Authorization: Bearer <api_key>Response
{
"status": "success",
"code": 200,
"data": {
"amount": {
"currency": "TZS",
"value": 5000
},
"api_version": "2026-01-25",
"channel": {
"provider": "airtel",
"type": "mobile_money"
},
"completed_at": "2026-01-25T01:06:52.322977Z",
"created_at": "2026-01-25T01:06:39.60131Z",
"external_reference": "fVJQRPGYbtN3",
"fees": {
"currency": "TZS",
"value": 1500
},
"id": "29faef0f-765f-4325-a674-6196f1d9232d",
"metadata": {
"employee_id": "EMP-001",
"payroll_id": "PAY-2026-01"
},
"narration": "Salary payment January 2026",
"object": "payout",
"recipient": {
"name": "John Doe",
"phone": "255781000000"
},
"reference": "667c9279-846f-4001-b046-fdecab204f4f",
"source": "api",
"status": "completed",
"total": {
"currency": "TZS",
"value": 6500
}
}
}Calculate Payout Fee
Always calculate fees before creating payouts to ensure you have sufficient balance.
GET /v1/payouts/fee?amount=5000
Authorization: Bearer <api_key>Response
{
"status": "success",
"code": 200,
"data": {
"amount": 50000,
"fee_amount": 1000,
"total_amount": 51000,
"currency": "TZS"
}
}Idempotency
Always use the Idempotency-Key header to prevent duplicate payouts when
retrying failed requests.
POST /v1/payouts/send
Idempotency-Key: payout-emp-001-jan-2026- Keys are valid for 24 hours
- Same key + same request body = returns cached response
- Same key + different body = returns error