Skip to content

M-Pesa — taking Safaricom payments and paying at the till (Kenya)

What it is

M-Pesa is Safaricom mobile payments. The customer pays to the shop's number, Safaricom notifies ERPJS, and the payment appears in the M-Pesa Payments register by itself. At the till the cashier chooses that payment instead of typing an amount: a receipt whose M-Pesa amount does not match the chosen payments is not posted. All of this exists only in the Kenya edition of ERPJS.

The module overview is on the M-Pesa (Safaricom, Kenya) page.

Before you start: what to get from Safaricom

  1. A working Till ("Buy Goods") or Paybill number.
  2. A Daraja developer account with an app in it: the consumer key and consumer secret — first for the test environment (Sandbox).
  3. For the live environment — Safaricom's approval: a letter on the company letterhead, usually 1–3 working days.
  4. An ERPJS address reachable from the internet over https://: Safaricom sends notifications only there.

Step 1. Till payment method

  1. In the Payment Method setting, add a code for M-Pesa if there is none.
  2. In the till payment methods, put this code as the third payment method. On a till with M-Pesa the third method is M-Pesa only; put other cashless methods second (terminal) or fourth.

Step 2. M-Pesa account

Open Modules → M-Pesa → Registers → M-Pesa Accounts and create a record.

  • "M-Pesa number (Till / Paybill)" — 5–7 digits; "Number type" — Till (Buy Goods) or Paybill.
  • "Payment Method" — the code from step 1: by it the till learns that its third method is M-Pesa.
  • "Daraja environment", "Daraja consumer key" and "Daraja consumer secret". The keys are stored encrypted: after saving the field shows a mask. Leave it as is — the key stays; type a new one — it replaces the old one; clear the field — the key is erased on saving. Changed the environment — enter the keys again. The keys are needed only for the "Register the address with Safaricom" button: the account receives notifications without them.

One open account per number and per payment method. Fields and checks — on the M-Pesa Accounts page.

Step 3. The notification address — at Safaricom

Save the record. In the window menu:

  • "Notification address" shows the addresses Safaricom will call about payments. They carry the account's secret: do not send them to anyone but Safaricom.
  • "Register the address with Safaricom" passes these addresses to Safaricom with the account's keys. Open ERPJS at the address seen from the internet: that is the one Safaricom gets. The saved record is registered: if you changed the number or the environment, save first. In the live environment Safaricom usually lets you register the address once — later changes go through Safaricom.

Both actions are available to those with the right to change M-Pesa accounts.

Check: pay a small amount to the number (in the test environment — with the Daraja simulator). The payment should appear in M-Pesa Payments within seconds.

Step 4. At the till

  1. Add the goods to the receipt.
  2. Press the third payment method button — the "M-Pesa payment" window opens.
  3. Type the transaction code from the customer's SMS, the amount, the payer's name or (for a Paybill) the account number they entered — two characters or more. The table shows free payments to this till's number received in the last day; the one equal to what is left to pay comes first.
  4. Choose the payment and confirm. A full SMS code typed in is taken at once.

Below the totals the receipt prints a "Paid by M-Pesa" block — the transaction code and amount of every payment taken.

  • Remove a payment from the receipt — choose the "Remove from receipt: …" row in the same window.
  • Delete the receipt — its payments are free again.
  • A payment larger than what is left to pay is refused: a payment is taken whole, M-Pesa gives no change.
  • A payment taken by another receipt or another till cannot be taken — the till names that receipt.
  • A payment to another till's number cannot be taken.

A customer prepayment by M-Pesa

The customer sent the money in advance and there is no invoice yet (a deposit):

  1. Open the payment in M-Pesa Payments and choose "Create customer payment (prepayment)" in the window menu.
  2. A new Payments document opens: the payment method of the M-Pesa account, one prepayment row for the whole amount with "Generate prep No." ticked, the payment's code in the "M-Pesa transaction code" column.
  3. Choose the customer and save the document.

Once it is saved, the Payment document column of the payment in M-Pesa Payments shows this document's number. Neither the till nor another document will take the payment any more. The prepayment is then linked to invoices as usual; one prepayment can cover several invoices or stay partly on the customer.

The code can also be typed into a row of a Payments document by hand, if the document's payment method is the method of an open M-Pesa account. One payment can be split into several rows of the same document (part pays an invoice, the rest is a prepayment): the code goes in each row, and the rows with that code must add up to the payment. A payment cannot be split between different documents.

  • The code removed from the row, or the unposted document deleted — the payment is free again.
  • A posted document with an M-Pesa payment method — every row has a code, the row currency is the base currency, and the rows of each code add up to the payment. Otherwise the document is not posted.

If the notification did not arrive

The customer has the SMS, the register has no payment: Safaricom could not reach ERPJS. A manager enters the payment by hand in M-Pesa Payments — transaction code, amount, number. The cashier then takes it as usual. If the notification arrives later after all, there is no second payment: the key of a payment is its transaction code.

Enter the number and the amount exactly as in the Safaricom statement: the till sees only payments to the numbers of its accounts, and a later notification with the same code does not correct a payment entered by hand.

Checks ERPJS does by itself

  • A repeated Safaricom notification is the same payment, not a second one.
  • An invoice with an M-Pesa amount is not posted until the amount of each M-Pesa payment method in it equals the payments it took to the numbers of that method — from the till, from the invoice window or through the API.
  • M-Pesa payments are in the base currency (KES): an invoice in another currency cannot be paid by M-Pesa and is not posted. There is no conversion at a rate.
  • A payment from Safaricom cannot be deleted or changed — except its comment.

Switching M-Pesa off

Close the account (the "Closed" box). Notifications to its address are no longer accepted, and the till takes the third-method amount from the keyboard again, with no check.

Not there yet

  • Refunds by M-Pesa. A refund receipt takes the third-method amount from the keyboard, as before.
  • Finding the customer by the Paybill account number. The customer in the Payments document is chosen by the bookkeeper.