Automating M-Pesa B2C Payouts: Bulk Payments, Salaries and Suppliers
How to automate M-Pesa B2C payouts for salaries, bulk payments and suppliers: official tariffs, limits, float management, security controls, and an idempotent payout workflow.

Paying salaries, casual wages, supplier invoices, refunds or claim settlements through M-Pesa does not have to mean someone in finance spends a day sending money from a phone. Safaricom's B2C (Business-to-Customer) payment service exists for exactly this: an organization disburses money from its shortcode to individual M-Pesa numbers, either through a bulk file upload in the M-Pesa web portal or programmatically through the Daraja B2C API. This guide covers both paths, what they cost at Safaricom's official tariffs, the limits and float mechanics that break payday if you ignore them, and the controls you need before you let software move money out of your account.
What the M-Pesa B2C API actually does
B2C is the reverse of collection. STK Push and C2B move money from customers into your paybill or till; B2C pays money out of your shortcode's float into a customer's M-Pesa wallet, in real time. Safaricom's own bulk payment documentation lists the use cases it was built for: salary and casual-worker payments, SACCO and microfinance loan disbursements, insurance claim settlements, listed-company dividend payments, promotional prizes, and NGO or government project disbursements.
The API accepts a CommandID that tells Safaricom what kind of payment you are making, and the choice matters:
- SalaryPayment: payroll. The recipient must be a registered M-Pesa user; unregistered numbers fail with error 4041.
- BusinessPayment: the general-purpose option for supplier payments, refunds and disbursements. Unregistered recipients can still collect the funds at an agent with their national ID.
- PromotionPayment: marketing prizes and rewards. Unregistered recipients are blocked by policy.
Each call to the API pays one recipient. A payroll run of 300 people is 300 API calls, queued and throttled, each with its own asynchronous result callback.
Bulk CSV vs the B2C API: a decision checklist
Safaricom offers two channels for the same service, and the right answer for most organizations is to start with one and grow into the other.
Use the portal bulk upload when:
- You pay tens of people, occasionally: a monthly payroll for 30 staff, a quarterly dividend run.
- Nobody on the team writes code, and you do not want to maintain an integration.
- You want controls without building them: the portal enforces maker-checker natively. A Business Operator uploads the file, and only a Manager can approve the batch.
The portal takes an Excel template of up to 20,000 records per file, supports optional recipient ID validation (the national ID number registered against the M-Pesa account), lets you schedule payments for a future date and time, and produces downloadable statements.
Move to the API when:
- Payouts are triggered by events (a customer requests a refund, a loan is approved, a gig worker completes a shift) and nobody should have to touch a file.
- Volume reaches hundreds or thousands of payments per run, or you pay several times a week.
- You need payouts initiated from your own system (ERP, payroll software, lending platform) with an audit trail in your own database.
The practical trade-off: the portal is free to start and impossible to misconfigure, but it is a manual step on every run. The API removes the human from the loop, which is exactly why it needs the controls described later in this post.
What B2C payouts cost
The business pays the transaction fee; the recipient pays nothing to receive the money. Safaricom's official B2C tariff for payments to registered M-Pesa users is banded by amount:
- KES 1-100: free
- KES 101-1,500: KES 5
- KES 1,501-5,000: KES 9
- KES 5,001-20,000: KES 11
- KES 20,001-250,000: KES 13
There is an option to include the recipient's withdrawal charges in the transfer, so the worker receives a round amount and can cash out at an agent without digging into the balance. That adds the withdrawal fee on top: for the KES 7,501-10,000 band, KES 11 B2C charge plus KES 115 withdrawal charge, KES 126 in total. Paying to Airtel Money or T-Kash numbers costs materially more (the KES 10,001-15,000 band is KES 100 versus KES 11 to M-Pesa), so cross-network payouts deserve their own line in the budget.
A worked example. A construction firm pays 200 casual workers KES 9,000 each, weekly:
- Business charge: 200 x KES 11 = KES 2,200 per week, roughly KES 8,800 per month.
- If the firm also covers withdrawal charges: 200 x KES 126 = KES 25,200 per week.
The alternative is not free either. Paying 200 people one by one from a phone at two to three minutes per payment is about eight hours of staff time every week, plus errors that someone then has to unwind. At any plausible loaded hourly cost, the API or even the portal upload wins within the first month.
For salaried payroll the numbers are smaller: 150 staff averaging KES 45,000 each costs 150 x KES 13 = KES 1,950 per month in fees. The tariff table and recipient-side charges are published on Safaricom's tariffs and limits page, and the B2C business tariffs are in the bulk payment document.
Limits, the float, and why payday fails
Two mechanics cause most B2C failures in production, and neither is a software bug.
The float. B2C payouts draw from a separate B2C utility account, not from the balance customers pay into your collection shortcode. You pre-fund it by RTGS transfer to M-PESA Holding trust accounts at NCBA, KCB, Co-operative Bank or Equity Bank. The beneficiary account number is 333 followed by your B2C shortcode, so shortcode 123456 maps to account 333123456. RTGS credits within about an hour; EFT takes two working days; cheques take three. If the float is empty, payday fails even if your collection account holds millions. The fix is operational: monitor the float and alert before it runs dry. Helpfully, every B2C result callback reports B2CUtilityAccountAvailableFunds, so a well-built integration can track the balance in real time and raise a low-float alert without a separate query.
The limits. New merchants typically start with conservative defaults, commonly cited at KES 500,000 per transaction and KES 2,500,000 per day per PayBillKe's B2C integration guide, with higher ceilings granted after a track record, usually involving about three months of clean B2C history and a bank guarantee covering the float. On the recipient side, individual M-Pesa wallets cap out at a KES 500,000 account balance and KES 500,000 in daily transactions, with a KES 250,000 maximum per transaction. A payout that would push a recipient over their wallet ceiling fails, which matters if you pay the same people large amounts frequently. Finally, the API itself is rate-limited: plan on queueing requests at roughly 30 per minute in production rather than firing a 1,000-row payroll in a burst. Error code 26 means traffic blocked; the correct response is exponential backoff, not a retry loop.
Setting up: from shortcode to first payout
The sequence, assuming you already have a paybill shortcode:
- Enable B2C on the shortcode. Applications for M-Pesa business services, including bulk payment, now run through m-pesaforbusiness.co.ke. If you have an existing shortcode, Safaricom enables the B2C product on it.
- Create the API operator. In the M-PESA Business Portal, register an operator with the B2C Initiator role. Safaricom issues an InitiatorName and initiator password for it.
- Fund the float. RTGS the initial float to the 333-prefixed trust account for your shortcode.
- Create a Daraja app. Register on the Safaricom developer portal, create an app, and get the consumer key and secret used for OAuth tokens. The official product pages describe the B2C disbursement service and its technical integration.
- Build the security credential. This is the step that trips everyone. B2C requires the initiator password encrypted with Safaricom's public certificate using RSA/ECB/PKCS1Padding, base64-encoded. You encrypt once per environment and reuse the ciphertext. The sandbox and production certificates are different files; using the sandbox certificate against production produces error 2001, "the initiator information is invalid," on every request. Keep the resulting credential in a secrets manager, never in source code.
- Wire the endpoints. Token from the OAuth endpoint, then POST to
/mpesa/b2c/v1/paymentrequestwith your shortcode, CommandID, amount, PartyB (the recipient's 2547XXXXXXXX number), remarks, and two callback URLs: ResultURL for the outcome and QueueTimeOutURL for timeouts.sandbox.safaricom.co.kefor testing,api.safaricom.co.kein production. - Test in the sandbox, then go live with a small batch. Pay five real people small amounts before you run payroll.
Controls before you automate money out
An integration that can pay 1,000 people without human involvement can also pay the wrong 1,000 people without human involvement. Before enabling production payouts, put these in place. The Upeosoft guide to B2C payout automation frames the same set:
- Maker-checker for batches. One person or process prepares the payout batch; a second approves it. The portal gives you this free; with the API you build it yourself, typically as an approval step in the workflow that assembles the batch.
- Your own ceilings. Enforce per-transaction and daily limits inside your system, below what Safaricom allows. A runaway loop should hit your ceiling, not your bank balance.
- Credential hygiene. The encrypted security credential and consumer secret live in a secrets manager (AWS Secrets Manager, Vault, Doppler), with access logged. Rotating the initiator password means re-encrypting the credential.
- IP whitelisting. Ask Safaricom to restrict your API access to known server IPs where your setup supports it.
- Alerts on money out. Every payout, or at minimum every batch, should notify a human channel: email, Slack, SMS to the finance lead. Silence is what fraud and bugs both look like.
Building a payout workflow that never double-pays
B2C is asynchronous. The API accepts your request and returns immediately; the actual outcome arrives seconds later as a callback to your ResultURL with a ResultCode, the M-Pesa TransactionID, the receipt number, the recipient's registered name, and the timestamp. Architect around that:
- Every payout starts as pending. Never mark a payment successful when you submit the API call. Mark it when ResultCode 0 arrives on the callback, and store the TransactionID and receipt as the proof of payment.
- Idempotency keys. Generate a unique key per intended payout (employee ID plus pay period, invoice number, refund ID) and refuse to submit the same key twice. Safaricom blocks exact duplicates within 60 seconds with error 2033, but your real protection is your own key, because retries after timeouts look nothing like duplicates to the API. A payout retried blindly after a network hiccup is how people get paid twice.
- Handle the failure codes deliberately. Error 2001 means your credential or certificate is wrong: fix config, not code. Error 17 means the shortcode is not B2C-enabled. Error 18 is an unresolvable receiver, usually a bad number. Error 4041 under SalaryPayment means the recipient is not registered on M-Pesa; switch that payment to BusinessPayment or resolve registration. Error 26 is throttling; back off.
- Queue, do not burst. A worker queue (Celery, Sidekiq, an n8n loop with a wait node, anything) that drips requests at a controlled rate is not optional at payroll scale.
- Verify the recipient name. The result callback returns
ReceiverPartyPublicName. Compare it against who you meant to pay and flag mismatches. This catches transposed phone digits before the reconciliation report does.
If you are choosing the automation platform for this workflow, our comparison of n8n, Zapier and Make covers the trade-offs; for payment flows, self-hosted n8n is the usual pick because credentials and payout data stay on your own infrastructure.
Reconciliation is the other half. The payout side is easier to match than collections because you chose the recipient, so every payout already maps to a payslip, invoice or refund record. The discipline is closing the loop: match each result callback's TransactionID to the pending record, investigate anything pending beyond a threshold, and reconcile the B2C statement against your ledger monthly. Collection-side matching is the harder problem: one engineering team's cascade (account reference, then phone, then amount and timing, then manual review) reaches about 98% automatic matching, as described in this Django and Daraja reconciliation write-up, and we cover that side in our guide to automating M-Pesa reconciliation with n8n and Daraja.
When B2C is the wrong choice
Honest limits:
- Very low volume. If you pay five people monthly, the portal bulk upload, or even manual payment with a strict process, beats building and maintaining an API integration. Automation has a carrying cost.
- Recipients above the wallet limits. A KES 400,000 supplier payment cannot go to a standard M-Pesa wallet in one transaction (KES 250,000 per-transaction ceiling) and may breach the recipient's daily limit anyway. Large B2B payments belong on RTGS or bank transfer.
- Cross-border recipients. B2C pays M-Pesa numbers on Kenyan networks (plus costlier payouts to Airtel Money and T-Kash). Paying contractors in other countries is a different product entirely.
- No float discipline. If finance cannot commit to funding the float ahead of payroll, automation will fail loudly at the worst possible moment. Fix the funding process first.
Frequently asked questions
What is the difference between M-Pesa B2C and B2B? B2C pays from your shortcode to individual M-Pesa customers: salaries, refunds, disbursements. B2B moves money between two business shortcodes, for example paying a supplier's paybill. They are separate APIs with separate enablement.
How much does an M-Pesa B2C payout cost? The business pays a banded fee: free up to KES 100, KES 5 for KES 101-1,500, KES 9 for KES 1,501-5,000, KES 11 for KES 5,001-20,000 and KES 13 for KES 20,001-250,000. Recipients pay nothing to receive the money. Figures are from Safaricom's official bulk payment tariff.
Can I pay someone who is not registered on M-Pesa? With the BusinessPayment command, yes. The recipient collects at an agent with their national ID. SalaryPayment and PromotionPayment require registered recipients and fail with error 4041 otherwise.
What are the default B2C limits for a new business? Commonly KES 500,000 per transaction and KES 2,500,000 per day for new merchants, raised after a track record with Safaricom Compliance, typically supported by a bank guarantee. Recipients have their own limits: a KES 500,000 maximum wallet balance and KES 250,000 maximum per incoming transaction.
Do I need the API, or is the portal bulk upload enough? For occasional batches of tens of people, the portal upload is enough and gives you built-in maker-checker approval and scheduling. Move to the API when payouts are event-driven, frequent, or large enough that a manual upload step is the bottleneck.
What is the security credential and why do payouts fail with error 2001? B2C requires the initiator password encrypted with Safaricom's public RSA certificate. Error 2001 almost always means the wrong certificate was used, typically the sandbox certificate against production, or the credential was regenerated incorrectly. Re-encrypt with the production certificate and store the result in a secrets manager.
Where to go from here
The B2C API is the straightforward part; the durable work is the workflow around it: batch approval, idempotent submission, callback handling, float monitoring and monthly reconciliation. If you want that built rather than described, our business automation service implements payment and operations workflows on n8n and Make, and our custom builds team handles deeper integrations into payroll, lending and ERP systems. Either way, the tariff bands, limits and controls above are the checklist we would start from.
About AI Agents Plus Editorial
AI automation expert and thought leader in business transformation through artificial intelligence.



