M-Pesa Daraja API Explained for Business Owners

The M-Pesa Daraja API is Safaricom's platform for connecting M-Pesa to software. Through it, a business's website, app or automation tool can send payment prompts (STK push), get notified of every payment to a Paybill or Till, send money to phones, and check or reverse transactions, without anyone typing into the M-Pesa menu. You sign up free at developer.safaricom.co.ke, create an app, and use its keys to make requests.

This is a plain-language guide for business owners: what each part of Daraja does, what every key and code word means, how sandbox and production differ, and what to ask your developer, or how to skip the developer entirely.

What Daraja can do for your business

Daraja is a set of separate APIs. Each one does one job:

• M-Pesa Express (STK push): asks a customer to pay by sending a prompt to their phone.
• C2B (customer to business): tells your system every time someone pays your Paybill or Till, including payments made from the customer's own M-Pesa menu.
• B2C (business to customer): sends money from your business account to a phone. Use it for salaries, commissions, refunds and winnings.
• Transaction status: looks up a payment by its M-Pesa receipt number.
• Reversal: sends back a payment you received by mistake.
• Account balance: checks the balance of your business account.

Daraja words explained

The Daraja portal and documentation use a lot of terms. Here's what each one means:

• App: a set of keys you create in the Daraja portal for one integration. Each app has products (APIs) switched on, such as M-Pesa Express.
• Consumer key and consumer secret: the app's username and password. Your system swaps them for a short-lived access token before every batch of requests. Keep the secret private, like a bank PIN.
• Access token: a temporary pass, valid for about an hour, sent with each request.
• Shortcode: your business number: the Paybill, or for a Till the Store or Head Office number.
• Passkey: a secret used only by M-Pesa Express. It's combined with your shortcode and the time to make each request's password.
• Initiator name and security credential: used by B2C, reversals and status checks, which move or reveal money. The initiator is a user on your M-Pesa business account, and the security credential is that user's password, encrypted.
• Callback URL: the address on your server where Safaricom sends the result of an STK push. It must be public and HTTPS.
• Confirmation and validation URLs: the addresses Safaricom calls for C2B payments. Validation can accept or reject a payment before it completes; confirmation tells you it happened.
• Result code: the number Safaricom returns with every result. 0 means success. Anything else explains what went wrong: 1032 is cancelled by the customer, 1037 is phone unreachable, 2001 is the wrong PIN.

Sandbox vs production

Daraja has two separate environments:

• Sandbox: for testing. It uses the test shortcode 174379 and a public test passkey. No real money moves, so test every case here: paid, cancelled and unreachable.
• Production: real money and your real Paybill or Till. You get there through "Go Live" in the Daraja portal, which needs the details of the business number you own. Safaricom then issues your production credentials, including the live passkey.

Keys from one environment never work in the other. If an integration that worked in testing fails after going live with an authentication error, mixed-up keys are the first thing to check.

What a Daraja request looks like

You don't need to read code to run a business on Daraja, but it helps to know the shape. Every request follows the same pattern:

1. Exchange your consumer key and secret for an access token.
2. Send the request (for example, "prompt 254712345678 for KES 1,500 to Paybill 123456") with the token.
3. Safaricom replies straight away that it accepted the request.
4. Safaricom sends the actual result to your callback URL a few seconds later.

Step 4 is why Daraja integrations need a server that's always reachable. The result doesn't come back in the reply. It arrives later, at an address Safaricom calls.

The Daraja rules that catch people out

• Phone numbers are written 2547XXXXXXXX: no plus sign and no leading zero.
• Amounts are whole shillings only.
• Timestamps are in Kenyan time (East Africa Time), whatever time zone your server is in.
• The account reference is at most 12 characters and the description at most 13.
• Callback URLs can't contain "M-Pesa", "MPesa" or "Safaricom". Daraja filters them out.
• For B2C and reversals, the security credential is generated for one environment. A credential made for the sandbox fails in production.

Keeping your Daraja keys safe

1. Never put your consumer secret, passkey or security credential in a website's code, a spreadsheet or a chat. Anyone with them can make requests as your business.
2. Give each integration its own app, so you can switch one off without breaking the others.
3. Use limits on anything that sends money: a maximum per payout and per run. A wrong number in a spreadsheet shouldn't be able to empty your account.
4. Change the initiator password when someone with access leaves the business.

Using Daraja without a developer

The hard part of Daraja isn't getting the keys, it's the code around them: tokens, passwords, callbacks, time zones, retries and status checks. A no-code automation tool does that part for you. In CiraIQ you paste your own Daraja keys once (stored encrypted), and then use M-Pesa steps in any workflow:

• M-Pesa Payment Received: starts a workflow when anyone pays your Paybill or Till.
• M-Pesa: sends an STK push and waits for the customer to answer.
• M-Pesa Payout: sends B2C payments, with limits per payout and per run, starting as a dry run.
• M-Pesa Transaction: checks a payment by receipt number, or reverses one.

The money always goes to and from your own business account. Start with the M-Pesa receipt by SMS template, see every option on the M-Pesa integration page, or read how to integrate M-Pesa into your business.

Questions

What is the M-Pesa Daraja API?

It's Safaricom's developer platform for connecting M-Pesa to software: payment prompts, payment notifications, payouts, status checks and reversals.

Is the Daraja API free to use?

Signing up and creating apps is free. The normal M-Pesa transaction charges for your Paybill or Till still apply.

How do I get Daraja API keys?

Sign up at developer.safaricom.co.ke, create an app, and copy its consumer key and consumer secret. For live payments, complete the Go Live process for your Paybill or Till.

What is the difference between C2B and STK push?

With STK push, your business starts the payment by sending a prompt to the customer's phone. With C2B, the customer starts it by paying your Paybill or Till, and Daraja tells your system it happened.

Can I use Daraja with a Till number?

Yes. STK push and C2B both work with a Till (Buy Goods), using your Store or Head Office number as the shortcode.

Do I need a server to use Daraja?

If you build it yourself, yes: one with a public HTTPS address for the callbacks. With a no-code tool, the tool's server receives them for you.