Help centre
How can we help?
Step-by-step guides for setting up Hesalio. Everything is on this page, and the links inside the app bring you back here.
M-Pesa
Receive PayBill and Till payments.
Register Hesalio's payment URLs in your own Safaricom Daraja app, then make one verification payment. After that, customer payments to your number are recorded automatically.
Before you start
What you need.
- A PayBill, or a Till with a head office number. A Till that settles to a bank has a Till number and a store number; the head office number is the one Daraja uses.
- Administrator access to your number's M-PESA business portal.
- A Hesalio account where you are the owner or an admin.
Daraja is Safaricom's service for Kenya, so this guide covers Kenyan numbers only. Daraja's portal changes from time to time, so screen names may differ slightly. If something doesn't match, Daraja's in-portal support can help.
Steps
Four steps, about half an hour of work.
-
Add your number in Hesalio
- Open Reconciliation and find Your PayBill and Till numbers.
- Enter the number, choose PayBill or Till, and press Add number.
- On the new card, open URLs for your own Daraja app. You'll see a Confirmation URL and a Validation URL.
These URLs work for this number only. Treat them like a password: don't paste them into chat groups or support tickets.
-
Create a Daraja app and go live
- Sign up at the Daraja developer portal (developer.safaricom.co.ke) and create an app that includes C2B.
- In your M-PESA business portal, create a user with the assistant role. Daraja uses it to confirm that you own the number.
- In Daraja, open your app, press Go Live, and choose Verification by Shortcode. Enter the assistant user's username, select C2B and submit.
- When approved, you'll get live credentials (a consumer key and a consumer secret). Keep them private. Hesalio never asks for them on this route.
-
Register the two URLs
Use Daraja's URL registration screen if your portal has one. Otherwise call the Register URL API with your live app. First get a token:
curl -s -u "CONSUMER_KEY:CONSUMER_SECRET" \ "https://api.safaricom.co.ke/oauth/v1/generate?grant_type=client_credentials"Then register, replacing the token, your number and the two URLs copied from Hesalio:
curl -s -X POST "https://api.safaricom.co.ke/mpesa/c2b/v2/registerurl" \ -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"ShortCode":"YOUR_NUMBER","ResponseType":"Completed", "ConfirmationURL":"CONFIRMATION_URL_FROM_HESALIO", "ValidationURL":"VALIDATION_URL_FROM_HESALIO"}'- A number has one pair of URLs at a time. If Safaricom says URLs are already registered, delete the old pair in Daraja's URL management, then register again.
- Paste the URLs exactly as Hesalio shows them. Safaricom rejects URLs that contain words like "mpesa".
- Completed means a payment still goes through if Hesalio is briefly unreachable.
-
Tell Hesalio, then verify
- Back on the number's card, press I registered them in my own Daraja app.
- Make the verification payment shown on the card. A PayBill gets a code to use as the account number. A Till gets an exact amount to pay.
- The card changes to Verified. Payments to that number are now recorded automatically.
The verification payment proves the number is yours and that Safaricom's notifications reach Hesalio. The money is held for you to refund or apply to an invoice from Reconciliation.
After setup
What happens when a customer pays.
- PayBill, invoice number as the account number: if the amount matches what is due on that invoice, Hesalio marks the invoice paid and books the payment. A customer who withholds tax can pay that much less, and the net amount settles the invoice too, with the withholding booked.
- Till payments: a Till payment carries no account reference, so Hesalio can't tell which invoice it is for. It is held as an unapplied payment for you to match in Reconciliation.
- Anything that doesn't match (no account number, an unknown invoice number, an invoice already paid, or a different amount) is held as an unapplied payment until you apply it to an invoice or sort it out in Reconciliation. Nothing is dropped.
- Possible double sends: the same payer, amount and account number a few minutes apart is flagged for you to check. It is still recorded, because it is real money.
- Repeated notifications: Safaricom sometimes sends the same notification twice. Each M-Pesa receipt is recorded once, so repeats change nothing.
Tip for your customers: ask them to type the invoice number exactly as account number (capital letters don't matter) and to pay the exact amount due.
M-Pesa troubleshooting
If something doesn't work.
| What you see | Likely cause |
|---|---|
| The card stays on "waiting for verification payment" | The URLs aren't registered, a URL has a typo, or the code or amount on the payment didn't match. Check step 3, then pay again with the exact code or amount. |
| Daraja rejects a URL | The URL contains a blocked word, isn't HTTPS, or your live app doesn't cover that number. |
| "Already verified for another business" | Another business proved this number first. Contact Hesalio support. |
| Payments stop after a change in Daraja | Registering a new pair replaces the old one. Register Hesalio's URLs again. |
| "Register payment URLs" fails | That button uses Hesalio's own Daraja app, which can only register numbers it controls. Use the steps above instead. |
M-Pesa questions
Common questions.
Does Hesalio move my money or ask for my M-Pesa PIN?+
No. Hesalio only receives Safaricom's notification that a payment arrived, so it can record it. Your money stays in your M-Pesa account. Hesalio never asks for your M-Pesa PIN, and on this route it never asks for your Daraja keys.
What's the difference between PayBill and Till?+
With a PayBill the customer types an account number, so Hesalio can match the payment to an invoice automatically. With a Till there is no account number, so every Till payment is matched by you in Reconciliation.
I have several numbers. Do I need a separate Daraja app for each?+
Add each number to Hesalio separately, and each gets its own URLs. Whether one Daraja app can cover several of your numbers is a question for Daraja support, because the go-live check is done per number. If in doubt, create one app per number.
How do refunds on my Hesalio subscription work?+
Contact support with the payment and the reason. A member of Hesalio staff reviews the request, and larger refunds need a second person to approve. Card and phone-prompt payments are refunded through Paystack, and the refund shows as pending until Paystack confirms it. If the result is unclear we check the provider's record before doing anything more, so we never send the same refund twice.
Can I do this without Daraja?+
Yes, partly. In Reconciliation you can import your M-Pesa statement as a CSV file, and Hesalio records the payments from it. That is also a good way to catch up on anything missed. It isn't instant the way Daraja is.
What happens to money I pay out?+
When you import an M-Pesa or bank statement, Hesalio lists the payments out that are not in your books yet, on the Cash position in Accounting. Each one shows a suggested account. At first these are starting guesses for common costs such as electricity, rent and bank charges; after you have chosen the same account for the same payee more than once, Hesalio suggests your own choice instead. Nothing is recorded until you pick the account and press Record, and you can set aside anything that is not a business payment.
What if customers pay before my number is verified?+
Those payments are kept, not lost. They aren't applied to invoices until the number is verified, and then they are booked automatically.
What happens to the verification payment?+
It's recorded as an unapplied payment. Hesalio doesn't send money back for you, so if you want to return it, do that from your own M-Pesa account. Otherwise apply it to an invoice in Reconciliation.
Who can set this up?+
Owners and admins. Only they can see the URLs, because the token inside them is like a password for your number.
How do I stop Hesalio recording a number?+
Press Remove on the number's card. That stops Hesalio recording it, but Safaricom keeps sending notifications until you delete the URLs in Daraja's URL management.
Does this work outside Kenya?+
No. Daraja is Safaricom's service for Kenya. Hesalio's other countries need a different M-Pesa or mobile-money integration.
Are the URLs safe to share with Daraja support?+
Share them only with Safaricom's own support if they ask. Never post them in public chats. If you think they've leaked, remove the number in Hesalio (the old URLs stop working at once), add it again to get fresh URLs, register those in Daraja, and make the verification payment again.
M-Pesa words you'll meet
Plain-English glossary.
Checklist
Ready to receive payments?
- The number shows Verified on its card.
- Your Daraja app is live, not in sandbox, and the URLs are registered against this number.
- Your invoices tell customers to use the invoice number as the account number.
- Someone checks Reconciliation for unapplied payments regularly, for example weekly.
- Your Daraja credentials are stored somewhere private, and at least two trusted people can reach your M-PESA portal.
KRA eTIMS
Connect to KRA and send invoices.
Hesalio connects your business to KRA's Online Sales Control Unit (OSCU). Once connected, finalized invoices are sent to KRA, and KRA's signed receipt is kept with the invoice for audit.
You need your KRA PIN and an eTIMS registration for the system you are connecting. The values you enter must match what KRA has on record for you.
Steps
Connect your business to eTIMS.
-
Open the eTIMS page
Sign in and open eTIMS from the menu. Under Business configuration you'll find the fields listed in the next step.
-
Fill in the connection details
Field What to enter TIS name The name KRA has for your system. It is filled in for you as Hesalio_etims.TIS version The version KRA has on record. It is filled in for you as V2.01.KRA PIN Your 11-character KRA PIN. Branch ID Two characters. 00is filled in for you. Change it only if KRA gave you a different branch ID.Device serial The serial exactly as it appears in your eTIMS registration with KRA. KRA expects the serial it has on record for your PIN. If you leave this blank, Hesalio generates one the first time you save, which will be rejected unless it matches KRA's record. Once saved, the serial is kept. Environment Sandbox for testing with KRA's test environment, Production for real invoices. -
Save, then initialize
- Press Save configuration.
- Press Initialize with KRA. Hesalio asks KRA to register this connection.
- Check the Fiscal device card. When initialization works, it shows the connection as initialized. Use Refresh status to update it.
-
Prepare your products, then send invoices
Each product needs an eTIMS item code and classification before its invoices can be sent. After that, finalized invoices go to KRA, and you can follow each one under Recent transactions on the eTIMS page: whether KRA accepted it, rejected it, or it is still being sent.
eTIMS troubleshooting
If initialization fails.
| What you see | Likely cause |
|---|---|
| KRA rejects initialization | The PIN, branch ID or device serial doesn't match KRA's record. Compare each one with your eTIMS registration, correct it, save and try again. |
| It works in Sandbox but not Production (or the reverse) | Check that the Environment (Sandbox or Production) matches where your details are registered with KRA. |
| An invoice can't be sent | One of its products is missing an eTIMS item code or classification. Add them, then send the invoice again. |
| An invoice shows as rejected | The Result column on the eTIMS page shows what KRA returned. Fix what it names and resend. |
When you contact support, include the message shown on the eTIMS page. Never send your KRA password or any keys.
Stock
Batches, costing and purchase orders.
Hesalio keeps stock in step with your bills and invoices. These are the settings people ask about most.
Plans: stock tracking, batches and costing start on Essential. Purchase orders, reorder planning and ABC ranking start on Growth.
| You want to | What to do |
|---|---|
| Track expiry dates | Open Inventory and use the Batches and expiry card. Receipts can carry a batch number and expiry date, and sales take from the batch that expires first. |
| Choose how sales are costed | On the Inventory page, under Stock value, pick "How sales are costed": average price paid, or FIFO (oldest stock first). Only an owner, admin or accountant can change it. Switching does not revalue stock and posts no entry. Earlier sales keep the cost they were booked at. |
| Reorder before you run out | Set a reorder level on each product. On Growth and above, Hesalio can also suggest reorder points and quantities from your own sales, and draft purchase orders for you to approve. |
| Send a purchase order to a supplier | Open Purchase orders and either download the order as a PDF or email it to the supplier (owner, admin and accountant). Record goods received against it when they arrive. |
| See what moved today | The Daily stock report on the Inventory page shows what was received and sold, adjustments and damages for any day you choose. Emailing it is part of Growth and above. |
AI
What the AI does, and what it keeps.
The AI reads documents, answers questions about your own records and prepares routine work for you to approve. It never moves money, files tax or changes your books on its own. AI is optional on every plan.
If your AI allowance runs out, documents are still read and processed. Your plan sets how many AI insights you get each month.
| You want to | What to do |
|---|---|
| Fix something it read wrongly | Open it under Records, correct the value and choose Verify. The original stays in the history. A corrected category is remembered for your business next time. |
| Tell it an answer was not helpful | Under an answer on the Dashboard, choose No. Your rating is saved at once. A box to share the question and answer starts unticked, and nothing is kept unless you tick it. Names and phone numbers are removed before anything is kept. |
| See what it has kept | An owner or admin can open "What Hesalio has learned from your corrections" on the Dashboard, under the assistant, and remove any item. Corrections are deleted after 12 months, and removed if the customer concerned is erased. |
| Check how well it is doing | An owner or admin can open "How well is the AI doing?" on the Dashboard. It shows how often suggestions were accepted and whether a person or Hesalio's own checks decided. A percentage appears after 5 decisions. |
| Use Kiswahili | Use the EN | SW switch at the bottom right of any page. Business terms such as invoice, VAT and eTIMS stay in English. |
Contact support
Still stuck? We can help.
Email support@hesalio.africa or use our contact page.
So we can help quickly, tell us which guide you were following and what the screen shows. For M-Pesa, include the PayBill or Till number. Don't send keys, passwords or your callback URLs.