📲 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](https://frappe.io/framework) - [ERPNext](https://frappe.io/erpnext) - Optional [Frappe HR](https://frappe.io/hr) For Salary Disbursements - Optional [Frappe Lending](https://frappe.io/lending) For Loans Disbursements - [Valid Daraja API credentials](https://developer.safaricom.co.ke/) - [M-Pesa Org Portal Access](https://org.ke.m-pesa.com) - Publicly accessible domain (for webhook callbacks) N/B Must be _https://_ ### ☁️ Managed Hosting [Frappe Cloud](https://frappecloud.com/) 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](https://frappecloud.com/marketplace/search) 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](https://developer.safaricom.co.ke/) and have a live/prod application that corresponds to the Business Shortcode you own (Paybill/Till Number). Contact [M-Pesa Business](mailto:m-pesabusiness@safaricom.co.ke) or [Safaricom API Support](mailto:api@safaricom.co.ke) for help in setting this up.

2. API Type: Select the type of Mpesa API integration you’re setting up (Mpesa Express, C2B, or B2C).

3. Consumer Key: A unique key provided by Safaricom to authenticate API calls.

4. Consumer Secret: A secret code paired with the Consumer Key to secure API access.

5. Security Credential: Encryption credential used for additional security, particularly in B2C transactions.

6. Till Number: Identifier for C2B payments, where customers make payments directly to a till.

7. Business Shortcode: A unique code used to identify your business account in the Mpesa system.

8. Online PassKey: An additional authentication key, specifically for initiating Mpesa Express (STK Push) transactions.

9. Initiator Name: Operator name for API Operator in the Mpesa Org Portal.

10. 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:**

2. Create a new Payment Request either from Sales Invoice or Sales Order.

3. Select a Mode of Payment that is associated with an Mpesa Settings record.

4. Since the Payment Channel is Phone

5. Enter the Customer's Phone Number in the To field

6. 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**

2. 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.

3. 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?

3. 💸 Disburse B2C Payments (Business to Customer)

Use this feature to send money directly to employees or suppliers via **Mpesa B2C** integration. **🔧 How It Works:**

2. Navigate to the B2C Payment Disbursement using the Awesome Search

3. Fill in the mandatory details:

• Company -> Will be autofilled from Session Defaults

• Mode of Payment -> Select one associated with Mpesa Settings

• Party Type

• Transaction to Pay Against

• Account Paid From

• Account Paid To

4. Use the Get References button to fetch outstanding/unpaid records.

• Use filters to fetch outstanding entries.

• The entries fetched are populated in the References child table.

• Set Mobile Numbers and Allocated Amount if not fetched or auto-set.

• Optional: Set or edit Paid Amount to allow auto-allocation of allocated_amounts.

5. Submit the document once you feel everything is okay.

• This initiates a Daraja B2C API call for each reference.

• Displays real-time notification messages showing (Success, Failure) status for each reference.

6. Automatic Status Updates: The main document's status updates based on payment_status on reference outcomes:

   • ✅ Paid: All references paid

   • ⚠️ Party Paid: Some paid, others failed

   • ❌ Failed: All references failed

   • 🕛 Not Initiated: No payments attempts made

8. Failed Payments? A Retry Failed Payments button is displayed to attempt the payment again for failed references.

https://github.com/user-attachments/assets/c37f45a0-1198-43f8-a71a-ae2dcb9ead51

🧾Accounting Entries

• Salary Slip → A Journal Entry of type Bank Entry is created.

• For all others (PI/PO/Employee Advance/Expense Claim) → A Payment Entry is created per reference.

• Loan -> A Loan Disbursement is created.

Use Cases

• Employee salary disbursements

• Supplier/Vendor payments

• Employee Expense and Advance reimbursements

• Employee/Customer/Member Loan disbursements

4. 🔍 Mpesa Payment Reconciliation

The **Mpesa Payment Reconciliation** tool simplifies matching incoming Mpesa payments with outstanding invoices. **🔧 How It Works:**

2. Navigate to Mpesa Payment Reconciliation in the Mpesa Workspace or using Awesome Search.

3. Select the Customer and Company to filter relevant transactions.

4. Click the Get Unreconciled Entries and the tool displays:

• A list of Draft Mpesa Payments from the Mpesa C2B Payment Register.

• A list of Unpaid/Outstanding Invoices for the selected customer.

5. Optional Filters can be set in the Filters Section

6. Allocate the invoices against the draft Mpesa Payments

https://github.com/user-attachments/assets/19ba1eee-e61c-403f-9874-ca3a9219fe7f

5. ❓Query Transaction Status

This feature allows you to check the status of an Mpesa transaction using its **Transaction ID**. **🔧 How It Works:**

2. Open the Mpesa C2B Payment Register from the Mpesa Workspace.

3. Use the Check Transaction Status button at the top of the page.

4. Select the Mpesa Settings this will contain the Business Shortcode to be used

5. Enter the Transaction ID provided by the Customer.

6. Optional **Remarks can also be included.

7. Submit and wait for the response.

8. The system will:

• If the transaction is successful and no record exists, create a new entry in the Mpesa C2B Payment Regiter

• If the transaction is successful and record already exists, display the current status and inform you of the existing record.

• If the transaction failed, it will notify you accordingly.

https://github.com/user-attachments/assets/c31fe0fc-6843-4ba6-ac6a-504a60257964

Use Cases:

• Verify delayed or failed transactions.

• Add missing transactions to the system for reconciliation.

Key DocTypes

Mpesa Settings

This DocType is central to configuring Safaricom's Daraja API credentials, allowing for seamless integration of various Mpesa payment services (Mpesa Express, C2B, and B2C). This DocType holds the necessary credentials and identifiers for authentication and payment initiation.

2. API Type: Select the type of Mpesa API integration you’re setting up (Mpesa Express, C2B, or B2C).

3. Consumer Key: A unique key provided by Safaricom to authenticate API calls.

4. Consumer Secret: A secret code paired with the Consumer Key to secure API access.

5. Security Credential: Encryption credential used for additional security, particularly in B2C transactions.

6. Till Number: Identifier for C2B payments, where customers make payments directly to a till.

7. Business Shortcode: A unique code used to identify your business account in the Mpesa system.

8. Online PassKey: An additional authentication key, specifically for initiating Mpesa Express (STK Push) transactions.

9. Initiator Name: API Operator configured from the Mpesa Org Portal

10. Initiator Password: Password paired with the Initiator Name will be encrypted to SecurityCredential for transactions.


Mpesa C2B Payment Register URL

This DocType registers the callback URLs for incoming C2B payments. Once registered, Safaricom will notify your app when payments are received, enabling real-time reconciliation.

2. Mpesa Settings: Links to the configured Mpesa Settings, pulling in the necessary credentials.

3. Company: Specifies the company associated with the payment registration.

4. Mode of Payment: Identifies the payment mode for better categorization in your accounting or ERP system.

5. Register Status: Displays the status of the URL registration (e.g., Success, Pending), useful for troubleshooting or verification.


Mpesa C2B Payment Register

This DocType records individual incoming payments via the C2B method, capturing essential details from Safaricom’s Daraja API. This data can be used for transaction verification, customer inquiries, and reconciliation with unpaid invoices.

2. Full Name: Customer’s full name as recorded in the Mpesa transaction.

3. Transaction Type: Type of transaction (typically "Pay Bill" or "Buy Goods").

4. Trans ID: Unique transaction ID generated by Mpesa.

5. Trans Time: Timestamp of the transaction.

6. Trans Amount: Amount transferred by the customer.

7. Business Short Code: The business shortcode involved in the transaction.

8. Bill Ref Number: Reference number associated with the transaction.

9. Invoice Number: Associated invoice for easy reconciliation.

10. Org Account Balance: Account balance at the time of the transaction.

11. Third Party Trans ID: Identifier from any third-party integration.

12. Posting Date & Time: Date and time when the transaction was recorded in your system.

13. Company: The company receiving the payment.

14. Default Currency: The currency in which the transaction was processed.

15. Customer: Links to the customer making the payment.

16. Mode of Payment: Type of payment method used.

17. Currency: The currency in which the transaction was processed.


Mpesa Public Key Certificate

This DocType is used to store the required public key certificates for both sandbox and production environments. These certificates are necessary to establish secure connections between your system and Mpesa’s API, especially for encrypting sensitive information in B2C transactions.

2. Sandbox Certificate: Used for testing in the Daraja sandbox environment.

3. Production Certificate: Used for live transactions in the production environment.


Payment Gateway

The Payment Gateway DocType facilitates the integration of Mpesa with your ERPNext system’s payment gateways, enabling transactions to be routed correctly.

2. Gateway Settings: Contains necessary settings for the payment gateway to work with Mpesa.

3. Gateway Controller: Manages the routing and processing of payments through the specified payment gateway.


Mpesa Payment Reconciliation

This DocType lists and organizes draft Mpesa payments, making it possible to reconcile these draft(s) mpesa payments with pending/unpaid invoices. This DocType streamlines the reconciliation process by matching Mpesa transactions with unpaid sales invoices.

2. Customer: Links to the customer who has any outstanding invoices.

3. Company: The company to which the payment(s) and invoice(s) applies.

4. Currency: The currency in which the transaction occured.

5. Invoices: Displays a list of associated unpaid invoices.

6. Mpesa Payments: Displays a list of draft Mpesa payments.


🔐 Security

• Credentials: Stored securely in the Mpesa Settings Doctype with password fields securely encrypted.

• Token Management: Tokens are generated and stored in the Mpesa Settings and reused for requests till they expire and new ones are requested.

• Webhooks: Ensure your site uses HTTPS.

🛠️ Troubleshooting