Mpesa Express (STK Push)

Mpesa Express, commonly referred to as STK Push (Sim Toolkit Push), is a payment method that sends a payment prompt directly to a customer's phone. The customer receives a pop-up on their screen asking them to enter their M-Pesa PIN to complete the payment. This eliminates the need for the customer to navigate a Paybill menu manually.

How It Works

1. A Payment Request is created in ERPNext linked to a Sales Invoice, Sales Order, or POS session.
2. The Mode of Payment on the Payment Request is set to one connected to an Mpesa Express Settings record.
3. The customer's phone number is entered in the To field.
4. Once the Payment Request is saved, the system sends an STK Push to the customer's phone via the Daraja API.
5. The customer enters their M-Pesa PIN on their phone to authorize the payment.
6. Safaricom sends a callback to your server confirming the transaction.
7. The Payment Request is automatically marked as completed and a Payment Entry is created against the transaction.

Supported Entry Points

STK Push can be triggered from the following documents in ERPNext:

• Sales Invoice (Credit) Sales Invoice
• Sales Order Sales Order
• POS (Point of Sale) Point Of Sale (POS)
• Webshop (E-Commerce): for online orders placed through the ERPNext Webshop WebShop
• Sales Invoice of type POS Sales Invoice (Type POS)

Step-by-Step Guide

Step 1: Ensure Mpesa Settings is Configured

Confirm that an Mpesa Settings record exists with API Type set to Mpesa Express and that it is linked to a Mode of Payment.

Step 2: Open the Source Document

Open the relevant Sales Invoice, Sales Order, or POS session in ERPNext.

Step 3: Create a Payment Request

From the document's action menu, select Create > Payment Request (the exact label depends on the document type).

Step 4: Configure the Payment Request

Fill in the following fields:

Step 5: Save the Payment Request

Click Save. The system will immediately trigger the STK Push to the customer's phone number.

Step 6: Customer Authorizes Payment

The customer receives a prompt on their phone displaying the amount and the business name. They enter their M-Pesa PIN to authorize.

Step 7: Automatic Completion

Once the customer completes the transaction, Safaricom sends a callback to your server. The Payment Request status updates to Paid and a Payment Entry is created automatically.

What Happens If the Customer Does Not Respond?

If the customer dismisses the prompt or does not respond, the STK Push request will time out. The Payment Request will remain in a pending state. You can resend the request by saving the Payment Request again or creating a new one.

Phone Number Format

Phone numbers must be entered in the international format without the leading zero or plus sign: