Frappe Mpsa Payments

bench get-app https://github.com/navariltd/frappe-mpsa-payments

[![Listed on Frappe Gems](https://frappegems.com/api/method/frappe_gems.seo.badge?app=navariltd%2Ffrappe-mpsa-payments)](https://frappegems.com/gems/apps/navariltd/frappe-mpsa-payments)

📲 Frappe Mpesa Payments

Frappe Mpesa Payments is a custom Frappe application that integrates with Safaricom's Daraja API. It is built to extend ERPNext enabling seamless mobile money payments from customers, and payment disbursements to suppliers and employees. Hence it implements the following APIs: Mpesa Express (STK Push), C2B (Customer to Business), B2C (Business to Customer) and Transaction Status (Query status of payment).

---

Table of Contents

• 📲 Frappe Mpesa Payments
• 🚀 Project Overview
• Supported APIs:
  • 1. ✅ Mpesa Express (STK Push)
  • 2. ✅ C2B (Customer to Business)
  • 3. ✅ B2C (Business to Customer)
  • 4. ✅ Transaction Status (Query status of payment)
• 🛠️ Installation
  • ✅ Dependencies
  • ☁️ Managed Hosting Frappe Cloud
  • 🧑🏿‍💻 Self Hosting
• ⚙️ Configuration
  • Mpesa Settings
• 🤵🏿 Usage Guide
  • 1. 🔁 Trigger STK Push (Mpesa Express)
  • 2. 📥 Receive C2B Payments
    • Notes:
    • FAQs: What happens when Registration Fails?
  • 3. 💸 Disburse B2C Payments (Business to Customer)
    • 🧾Accounting Entries
    • Use Cases
  • 4. 🔍 Mpesa Payment Reconciliation
  • 5. ❓Query Transaction Status
    • Use Cases:
• Key DocTypes
• 🔐 Security
• 🛠️ Troubleshooting

---

🚀 Project Overview

With the growth of mobile money payments and digital cash transfers, this app was built to enable Kenyan businesses to automate and streamline payment collection, salary disbursement, and transaction tracking through Safaricom Mpesa — without leaving their ERPNext system.

Supported APIs:

1. ✅ Mpesa Express (STK Push)

• This is a feature that allows suppliers/vendors to initiate a payment prompt on a customer's phone, prompting them to enter their M-Pesa PIN to authorize the transaction. It's a convenient and secure way for customers to pay, as it eliminates the need for customers to remember paybill/account numbers. It also reduces the time taken to receive payment

  Use Cases

  • Request payment from:

    1. Sales Invoice (Credit)

    

    2. Sales Order

    

    3. POS (Point of Sale)

    

    4. Webshop (E-Commerce)

    

    5. Sales Invoice (of type POS)

      flowchart LR
      A[Draft Sales Invoices of type POS]
      A -->|STKPush onExisting Row| C[Initiate STKPush for Payment Row]
      A -->|STKPush for Outstanding| D[Calculate Outstanding]
      C --> E[Update Transaction No. on Row]
      D --> F[Initiate STKPush for Selected Amount]
      F --> G[Add New Payment Row]
  

2. ✅ C2B (Customer to Business)

• In ERPNext, C2B integration allows you to automatically receive and reconcile payments made by customers through M-Pesa to your Paybill or Till number. These payments are linked to payment entries, enabling real-time updates of outstanding balances and reducing manual data entry.

  

3. ✅ B2C (Business to Customer)

• M-Pesa B2C integration enables businesses disburse payments directly to customers, employees or suppliers directly to their M-Pesa accounts. Through seamless API integration, ERPNext users can initiate bulk payments such as salaries, expense claims, supplier payouts or even loans directly from the system. This enhances efficiency, reduces errors and ensures secure, traceable disbursements, all while maintaining accurate financial records within ERPNext.

  Use Cases

  • Disburse payments to suppliers

    

  • Disburse to employees

    

  • Disburse Loans

    

4. ✅ Transaction Status (Query status of payment)

• In the case a customer has paid via M-Pesa but the payment is not reflecting in your ERPNext instance, this API becomes essential. This integration allows ERPNext to query Safaricom's systems using the transaction receipt number and retrieve real-time details such as transaction status (Success, Failed or Pending). It helps resolve issues caused by network delays, missed callbacks, or unregistered C2B transactions by enabling manual verification.

  

---

🛠️ Installation

✅ Dependencies

• Frappe Framework
• ERPNext
• Optional Frappe HR For Salary Disbursements
• Optional Frappe Lending For Loans Disbursements
• Valid Daraja API credentials
• M-Pesa Org Portal Access
• Publicly accessible domain (for webhook callbacks) N/B Must be https://

☁️ Managed Hosting Frappe Cloud

1. Login to your Frappe Cloud account.
2. Navigate to your Sites/Bench Groups dashboard.
3. Go to the Apps tab and select + Install APP / + Add APP.
4. Search for Frappe Mpesa Payments application in the Marketplace section.
5. Or select Add from Github then add this github url https://github.com/navariltd/frappe-mpsa-payments.git.
6. Install Application or Fetch Branches.

🧑🏿‍💻 Self Hosting

1. Ensure you have a working Frappe and ERPNext instance
2. Clone this repository into your Frappe bench apps directory.

bench get-app https://github.com/navariltd/frappe-mpsa-payments.git

3. Install the app into your site

bench --site [your-site-name] install-app frappe_mpsa_payments

4. Reload and restart the bench to reflect changes:

bench restart

---

⚙️ Configuration

Mpesa Settings

In the Mpesa Workspace or using the Awesome Search navigate to Mpesa Settings This DocType is central to configuring Safaricom's Daraja API credentials, it is the entry point of the various Mpesa payment services (Mpesa Express, C2B, and B2C). It holds the necessary credentials and identifiers for authentication and payment initiation.

To get these credentials you need to have an account on Safaricom Developer Portal and have a live/prod application that corresponds to the Business Shortcode you own (Paybill/Till Number). Contact M-Pesa Business or Safaricom API Support for help in setting this up.

1. API Type: Select the type of Mpesa API integration you’re setting up (Mpesa Express, C2B, or B2C).
2. Consumer Key: A unique key provided by Safaricom to authenticate API calls.
3. Consumer Secret: A secret code paired with the Consumer Key to secure API access.
4. Security Credential: Encryption credential used for additional security, particularly in B2C transactions.
5. Till Number: Identifier for C2B payments, where customers make payments directly to a till.
6. Business Shortcode: A unique code used to identify your business account in the Mpesa system.
7. Online PassKey: An additional authentication key, specifically for initiating Mpesa Express (STK Push) transactions.
8. Initiator Name: Operator name for API Operator in the Mpesa Org Portal.
9. Initiator Password: Password paired with the Initiator Name.

---

🤵🏿 Usage Guide

1. 🔁 Trigger STK Push (Mpesa Express)

Mpesa Express (STK Push) is initiated through the Payment Request DocType in ERPNext.

🔧 How it works:

1. Create a new Payment Request either from Sales Invoice or Sales Order.
2. Select a Mode of Payment that is associated with an Mpesa Settings record.
3. Since the Payment Channel is Phone
4. Enter the Customer's Phone Number in the To field
5. Save the Payment Request

👉🏿 Once saved, the system automatically triggers an STK Push request to the customer. When the customer finishes the transaction i.e., enters pin the Payment Request is completed and a Payment Entry created against the transaction.

Can be used from:

• Sales Invoice
• Sales Order
• POS
• Webshop

https://github.com/user-attachments/assets/260359a0-13a0-40fa-9f3c-412acdac6464

2. 📥 Receive C2B Payments

C2B (Customer to Business) integration enables your system to receive and log incoming payments from customers in real-time.

🔧 How it Works

1. Register URLs:

• Navigate to Mpesa C2B Payment Register URL.
• Link to your configured Mpesa Settings and its Mode of Payment.
• Save the Document.
• The Register Status should change to Success to indicate the callbacks have been registered.

2. Payment Logging:

• Ensure the callbacks have been registered successfully.
• Once a customer pays via your PayBill/Till, Daraja sends a callback to your registered URLs.
• These callbacks are recorded in the Mpesa C2B Payment Register.

https://github.com/user-attachments/assets/18e790f7-5a23-472f-a9fc-ffaf0ee704ca

Notes:

• Smart Matching Logic:
  • If Customer inputs a Sales Invoice Number or Customer Name/Number(unique identifier of the customer in ERPNext), as the Account Number when making a Paybill payment, Daraja API will send this information as BillRefNumber in the callback.
  • If this information matches the Sales Invoice Number or Customer Name/Number in the system, then the Customer field in the Mpesa Payment Register is automatically filled.
• Auto-Reconciliaton Logic:
  • In Mpesa Settings there is an option Auto Reconcile C2B Payments.
  • If this is checked then once you submit the Mpesa Payment Register Record it will try to match an invoice if no invoice is found then a reconciliation of the customer's outstanding invoices will be performed automatically using FIFO (First-In First-Out) logic.

FAQs: What happens when Registration Fails?

Problem	Solution
URLs are already registered.	Login to Daraja Portal. Access the Self Services tab and delete the previously registered urls
Bad Request	Confirm everything is set up in the Mpesa Settings and the credentials are correct
Invalid Access Token	Make sure the Consumer key and secret are correctly