Settlements
Money you collect lands in your float — already net of the commission taken at collection. A settlement is you asking for some of that float to be sent to an account you control (your M-Pesa number, your till, your paybill).
Two things make it different from an ordinary payout:
- An operator reviews it. Every request waits for a human at Taifa Pay to approve or reject it. There is no auto-approval, whatever the amount.
- The money is held while it waits. Raising a request moves
amount + feeout of your spendable float into a reserved account, so the same shillings cannot also go out on a payout while the request sits in the queue.
All endpoints on this page take your company Bearer token (see Authentication) and only ever see your own company's requests.
Before your first settlement
You need a verified destination. Register it once, and an operator confirms who the number actually belongs to before any settlement to it can be approved — a payout cannot be recalled, so the name behind the number is checked up front.
curl -X POST https://sandbox.merchants.taifapay.africa/v1/settlements/destinations \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"type": "user",
"identifier": "254712345678",
"isDefault": true
}'
{
"message": "Settlement destination registered and awaiting verification",
"destination": {
"id": "6f1c9a20-...",
"type": "user",
"identifier": "254712345678",
"accountName": null,
"verified": false,
"isDefault": true,
"createdAt": "2026-08-20T09:00:00.000Z"
}
}
| Field | Required | Notes |
|---|---|---|
type | yes | user (phone), pochi, till, paybill, bankAccount. Decides which channels can reach it. |
identifier | yes | Phone number, till, paybill or bank account number. |
accountNumber | paybill only | The account to credit at the paybill. |
bankCode / bankName | bank only | See PesaLink bank codes. |
isDefault | no | Used when a settlement request does not name a destination. |
Posting the same type + identifier again updates the destination and resets it to unverified. A changed number never inherits the previous one's approval.
List what you have registered, and check the verified flag before offering a destination in your own UI:
curl https://sandbox.merchants.taifapay.africa/v1/settlements/destinations \
-H "Authorization: Bearer $ACCESS_TOKEN"
What is available to settle
curl https://sandbox.merchants.taifapay.africa/v1/settlements/balance \
-H "Authorization: Bearer $ACCESS_TOKEN"
{
"message": "Settlement balance retrieved",
"available": { "float": 149987, "float_working": 20000 },
"held": 100013
}
availableis keyed per float pot, and is already net of holds. Do not subtractheldfrom it again — that double-counts.heldis for explanation only: "100,013 is reserved against requests awaiting approval".- Validate an amount against the pot the channel you picked uses (see the table below), never against the sum of the pots. You can have plenty in
floatand nothing infloat_working, so a till settlement can fail while a B2C settlement of the same size succeeds.
Request a settlement
curl -X POST https://sandbox.merchants.taifapay.africa/v1/settlements/requests \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Idempotency-Key: 8f14e45f-ea0c-4f65-9c1b-3a7f0c2d5e11" \
-H "Content-Type: application/json" \
-d '{
"amount": 100000,
"channel": "mpesa_b2c",
"description": "June payout"
}'
| Field | Required | Notes |
|---|---|---|
amount | yes | What the destination receives, in full. The fee is charged on top. |
channel | yes | mpesa_b2c, mpesa_pochi, mpesa_till, mpesa_paybill. |
settlementAccountId | no | Defaults to your default verified destination that the channel can reach. |
description | no | Your own note, up to 200 characters. |
Idempotency-Key is requiredSend a unique key per settlement you intend to raise, and reuse the same key if you retry after a timeout — the replay returns the original request instead of holding the money twice. A request without the header is rejected with 400.
{
"message": "Settlement requested",
"settlement": {
"id": "b3a7c0d2-...",
"amount": 100000,
"fee": 13,
"currency": "KES",
"status": "pending",
"channel": "mpesa_b2c",
"settlementAccountId": "6f1c9a20-...",
"destinationSnapshot": { "type": "user", "identifier": "254712345678", "accountName": "ACME TRADERS LIMITED" },
"floatCategory": "float",
"transactionId": "WDR1A2B3C4D5E6F7",
"statusReason": null,
"createdAt": "2026-08-20T09:05:00.000Z"
}
}
Your float drops by amount + fee — 100,013 here — and the destination receives amount in full. Show both figures before a user confirms.
Channels and the pot each one uses
| Channel | Pays | Destination type | Leaves pot |
|---|---|---|---|
mpesa_b2c | A phone number | user | float |
mpesa_pochi | Pochi la Biashara | pochi | float |
mpesa_till | A Buy Goods till | till | float_working |
mpesa_paybill | A paybill | paybill | float_working |
Sending a channel to a destination it cannot reach is a 422.
Fees
Quote the fee from settlement.fee on the created request rather than reimplementing these tables — they change when Safaricom republishes their tariffs.
mpesa_b2c and mpesa_pochi (disbursement tariff):
| Amount (KES) | Fee |
|---|---|
| 0 – 100 | 0 |
| 101 – 1,500 | 5 |
| 1,501 – 5,000 | 9 |
| 5,001 – 20,000 | 11 |
| 20,001+ | 13 |
mpesa_till and mpesa_paybill (B2B tariff) band from 2 (1 – 49) up to 115 (45,001+) — for example 1,001 – 1,500 → 18, 10,001 – 15,000 → 63, 20,001 – 25,000 → 74.
Commission is never charged on a settlement. It was already taken when the money was collected.
Track the request
# Your requests, newest first — optionally filtered by status
curl "https://sandbox.merchants.taifapay.africa/v1/settlements/requests?status=pending&page=1&limit=10" \
-H "Authorization: Bearer $ACCESS_TOKEN"
# One request
curl https://sandbox.merchants.taifapay.africa/v1/settlements/requests/{id} \
-H "Authorization: Bearer $ACCESS_TOKEN"
The list responds with { message, data, total, page, limit }; a single request comes back as { message, settlement }, including its destination and payout transaction.
| Status | Meaning | Your float |
|---|---|---|
pending | Waiting on a reviewer | Held |
approved | Approved, not yet on the rail | Held |
processing | On the rail, awaiting confirmation | Held |
paid | Money confirmed gone | Spent |
rejected | Turned down — reason in statusReason | Returned |
cancelled | You withdrew it | Returned |
failed | The rail refused, or never confirmed | Returned |
paid, rejected, cancelled and failed are terminal.
The payout transaction alongside it
Every request creates a transaction straight away — not at approval — so a settlement appears in your transaction list from the moment you ask. settlement.transactionId links the two.
| Request status | transaction.status |
|---|---|
pending, approved | pending_settlement |
processing | pending |
paid | complete |
rejected, cancelled, failed | failed |
pending_settlement is not awaiting_settlementThey are opposite ends of the business. awaiting_settlement is a card payment captured at the processor and not yet cleared — money coming in that you cannot spend yet. pending_settlement is money you can already spend and have asked to send out. A filter or badge that lumps them together is wrong in both directions.
Cancel a request
Only while it is still pending. The held float goes straight back to the pot it came from.
curl -X POST https://sandbox.merchants.taifapay.africa/v1/settlements/requests/{id}/cancel \
-H "Authorization: Bearer $ACCESS_TOKEN"
A 422 here means a reviewer got there first — treat it as a race, refetch the request and show its actual state rather than surfacing an error.
Errors
| Code | When |
|---|---|
400 | No Idempotency-Key header |
404 | The request id isn't yours (another company's request reads as missing) |
409 | That idempotency key was already used by a different company |
422 | Not enough float in the pot the channel uses; no verified destination for that channel; channel/destination mismatch; cancelling something no longer pending |
Current limitations
- No notification on approval or rejection. Poll
GET /v1/settlements/requests— settlements do not fire webhooks yet. - No bank channel.
bankAccountdestinations can be registered, but no channel dispatches to a bank today. - Every request needs a human. There is no auto-approval threshold.
Where to go next
- Direct payments & payouts — paying third parties out of the same float
- Webhooks — how you learn about the collections that build the float up