Paying an Invoice via M-PESA
The system supports M-PESA as a payment method for invoices, allowing payers to complete payments directly from their M-PESA account via an STK Push prompt sent to their phone. Once the payment is confirmed by Safaricom, the invoice is automatically marked as paid and a receipt number is generated.
M-PESA is available only for Kenya-based accounts where the plugin has been enabled and credentials have been configured.
Before You Begin
- M-PESA must be enabled and configured with valid Daraja credentials before it appears as a payment option. See the “Setting Up M-PESA as a Payment Method” guide.
- The payer must have an active M-PESA account registered to a Kenyan phone number in the format
254XXXXXXXXX. - M-PESA payments are processed for the full outstanding invoice balance. Partial payments are not supported in the standard flow.
Steps to Pay an Invoice via M-PESA
- Open the invoice you want to pay and click “Add Payment.”
- From the available payment methods, select M-PESA.
- A popup appears with a phone number field — enter the payer’s M-PESA registered phone number in the format
254XXXXXXXXX(e.g. 254712345678). - The phone number must always be entered manually. No pre-fill from the client record is applied. If the format is incorrect the message appears: “Please enter a valid M-PESA phone number in the format 254XXXXXXXXX.”
- Review the instruction displayed on screen: “You will receive an M-PESA prompt on your phone. Enter your PIN to complete the payment.”
- Click “Submit” — the popup closes and the payment request is sent to Safaricom.
- A waiting screen appears showing a countdown timer with the status “Waiting…” — keep this screen open while the payment is being processed.
- On your phone, an M-PESA STK Push prompt appears — enter your M-PESA PIN to authorize the payment.
- Once Safaricom confirms the payment, the screen updates and you are redirected to the payment success page showing: “Payment successful. Your M-PESA receipt number is [receipt number].”
Payment Amount
The payment amount is automatically set to the full outstanding invoice balance, rounded up to the nearest whole Kenyan Shilling (e.g. KES 1,500.50 is sent as KES 1,501).
What Happens After a Successful Payment
Once the payment is confirmed by Safaricom, the invoice status changes to Paid and a payment record is created containing the M-PESA receipt number, the masked payer phone number (e.g. 254•••••••78), the amount paid in KES, the payment timestamp, and the payment method. The payment is visible in the invoice’s Payment History tab, and an accounting journal entry is created following the same rules as all other payment methods.
If the Payment Does Not Complete
The waiting screen remains open while the system checks the payment status. If no confirmation is received within 60 seconds, the system automatically queries Safaricom for the latest status and the screen updates to “Checking…” — the system retries every 10 seconds for a maximum of 3 retries.
The outcome of the payment attempt determines what happens next. If you cancelled the payment on your phone, the message appears: “You cancelled the M-PESA payment request. Please try again if you wish to complete the payment.” If the request timed out without a response, the message appears: “The M-PESA payment request timed out. Please try again.” If your M-PESA account has insufficient funds, the message appears: “Your M-PESA account has insufficient funds. Please top up and try again.” If there is already an active M-PESA session on the phone, the message appears: “There is already an active M-PESA session on this phone. Please complete or dismiss it and try again.” If the M-PESA service is temporarily unavailable, the message appears: “M-PESA is temporarily unavailable. Please try again in a few minutes.” For any other unexpected error, the message appears: “The payment could not be completed. Please try again or use a different payment method.”
In all of the above cases a “Try Again” button is shown, returning you to the phone number entry step to restart the payment.
Two situations do not offer a retry option. If your PIN was entered incorrectly too many times, the message appears: “Your M-PESA PIN was entered incorrectly too many times. Please try again later or contact Safaricom.” If the payment status could not be confirmed after all retries are exhausted, the message appears: “We could not confirm your payment status. Please check your M-PESA messages. If the amount was deducted, contact support with your receipt number.” In this case the invoice remains as Pending — it is not marked as Paid or Failed. Do not attempt to pay the invoice again until you have verified with Safaricom whether the amount was deducted from your M-PESA account.
Notes
- The waiting screen remains open until a definitive outcome is reached — it does not close automatically.
- M-PESA does not appear as a payment option if the plugin is disabled or credentials are not configured.
- The phone number entered is always masked in the payment record — only the last 2 digits are visible.