M-Pesa setup

Set up M-Pesa on the Safaricom Daraja portal and the M-PESA org portal, then enter the values in Payment settings. Source: Safaricom Daraja API pages, read 5 November 2026.

Short codes and apps

Org portal access needs a Business Administrator. That needs settlement to a bank through a Head Office (HO) application.
Go Live attaches one Daraja app to one live short code. A paybill without B2C permission gets no B2C product and fails with no apiproduct match.
Paybill: enter the paybill as the shortcode. Till: enter the HO or store number from Go Live as the shortcode, and the till number in the till field.
B2C on its own app: fill both B2C consumer fields. Leave both empty to use the main app.

Operator roles

A Business Administrator creates each API user. A user with Set Restricted ORG API Password sets the password; until then the user is pending. Avoid @ and . in the password. Repeated failures lock it.

Role per API
API	Meaning
`B2C`	ORG B2C API Initiator. Used by the B2C initiator name.
`Reversals`	Org Reversals Initiator. Used by the initiator name.
`Transaction Status`	Transaction Status query ORG API. Used for payout and reversal lookups.
`Balance`	Balance Query ORG API. Tinker does not call it.
`B2C Account Top Up`	Org Business Pay to Bulk API initiator. Tinker does not call it.

The security credential is the initiator password encrypted with the public certificate for that environment. Sandbox and production use different certificates.

B2C limits

Ksh 10 minimum and Ksh 250,000 maximum per payment. Tinker refuses a payout outside these limits before sending anything; a refund goes to manual execution and a withdrawal stays blocked, each with the reason.

Fund the Utility account

B2C pays from the Utility account only, not Working or MMF. Tinker never moves money between accounts. Use one of these:

The M-PESA org portal. A second operator approves the transfer.
The B2B API with BusinessTransferFromMMFToUtility. Safaricom must whitelist you through [email protected].
B2C Account Top Up from a paybill's Working account: POST /mpesa/b2b/v1/paymentrequest with BusinessPayToBulk.

Administrators see a low-balance alert in Payment operations when a signed payout result shows the Utility account below Ksh 10,000.

Failed payout codes

Payout result codes
Code	Meaning
`1`	The Utility account has too little money. Fund the Utility account.
`2`	The amount is below Ksh 10.
`3`	The amount is above Ksh 250,000.
`4`	The daily limit is reached.
`21`	The initiator lacks the ORG B2C API Initiator role.
`2001`	The initiator name, password or certificate is wrong. Encrypt the password with this environment’s certificate.
`2028`	The initiator may not use this API or short code.
`8006`	The initiator password is locked after repeated failures.