Skip to main content

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 + fee out 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"
}
}
FieldRequiredNotes
typeyesuser (phone), pochi, till, paybill, bankAccount. Decides which channels can reach it.
identifieryesPhone number, till, paybill or bank account number.
accountNumberpaybill onlyThe account to credit at the paybill.
bankCode / bankNamebank onlySee PesaLink bank codes.
isDefaultnoUsed when a settlement request does not name a destination.
Re-registering clears verification

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
}
  • available is keyed per float pot, and is already net of holds. Do not subtract held from it again — that double-counts.
  • held is 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 float and nothing in float_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"
}'
FieldRequiredNotes
amountyesWhat the destination receives, in full. The fee is charged on top.
channelyesmpesa_b2c, mpesa_pochi, mpesa_till, mpesa_paybill.
settlementAccountIdnoDefaults to your default verified destination that the channel can reach.
descriptionnoYour own note, up to 200 characters.
Idempotency-Key is required

Send 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​

ChannelPaysDestination typeLeaves pot
mpesa_b2cA phone numberuserfloat
mpesa_pochiPochi la Biasharapochifloat
mpesa_tillA Buy Goods tilltillfloat_working
mpesa_paybillA paybillpaybillfloat_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 – 1000
101 – 1,5005
1,501 – 5,0009
5,001 – 20,00011
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.

StatusMeaningYour float
pendingWaiting on a reviewerHeld
approvedApproved, not yet on the railHeld
processingOn the rail, awaiting confirmationHeld
paidMoney confirmed goneSpent
rejectedTurned down — reason in statusReasonReturned
cancelledYou withdrew itReturned
failedThe rail refused, or never confirmedReturned

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 statustransaction.status
pending, approvedpending_settlement
processingpending
paidcomplete
rejected, cancelled, failedfailed
pending_settlement is not awaiting_settlement

They 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​

CodeWhen
400No Idempotency-Key header
404The request id isn't yours (another company's request reads as missing)
409That idempotency key was already used by a different company
422Not 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. bankAccount destinations 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​