The iVendNext Kenya M-Pesa Integration is configured through a single settings record per Safaricom shortcode. Creating that record wires up all the payment infrastructure needed — the payment gateway, mode of payment, and API connection — in one save action. Once live, the integration provides on-demand tools for querying transaction status and account balances, and three built-in reports give finance teams and store managers full visibility into M-Pesa payment activity. This article covers the configuration process and the monitoring and reporting tools available within iVendNext Desk.

---

Mpesa Settings: One Record Per Shortcode

The Mpesa Settings DocType is the central configuration record for each M-Pesa gateway. Each Safaricom shortcode — whether a Till Number or PayBill shortcode — requires its own settings record. Multiple records can coexist for businesses operating more than one shortcode or till.

Creating a New Mpesa Settings Record

1. Go to Mpesa Settings and click New.

2. Enter a unique Payment Gateway Name (for example, Main Till or Online Payments). This name is appended to the Payment Gateway, Payment Gateway Account, and Mode of Payment that are created automatically on save.

3. Set API Type to MPesa Express for C2B (collecting payments from customers).

4. Enter the Consumer Key and Consumer Secret from your Safaricom Daraja developer portal.

5. Enter the Business Shortcode — the Safaricom-assigned identifier for your PayBill or Till.

6. Enter the Till Number and Online Passkey.

7. Set the Transaction Limit — the maximum KES amount allowed per single STK Push request. Invoices above this amount are split into multiple requests automatically.

8. Select the Company.

9. Enable Auto Reconcile C2B if incoming C2B payments should be submitted and reconciled without manual intervention.

10. Check Sandbox for testing against Safaricom's sandbox environment. Uncheck it when going live.

11. Click Save.

On save, iVendNext automatically creates three records: a Payment Gateway named Mpesa-[Your Gateway Name], a Payment Gateway Account linked to your company's bank account, and a Mode of Payment with the same name. These appear as standard tender options on POS Invoice, Sales Invoice, and Payment Request forms — M-Pesa is treated as a native iVendNext payment method from this point forward.

---

Sandbox and Production Switching

iVendNext supports safe testing against Safaricom's sandbox environment before going live. The Sandbox checkbox on Mpesa Settings controls which Safaricom endpoint all API calls are directed to:

• Sandbox checked: All calls go to sandbox.safaricom.co.ke. Test credentials and sandbox transactions are used. No real money moves.

• Sandbox unchecked: All calls go to api.safaricom.co.ke. Live credentials must be in place. Real transactions are processed.

Switching environments is a single checkbox change followed by a save. There is no need to create a second settings record for testing — the same record serves both environments. When switching to production, the Consumer Key, Consumer Secret, and Online Passkey must be updated to production credentials from the Daraja portal at the same time.

Transaction Status Check

For any historical transaction where the outcome is uncertain — for example, a payment where Safaricom delivered an ambiguous callback or where the cashier suspects a duplicate — iVendNext can query Safaricom directly for the current status.

On any Mpesa Settings record, enter a Transaction ID in the Transaction Status field and click Check Transaction Status. iVendNext sends a query to the Safaricom Daraja transaction status endpoint. The result is returned as a real-time notification on screen without navigating away from the settings record. This allows IT administrators and store managers to resolve payment disputes quickly without contacting Safaricom support or logging into the Daraja portal.

Account Balance Query

The Get Account Balance button on Mpesa Settings allows the business to check the current M-Pesa working account balance for the configured shortcode at any time. iVendNext sends a balance query to Safaricom, and the response is stored in the Account Balance field as structured JSON, showing the working account balance in KES.

This is an on-demand query rather than a live dashboard feed. The balance is updated each time the button is clicked. It is useful for IT administrators and finance managers who need a quick sanity check on the working account without logging into a separate banking portal.

Built-In Payment Reports

Three Script Reports are included with the iVendNext Kenya M-Pesa Integration, accessible from the Mpesa module in iVendNext Desk. All three support date range filters and can be exported.

STK Push Request Status

This report gives a date-range view of all STK Push requests initiated from POS Invoice, Sales Invoice, or Payment Request forms. For each request it shows the phone number, amount, merchant request ID, checkout request ID, and final status (Pending, Completed, or Failed). Store managers use this report to audit daily STK Push activity and identify failed requests that may need follow-up with the customer.

C2B Payment Summary Group by Customer

This report aggregates incoming C2B payments by customer over a selected date range. It shows the total amount received per customer, the number of transactions, and the associated modes of payment. Finance teams use this report to understand which customers are paying via M-Pesa and to identify any customers with large unmatched balances.

C2B Reconciliation Report

This report compares incoming C2B Payment Register records against the Payment Entries created from them. It highlights records that have been received but not yet submitted for reconciliation, and those where a Payment Entry exists but the invoice balance has not been fully reduced. This report is the primary tool for the daily reconciliation review — it makes it immediately visible which incoming payments are still unprocessed at any point during the day.

Full API Audit Logging

Every outbound API call to Safaricom and every inbound webhook callback received from Safaricom is logged automatically in iVendNext's Integration Request DocType. This includes STK Push requests, C2B webhook receipts, transaction status queries, and account balance queries.

Each Integration Request log entry records the request payload, the response payload, the HTTP status, and a timestamp. This gives the IT administrator and finance team a complete, queryable audit trail of all M-Pesa activity in iVendNext — nothing happens outside the system, and no payment event goes unlogged. The audit log is essential for resolving disputes, supporting external audits, and diagnosing integration issues with Safaricom.