Configuration
All M-Pesa integration settings are managed through the Mpesa Settings DocType. This is the central configuration record for each API type you plan to use. You will typically create one Mpesa Settings record per API type (Mpesa Express, C2B, or B2C).
Mpesa Settings Doctype
Accessing Mpesa Settings
You can reach Mpesa Settings in two ways:
- Open the Mpesa workspace from the sidebar and click Mpesa Settings.
- Use the Awesome Bar (
Ctrl + G/Cmd + G) and search forMpesa Settings.
Creating an Mpesa Settings Record
Click New to create a configuration record. Fill in the fields described below.
API Type
Select the payment service this record will configure:
- Mpesa Express: For STK Push (payment prompts to customers)
- C2B: For receiving payments from customers via Paybill or Till
- B2C: For disbursing payments to employees or suppliers
Each API type may require different credentials. You can create multiple records one for each API type.
Field Reference
| Field | Description |
|---|---|
| API Type | The Mpesa service this record configures: Mpesa Express, C2B, or B2C. |
| Consumer Key | A unique key from Safaricom used to authenticate API requests. |
| Consumer Secret | A secret paired with the Consumer Key to secure API access. |
| Business Shortcode | Your business identifier in the M-Pesa system (Paybill or Till number). |
| Online PassKey | Used exclusively for Mpesa Express (STK Push) transactions. |
| Till Number | Required for C2B payments where customers pay to a Till number. |
| Initiator Name | The API Operator username configured in the M-Pesa Org Portal. Required for B2C and Transaction Status. |
| Initiator Password | The password paired with the Initiator Name. This is encrypted to generate the Security Credential. |
| Security Credential | An encrypted credential used in B2C transactions. Generated from the Initiator Password and the Mpesa Public Key Certificate. |
Mode of Payment
After saving an Mpesa Settings record, you must link it to a Mode of Payment in ERPNext. This is how the system knows which Mpesa configuration to use when a payment is initiated from a Sales Invoice, Sales Order, or B2C disbursement.
To link:
- Open Accounts > Mode of Payment.
- Create or open the relevant Mode of Payment (e.g., "M-Pesa").
- In the Payment Gateway Account section, select the Mpesa Settings record.
Public Key Certificate
For B2C transactions, the app encrypts the Initiator Password using Safaricom's public key certificate. The Mpesa Public Key Certificate DocType stores these certificates for both environments:
- Sandbox Certificate: Used during development and testing.
- Production Certificate: Used for live transactions.
Navigate to Mpesa Public Key Certificate and ensure the correct certificate is saved before attempting B2C disbursements. The certificates are available from the Safaricom Developer Portal.
Auto Reconcile C2B Payments
Within Mpesa Settings, there is an option labeled Auto Reconcile C2B Payments. When enabled, the system will automatically attempt to match incoming C2B payments to outstanding invoices as soon as the payment record is submitted. If no matching invoice is found, it applies the payment to the customer's oldest outstanding invoices using FIFO (First-In First-Out) logic.
This option is recommended for businesses with a predictable invoice reference flow. Disable it if you prefer to manually review and match payments.
Token Management
Access tokens are generated automatically using the Consumer Key and Secret and are stored within the Mpesa Settings record. The app reuses a valid token for all requests until it expires, at which point a new one is requested. No manual token management is required.