Talk to us
Talk to us

Integration guide

M-Pesa integration in Kenya: how it works and what to check

What happens between a customer's phone and your records, the ways to collect, what goes wrong and how to find out when it does. For owners who commission an integration and for the developers who build it.

For businesses that take M-Pesa9 min read

Read the guide Talk to us about payments This guide as Markdown

How a payment reaches your system

Safaricom offers M-Pesa to businesses through its Daraja API. Your system never sees a customer's PIN or their balance: it asks for a payment, and Safaricom tells it what became of the request. Everything else in an integration is how you start the request, how you listen for the answer and what you do when the answer is odd.

  1. Your system asks

    It sends the amount, the customer's phone number and a reference to Daraja.

  2. The customer approves

    A prompt appears on their phone and they enter their M-Pesa PIN.

  3. Safaricom tells your system

    A callback reaches your server with the result and, for a payment that succeeded, the M-Pesa receipt number.

  4. You match and record

    The payment is tied to an order or an invoice, once.

  5. The customer is told

    A receipt on screen, by SMS or by email.

Always read the current documentation

Safaricom changes Daraja, its go-live steps and its tariffs from time to time. Use this guide to decide what you need, and Safaricom's documentation for the exact fields.

Choose how you collect

A business can take M-Pesa in three ways and send money out in a fourth. A business may use more than one.

The ways to take and send M-Pesa
Way How it works Suits Watch out for
STK push Your system starts the payment. The customer approves it on their phone. A checkout on a website or app, and invoices sent to a customer. It needs the customer's phone number, and the prompt can be cancelled or can time out.
Paybill with confirmations The customer pays your paybill number and types an account number. Safaricom tells your system about each payment. Rent, school fees, savings and loan repayments, utilities. Wrong or missing account numbers, and several purposes on one paybill.
Till number The customer pays your till number. There is no account number. Shops and counters. Nothing in the payment says which sale it was for, so matching leans on the amount, the time and the phone.
Payouts Your system sends money from your account to a customer's phone. Refunds, loan disbursements, commissions and salaries. Controls, limits, and a payout that fails or has no answer.

What you need before you start

These are the requirements for going live. Delays in an integration are often in them, not in the code.

  • A business shortcode: a paybill or a till number in your business's name.
  • A Daraja developer account, and the sandbox to build and test against.
  • Production credentials, which Safaricom gives after you go through its go-live steps. Ask early what it will want from you.
  • A public HTTPS address on your server that Safaricom can call. A page on your laptop cannot receive a callback.
  • Somewhere safe for the secrets: the keys and passwords belong in the server's settings, not in the code or the repository.
  • Someone who owns reconciliation: a person who looks at the day's differences, every day.

Handle callbacks safely

A callback is a message to check, not proof. It can arrive late, twice or not at all.

  1. Keep it first, then answer

    Store the callback exactly as it arrived and send back your acknowledgement quickly. Work on it afterwards.

  2. Check it against what you expected

    The shortcode, the amount and the reference must match a payment you asked for or an account you hold.

  3. Apply it once

    Use the M-Pesa receipt number as a unique key, so that a callback that arrives twice changes nothing the second time.

  4. Ask when nothing arrives

    If a payment is still unanswered after a reasonable wait, ask Safaricom for the status of the request. Do not guess, and do not charge the customer again.

  5. Leave a trail

    Record the request, the callback and what you did with it, so that you can answer a customer who says they paid.

What goes wrong, and what to do

Plan for each of these before you go live.

Failures to plan for
What happens What to do
The customer cancels or lets the prompt expire Mark the request as not paid, and let the customer try again.
The wrong PIN, or not enough money Show a plain message and offer another try or another way to pay.
The callback is late, missing or repeated Apply it once by receipt number, and ask for the status of a request that is still open.
A paybill payment has a wrong or empty account number Hold it in a list of unmatched payments for a person to settle, and tell the customer.
The customer pays too little or too much Record what was paid, and decide the rule: part payment, credit or refund.
Your server is down when the callback comes Reconcile against Safaricom's report when it is back.

Reconcile every day

An integration is only as good as the check that proves it.

  • Compare your day's total with Safaricom's statement for the shortcode.
  • List every payment on one side and not the other, and clear the list.
  • Keep the list of unmatched payments short and owned by a named person.
  • Post the totals to your accounts, so that the books and M-Pesa agree.
  • Make the report a screen or an email, not a job that someone remembers.

Paying money out

A payout moves money from your account, so it needs the controls a payment does not.

  • Require a second person to approve payouts above a limit you set.
  • Keep a record of who asked, who approved and what Safaricom answered.
  • Never repeat a payout that has no answer. Ask for its status first.
  • Keep the initiator's password out of the code and out of the logs.
  • Check that the account has the money before the request, and alert someone when it runs low.

A payout that is sent twice is money gone twice

Treat a payout with no answer as unknown, not as failed. Find out what happened before you send it again.

What it will cost

Ask a developer to price the parts, so that you can see what you are paying for.

What to ask about cost
Cost What to ask
Building the integration Which of the ways above are included, and does it cover callbacks, failures and reconciliation, or only the happy path?
Testing Who tests with real money after go-live, and how are the test payments returned?
Going live Who deals with Safaricom, and what do you have to supply?
Safaricom's charges These are Safaricom's, set out in its tariff for businesses. Ask your developer to show you which you or your customer pays.
Hosting and monitoring Where does the callback address run, and who is told when it fails?
Support What happens when a payment is missing on a Saturday evening?

Ask for it in phases

A first phase that takes one way of paying through to reconciled records tells you more than a long list of methods that have never been used.

Build it yourself, or use a payments platform

You can connect to Daraja directly, or through a service that sits between you and the providers.

  • Directly to Daraja: the most control and no middle charge, and you carry every edge case yourself, from retries to reconciliation.
  • Through a payments platform or gateway: one connection for several ways of paying, such as M-Pesa and cards, and one set of records. You depend on the provider and pay for the service.
  • Either way, ask who holds the shortcode and the credentials. They should be in your business's name, so that you can move if you must.

Keep reading

Common questions

What is the Daraja API?

Daraja is Safaricom's developer platform for M-Pesa. It lets a business's system ask customers for payments, learn about payments made to its paybill or till, send money to customers and check the status of a transaction.

How do I integrate M-Pesa into my website?

Get a paybill or till number, open a Daraja account, build against the sandbox, add a public HTTPS address for callbacks, pass Safaricom's go-live steps and test with real money. Then reconcile every day.

What is the difference between a paybill and a till number?

With a paybill the customer types an account number as well, which lets you match the payment to a person or an invoice. With a till number there is no account number, so it suits counters where the sale is made on the spot.

What is STK push?

It is a request your system sends so that a prompt appears on the customer's phone. The customer enters their M-Pesa PIN to approve the payment, and Safaricom then tells your system the result.

Why is my STK push callback not arriving?

The usual causes are a callback address that is not public or not HTTPS, a wrong address, a server that answers with an error, or a request the customer did not complete. Log every request, check the address from outside your network and ask for the status of the request.

How long does M-Pesa integration take?

The coding is usually the shorter part. Getting production credentials, testing with real money and reconciling to your accounts take longer, so plan them before you promise a date.

How much does M-Pesa integration cost?

It depends on which ways of collecting you need and how much of failures and reconciliation is included. Safaricom's own charges are separate and set out in its tariff. Ask for the work in phases.

Need M-Pesa working in your system?

Tell us what you sell and how you are paid today. We will say which way of collecting fits, and what we would build first.

Talk to us about payments