STK Push Payments

The iVendNext Kenya M-Pesa Integration enables cashiers and finance teams to collect customer payments directly through Safaricom's STK Push mechanism — without handling cash or using any external portal. When a cashier triggers an STK Push, the customer's phone receives an instant payment prompt. The customer enters their M-Pesa PIN, Safaricom confirms the transfer, and iVendNext records the payment automatically. The entire flow happens within iVendNext Desk with no manual data entry after the phone number is entered.

What Is an STK Push?

STK Push (also known as Lipa Na M-Pesa Online or M-Pesa Express) is a Safaricom service that sends a payment request directly to a customer's phone. The customer sees the merchant name, amount, and a PIN prompt. Once they approve, Safaricom processes the transfer and notifies iVendNext through a callback. Unlike paybill or till payments where the customer initiates the payment, STK Push is initiated from the business side — the cashier or accountant triggers it from inside iVendNext.

Three Entry Points for STK Push

iVendNext provides three places from which an STK Push can be triggered, covering POS counter transactions, back-office sales invoices, and payment requests.

From POS Invoice

At the counter, a cashier adds items to the customer's order in the POS. When selecting M-Pesa as the mode of payment in the payment panel, a dialog appears asking for the customer's phone number. The cashier enters the number and clicks Send STK Push. The customer's phone immediately shows the amount and a PIN prompt. Once the customer approves, the POS updates with a confirmation in real time and the bill is closed.

Phone numbers beginning with 0 are automatically converted to the 254XXXXXXXXX international format before the API call is made. If the number is in an unrecognised format, the system rejects it with a clear error message before any request is sent to Safaricom.

From Sales Invoice

For transactions managed outside the POS — such as credit sales or invoices raised by the accounts team — the STK Push is available directly on the Sales Invoice form. When an M-Pesa payment row is present on a Sales Invoice, an Initiate STK Push button appears next to that row.

Before the button becomes active, iVendNext performs two checks: the invoice currency must be KES, and an outstanding balance greater than zero must exist. These checks prevent accidental STK Push requests on already-settled invoices or on invoices in unsupported currencies. Only KES transactions are accepted; invoices in other currencies display a validation message asking the user to select a different payment method.

From Payment Request

A Pay via Mpesa button is available on Payment Request forms. This entry point supports conversion rate handling, which means it can accommodate invoices originally raised in other currencies where a KES equivalent has been calculated. This is useful when customers need to pay outstanding requests that originated in multi-currency workflows.

The Mpesa Express Request Record

Every STK Push initiated from any of the three entry points creates an Mpesa Express Request record in iVendNext Desk. This record is the single source of truth for the full lifecycle of that transaction. It is created the moment the request is submitted and updated automatically when Safaricom delivers its callback — no manual refresh is needed.

Key fields on this record include:

• Phone Number — the customer's number in 254XXXXXXXXX format

• Amount — the payment amount in KES

• Merchant Request ID — Safaricom's identifier for the request, received on acknowledgement

• Checkout Request ID — Safaricom's session identifier for the STK Push

• Transaction ID — the final M-Pesa transaction reference, populated on completion

• Status — Pending while awaiting callback, Completed on successful payment, Failed if rejected or timed out

• Result Code and Result Description — Safaricom's response codes explaining the outcome

When Safaricom delivers its callback, iVendNext publishes a real-time event that refreshes the Mpesa Express Request form automatically. There is no need to leave and return to the form to confirm whether the customer has paid.

Transaction Amount Splitting

Safaricom enforces a maximum per-transaction amount on STK Push requests. This threshold is configured in the Transaction Limit field on the Mpesa Settings record for each shortcode.

When a single invoice amount exceeds this limit, iVendNext automatically splits the total into multiple STK Push requests so that each request stays within the cap. For example, if the Transaction Limit is KES 500 and the invoice total is KES 1,200, iVendNext generates three separate requests — KES 500, KES 500, and KES 200. The customer receives a phone prompt for each request and approves them individually. No manual intervention from the cashier or accountant is required — the split is applied automatically before any request is sent to Safaricom.

Phone Number Validation

Phone number formatting is enforced before any API call reaches Safaricom. Numbers beginning with 0 are automatically sanitised to the 254XXXXXXXXX format. Numbers that do not match a recognised Kenyan mobile format are rejected immediately with the message: "Invalid phone number format. Please ensure it is in the correct format, e.g., 254712345678." This validation happens before the request is dispatched, preventing wasted API calls at busy checkout counters and giving the cashier an immediate prompt to correct the number.

KES Currency Enforcement

M-Pesa is a KES-only payment network. iVendNext enforces this at the form level. Any attempt to initiate an STK Push on an invoice or payment request in a non-KES currency is blocked before the API call is made. The system checks whether the invoice currency or the company's default currency is KES. If neither is KES, the user sees a validation message: "Please select another payment method. Mpesa does not support transactions in currency 'USD'." (or whichever currency applies). This prevents accidental selection of M-Pesa on foreign-currency transactions and ensures Safaricom never receives an invalid currency in the requested payload.

Who Uses This Feature

Cashiers use the POS Invoice entry point as part of the standard checkout flow — it replaces cash handling with a phone prompt and eliminates the need to verify a payment SMS manually. Accountants use the Sales Invoice entry point to accept M-Pesa on credit sales or outstanding balances without switching to a separate system. Finance managers use the Payment Request entry point for customer collections tied to longer billing cycles. In all cases, the workflow stays entirely within iVendNext Desk, and every transaction is recorded and traceable from the moment the STK Push is initiated.