Taking M-Pesa live: Go-Live, keys and URLs
What a Kenyan business needs from Safaricom before M-Pesa invoice payments work in Achekam, from its own Daraja app and Go-Live to registering its URLs.
By Achekam · · 4 min read · For Running a business businesses in Kenya
For most Kenyan customers, "how can I pay?" has one expected answer: M-Pesa. A business that can send a payment prompt to a customer's phone, or that recognises a paybill payment against the right invoice without anyone sorting through statements, gets paid sooner and spends less time chasing.
Getting there takes a little set-up with Safaricom before Achekam can do anything. None of it is difficult, but the steps have to happen in order, and one of them can only be done once. This article walks through them.
Your own Daraja app
Achekam does not collect M-Pesa payments on your behalf through a shared account. It works through your business's own Daraja app, the developer access Safaricom gives a business for its own short code.
Through that app, Achekam can do two things for a Kenyan business:
- Send a payment prompt, an STK push, to the customer's phone for a shilling invoice, to your paybill or Buy Goods till. The payment is recorded only after Achekam confirms it with Safaricom.
- Recognise paybill or till payments that customers make from their own phones, as long as your short code is registered for notifications.
Create the Daraja app under your business's own Safaricom account, not a developer's personal one. Whoever controls the app controls the keys.
Safaricom Go-Live and the production passkey
A Daraja app starts in Safaricom's test environment. To take real payments, a Kenyan business must complete Safaricom's Go-Live for its short code. After Go-Live, Safaricom e-mails the production passkey.
Keep that e-mail safe and make sure it goes to a mailbox the business controls. The passkey, the short code and the Daraja keys together are what Achekam needs.
Entering the short code and keys
A workspace administrator enters the business's own production short code, passkey and Daraja keys in Settings under Payment Gateways & Checkout. Other users can see the settings but cannot save them. The administrator can test the connection with a real call to Safaricom before any customer is prompted.
Registering the URLs once per short code
For paybill and till payments to reach Achekam, the short code has to be registered so Safaricom knows where to send its payment notifications. Achekam can register a Kenyan business's paybill or till for this. Safaricom's Daraja page on Customer To Business (C2B) payments explains how the validation and confirmation URLs are registered, the rules those URLs must follow and the go-live steps.
Two Safaricom rules matter here:
- It is one-time. Production URL registration happens once per short code at Safaricom. If your short code was already registered with another system, such as an old till or a previous provider, changing it needs two operators in the M-Pesa org portal. Arrange that before you start, not on the day you go live.
- Safaricom refuses addresses containing "mpesa". Achekam's notification address avoids the word for exactly that reason, so you do not need to work around it.
Safaricom does not sign these notifications. Achekam protects them with a secret address and a check of Safaricom's source addresses instead.
What happens when customers pay
Once the set-up is done, payments arrive in one of two ways.
A prompt to the customer's phone. From the invoice, you send an M-Pesa prompt for a shilling invoice. Only whole shillings are requested, so any cents stay due on the invoice. The same phone can be prompted once a minute, which stops an impatient double-tap from sending two prompts.
A payment from the customer's own phone. A payment that quotes an open shilling invoice number as the account number is receipted against that invoice automatically. Any other payment waits in a list for a person to allocate, so a customer who types their name instead of the invoice number does not disappear; they simply need someone to match them.
If a notification never arrives, the payment is still picked up, because the server asks the provider about open M-Pesa payments on a schedule and while the pay page is open. A verified payment is recorded as a receipt against the invoice, and the invoice shows as paid or part-paid.
Keeping it working
Once M-Pesa is live, a few habits keep it that way. Keep the production passkey and Daraja keys with the person who administers Achekam, not on one employee's phone. After any change on Safaricom's side, such as a new short code, re-issued keys or a change of administrator, re-enter the details and use the connection test in Payment Gateways & Checkout before customers are prompted again. And look at the list of unallocated payments every day; a growing list usually means customers are not quoting the invoice number, which is a message to fix on your invoices, not in your books.
Testing with a small invoice
Before you tell customers, test every path with real money:
- Raise a small shilling invoice to yourself.
- Send the prompt to your own phone, pay it, and check the receipt appears on the invoice.
- Raise another small invoice and pay it from your phone through the paybill or till, quoting the invoice number as the account.
- Make one more payment with a wrong account number and confirm it lands in the list waiting for allocation.
- Allocate it to the invoice it was meant for.
If all five work, you are ready. Tell customers to quote the invoice number as the account number; it is the single habit that makes automatic receipting work.
Schools collecting fees by paybill use these same steps, as described in school fees through an M-Pesa paybill, and garages that prompt customers at vehicle collection follow them too; see an M-Pesa prompt on collection. Payroll deductions work differently and are covered in Kenyan payroll deductions and who collects them.
Start the Go-Live application with Safaricom now. It is the step you cannot hurry, and nothing else in this article works until it is done.
General guidance only, not advice on your own circumstances. Tax and payroll rules change: check the current position with the authority or your adviser.
