Prerequisites
Before using M-Pesa in iVendNext, ensure the following are in place:
Your iVendNext company uses KES as its default currency, or the invoices you intend to process are denominated in KES. M-Pesa does not support transactions in other currencies.
You have an active Safaricom Daraja account with an approved M-Pesa app. From the Daraja developer portal, collect your Consumer Key, Consumer Secret, Business Shortcode, and Online Passkey.
Your iVendNext site must be accessible over a publicly reachable HTTPS URL so Safaricom can deliver webhook callbacks. In local development, use a tunneling tool such as ngrok.
The ivendnext_mpsa_payments app is installed on your bench.
How to Create Mpesa Settings
Mpesa Settings is the central configuration record for each payment shortcode or gateway. Create one record per MPESA shortcode.
Go to Mpesa Settings and click New.
Enter a unique Payment Gateway Name (for example, Main Till). This name is appended to the Mode of Payment and Payment Gateway created automatically on save.
Set API Type to MPesa Express.
Enter your Consumer Key and Consumer Secret from the Safaricom Daraja portal.
Enter your Business Shortcode — the Safaricom-assigned identifier for your PayBill or Till.
Enter the Till Number and Online Passkey.
Set the Transaction Limit to the maximum KES amount allowed per single STK Push request. If an invoice exceeds this amount, iVendNext automatically splits it into multiple requests so each stays within Safaricom's enforced cap.
Select your Company.
Enable Auto Reconcile C2B if you want incoming C2B payments submitted and reconciled without manual intervention.
Check Sandbox for testing. Uncheck it for live payments — this switches all API calls to the Safaricom production endpoint automatically.
Click Save.
On save, iVendNext automatically creates a Payment Gateway, a Payment Gateway Account, and a Mode of Payment named Mpesa-[Your Gateway Name]. These appear as standard tender options across POS Invoice, Sales Invoice, and Payment Request forms.
How to Register the C2B Callback URL
For incoming paybill or till payments to be captured automatically, you must register your callback URL with Safaricom. Do this once per shortcode.
Go to Mpesa C2B Payment Register URL and click New.
Enter the Business Shortcode matching your Mpesa Settings record.
Select your Company and the Mode of Payment that was created by your Mpesa Settings.
Click Register URL.
iVendNext builds the callback URL from your site address and submits it to Safaricom's Daraja API. Once registered, all incoming payments to that shortcode are delivered to iVendNext Desk automatically.
Features
C2B Payment Collection
iVendNext provides three entry points for triggering an STK Push — the payment prompt sent directly to the customer's phone.
From POS Invoice: In the POS payment panel, select the M-Pesa mode of payment. A dialog appears for the customer's phone number. Enter it and click Send STK Push. The customer receives a prompt on their phone, enters their M-Pesa PIN, and the POS confirms the payment in real time. Phone numbers beginning with 0 are automatically converted to the 254XXXXXXXXX format before any API call is made.
From Sales Invoice: On any Sales Invoice with an M-Pesa payment row, click Initiate STK Push next to the row. The system validates that the invoice currency is KES and that an outstanding amount exists before sending the request. This lets your accounts team accept M-Pesa on non-POS invoices without switching to a separate system.
From Payment Request: A Pay via Mpesa button on Payment Request forms triggers an STK Push with conversion rate handling for invoices in other currencies.
Each STK Push creates a Mpesa Express Request record that tracks the full lifecycle of the transaction. Key fields on this record include Phone Number, Amount, Merchant Request ID, Checkout Request ID, Transaction ID, Status (Pending, Completed, or Failed), Result Code, and Result Description. The form refreshes automatically when Safaricom delivers the callback — no manual reload is needed to confirm whether the customer paid.
If a single invoice exceeds the Transaction Limit set on your Mpesa Settings, iVendNext automatically splits the total into multiple STK Push requests, each within Safaricom's per-transaction cap. For example, an invoice of KES 1,000 with a limit of KES 500 generates two separate requests of KES 500 each. The customer receives a prompt for each.
Incoming C2B via Webhook: When a customer pays directly to your shortcode, Safaricom posts a webhook to your registered URL. iVendNext auto-creates a Mpesa C2B Payment Register record with Trans ID, Trans Amount, MSISDN, Company, Currency, and Mode of Payment set from your registered URL configuration. Submitting the record with Submit Payment enabled creates a Payment Entry against the customer and reduces the outstanding invoice balance. If Auto Reconcile C2B is on, this happens without any manual step.
Duplicate protection is built in: if a payment arrives with a transaction ID matching an existing Mpesa Express Request, iVendNext blocks the insert to prevent double-counted entries.
The Mpesa C2B Payment Register record stores all incoming payment details: Trans ID, Trans Time, Trans Amount, Bill Ref Number, MSISDN, First Name, Last Name, Customer, Company, Currency, Mode of Payment, and Posting Date. You can link the record to a specific customer and, once linked, submit it to automatically generate a reconciled Payment Entry. If you prefer a fully hands-off workflow, enabling Auto Reconcile C2B on your Mpesa Settings means the system submits every incoming C2B payment the moment the webhook is received.
Monitoring and Reports
Transaction Status Check: On any Mpesa Settings record, enter a Transaction ID and click Check Transaction Status to query Safaricom for its current state. The result is delivered as a real-time notification to your screen.
Account Balance Query: Click Get Account Balance on Mpesa Settings to fetch your working account balance from Safaricom. The result is stored in the Account Balance field in structured JSON format.
Three built-in reports are available: STK Push Request Status, C2B Payment Summary Group by Customer, and C2B Reconciliation Report. Every outbound API call and every inbound Safaricom callback is logged automatically in Integration Request, giving you a complete audit trail of all M-Pesa payment activity.