Reference

Skills overview

All 22 Agent Skills: recipes, one per Daraja API, and helpers, with how to install them.

The kit ships 22 Agent Skills. Each one is a folder with a SKILL.md your agent reads, plus tested scripts it runs instead of improvising. Every skill is self-contained, so you can install all of them or only the ones you need.

npx skills add Mr-Macharia/mpesa-daraja-skills-and-mcp

Recipes

End-to-end guides for a whole use case. Start here if you know what you want to build.

Skill	What it covers
Recipe: online checkout	End-to-end recipe for adding M-Pesa checkout to an existing web or mobile app with STK Push.
Recipe: Paybill collections and reconciliation	End-to-end recipe for collecting payments that customers start themselves on a Paybill or Till (C2B), and matching them to accounts.
Recipe: payroll and payouts	End-to-end recipe for paying people from a business with M-Pesa B2C, such as payroll, commissions, supplier-to-wallet payments, winnings and refunds.
Recipe: recurring billing	End-to-end recipe for subscriptions and recurring charges with M-Pesa Ratiba standing orders, with Bill Manager invoices or STK reminders as fallbacks.
Recipe: an agent that sells	Recipe for an AI agent that sells and takes M-Pesa payments for a store, either inside a developer-built store with its own backend or as an agent-only seller in a chat.
Designing an M-Pesa payment system	Designs the system around M-Pesa Daraja calls so money is never lost or double-counted.

Daraja APIs

One skill per Daraja product, plus mpesa-daraja, the entry point that routes to the others.

Skill	What it covers
M-Pesa Daraja	Entry point for Safaricom M-Pesa Daraja API work.
Daraja Authentication	Generates, caches and refreshes Safaricom Daraja OAuth 2.0 access tokens from the Consumer Key and Secret (client-credentials grant with HTTP Basic auth), including single-flight refresh, 401 retry and multi-instance caching.
M-Pesa Express (STK Push)	Implements Safaricom M-Pesa Express (Lipa na M-Pesa Online / STK Push) and STK Push Query.
C2B: Customer to Business	Implements Safaricom Daraja C2B (Customer-to-Business) for Paybill and Till numbers.
B2C: Business to Customer	Implements Safaricom Daraja B2C payouts from a business shortcode to customers' M-Pesa wallets (BusinessPayment, SalaryPayment, PromotionPayment) and to Pochi la Biashara (B2Pochi).
B2B: Business to Business	Implements Safaricom Daraja B2B payments between shortcodes: BusinessPayBill (to a Paybill and account), BusinessBuyGoods (to a Till), BusinessPayToBulk (top up a B2C utility account) and B2B Express Checkout (a USSD push asking a merchant's till operator to pay your Paybill).
Tax Remittance to KRA	Remits taxes to the Kenya Revenue Authority (KRA) from a business shortcode through Safaricom Daraja's Tax Remittance API (CommandID PayTaxToKRA, PartyB 572572, AccountReference set to the KRA Payment Registration Number).
Transaction Status, Reversal and Account Balance	Uses Safaricom Daraja's Transaction Status, Transaction Reversal and Account Balance APIs, whose results arrive asynchronously on a ResultURL, and builds reconciliation jobs on top of them.
Dynamic QR	Generates M-Pesa Dynamic QR codes with Safaricom Daraja for Buy Goods, Paybill, agent withdrawal, send money or send-to-business, with a preset amount and reference, and renders the returned base64 PNG.
M-Pesa Ratiba (standing orders)	Creates M-Pesa Ratiba standing orders (recurring customer payments to a Paybill or Till) through Safaricom Daraja, including frequency codes, date rules, the PIN-consent prompt, and the callback that returns the TransactionID.
M-Pesa Bill Manager	Integrates M-Pesa Bill Manager through Safaricom Daraja.

Helpers

Callbacks, sandbox setup, credentials, troubleshooting, and the sandbox tutor behind the tutorials.

Skill	What it covers
Daraja callback receivers	Builds resilient Safaricom Daraja callback and webhook receivers: STK CallBackURL; C2B Validation and Confirmation; ResultURL and QueueTimeOutURL for B2C, B2B, tax, status, reversal and balance; Ratiba, Bill Manager and B2B Express callbacks.
Daraja sandbox setup and go-live	Sets up a Safaricom Daraja sandbox from scratch: creating the developer account and app with the right products, finding test credentials (shortcodes, passkey, initiator, certificate), writing the .env file, exposing callbacks through a tunnel, smoke testing each API, and running the production go-live checklist.
Daraja credentials and security	Manages Safaricom Daraja secrets safely (Consumer Key and Secret, M-Pesa Express passkey, initiator password, SecurityCredential) and generates the SecurityCredential by RSA-encrypting the initiator password with Safaricom's sandbox or production certificate.
Daraja troubleshooting	Diagnoses Safaricom Daraja and M-Pesa API failures.
Teach me M-Pesa Daraja	An interactive tutor that teaches M-Pesa Daraja step by step in the sandbox.