Kenya — M-Pesa collect and payout

Base URL

https://api.transacty.ai

Summary

Collect and pay out KES via M-Pesa. Collect credits the merchant KES wallet; payout debits it and sends to an M-Pesa MSISDN. Native KES ledger — no swap, no cross-border USDT.

Each collect is one M-Pesa collection per API call. The payer approves on their phone. Each payout is one disbursement to a beneficiary MSISDN.

Kenya mobile numbers (accountNumber) accept 2547XXXXXXXX, 07XXXXXXXX, or 7XXXXXXXX.

Live only

This rail has no sandbox. Use a live API key. A test key returns 503 { "code": "payment_unavailable" } on collect and payout.

Settlement wallet & market


Collect	One M-Pesa collection per API call; payer approves on their phone
Settle	Transacty credits KES when the collection is credited (webhook and/or poll)
Payout	Debit merchant KES (amount + platform payout fees) on create; send to MSISDN
Spend	Other pockets cannot fund KES payouts; KES cannot fund USDC / PYUSD-USDC / NGN / CAD
Live only	Use a live API key. `test` → `503` `payment_unavailable`
Market	`kenya` must be approved and KYC verified

KES is a separate wallet pocket. Never sum unlike currencies into one headline number. Read it on GET /v1/balance items[].

Enable the kenya market first. Until Kenya is KYB-approved (and KYC verified), /v1/ke/* returns 403 (market_not_enabled).

Limits (major units, KES)

Flow	Min	Max
Collect	20	145,000
Payout	20	250,000

Required headers

Every request uses HMAC authentication (same scheme as all /v1/* endpoints):

X-Transacty-Key
X-Transacty-Timestamp (Unix seconds)
X-Transacty-Signature = HMAC-SHA256(secret, "{timestamp}.{rawBody}")
Content-Type: application/json on POST
Idempotency-Key (16–255 chars, required on POST collects and POST payouts)

Required scopes

payin:create — POST / GET /v1/ke/collects
payout:create — fee quote, create payout, poll payout

Collect flow

Step	Merchant server	Transacty API
1	Create a collect	`POST /v1/ke/collects` with `Idempotency-Key`
2	Store `transactionId`; prompt the payer to approve on their phone	—
3	Payer approves M-Pesa	—
4	Poll or wait for webhook	`GET /v1/ke/collects/:transactionId`
5	Credit your order on `success` / `payin.completed`	—

List history with GET /v1/transactions?type=payin, then filter rail === "kenya" in your app (no rail= query).

Payout flow

Step	API
1	`GET /v1/ke/payouts/fee-quote?amount=` (optional preview)
2	`POST /v1/ke/payouts` with `Idempotency-Key`
3	`GET /v1/ke/payouts/:transactionId` or wait for webhook

Creating a payout debits KES immediately (amount + platform payout fees). On payout.failed, the wallet is refunded when applicable. No separate beneficiary create step — send MSISDN + name inline.

Webhook events

When a webhook URL is configured, Transacty sends:

payin.completed — KES wallet credited, net of fees (currency: "KES")
payin.failed — collection failed or expired
payout.completed — M-Pesa payout succeeded
payout.failed — payout failed (wallet refunded when applicable)

See Webhooks for signature verification.