M-Pesa Unified Payment Gateway
Safaricom Daraja API Integration for Website, Portal & Vendor Payments
The complete Modular Treasury Solution for Kenyan businesses. Automate M-Pesa Express (C2B), B2C Refunds, and B2B and B2C Vendor Payments directly within Odoo. Scale your features by installing only the sub-modules you need.
Modular & Complimentary Extensions
The core trace_payment_mpesa module is your gateway. Unlock advanced functionality with our Free Extension Modules below. Install only what you need. Zero bloat, maximum efficiency.
-
trace_payment_mpesa_c2b(C2B Payments) -
trace_payment_mpesa_b2c(Refunds and Payouts)
-
trace_payment_mpesa_b2b_paybill -
trace_payment_mpesa_b2b_till -
trace_payment_mpesa_b2c_wallet
Comprehensive Features
M-Pesa Express
Instant STK Push for website and portal checkout.
Vendor Payments
Automated B2B(Paybill and Till) and B2C(Phone and Pochi) payouts.
B2C Refunds
Process customer refunds directly from Odoo invoices.
C2B Fallback
C2B URL Registration and Automatic graceful fallback for failed STK requests.
The Full Financial Lifecycle
1. Revenue: Instant STK Push
Secure customer checkout via STK Push with retries and smart phone validation to ensure successful delivery.
2. Reconciliation: Vendor Payouts
Use the "M-Pesa" payment method when registering payments on Vendor Bills. This will send payments automatically via B2B(Paybill or Till) or B2C(Pochi or Phone)
3. Operations: B2C Payouts & Refunds
Close the financial loop. Issue payouts directly from the Invoice/Payment record using M-Pesa B2C API.
Developer-Friendly Configuration
- Unified API handling for Paybill, Till, and Wallet (Pochi).
- Automated IPN & Webhook registration.
M-Pesa Payment Gateway - Setup & User Guide
The M-Pesa Unified Payment Gateway is a modular, professional-grade suite for Odoo, designed to handle the complexities of the Safaricom Daraja API. It streamlines the collection of payments via STK Push (Express), C2B (Paybill/Till) while automating disbursements through B2C,B2C Wallet, B2B Paybill and B2B Till(Buygoods).
Key Features
- M-Pesa Express (STK Push): Triggers a secure PIN prompt instantly on the customer's phone.
- Intelligent Retry Logic: Supports multiple payment attempts while ensuring a full audit trail without duplicating orders.
- C2B Fallback: Provides manual payment instructions for Paybil Short Codes if the STK Push is ignored or fails.
- B2C Automated Refunds: Process refunds directly from Odoo Credit Notes using a secure Disbursement Queue.
- B2B Paybill and B2B Till(Buygoods) Payouts: Pay vendor bills via M-Pesa's B2B(Paybill or Till) and B2C(Pochi or Direct Phone Account) API's.
- Modular Design: Optimized for performance; install only the components you need (trace_payment_mpesa_c2b, trace_payment_mpesa_b2c, trace_payment_mpesa_b2b_paybill,``trace_payment_mpesa_b2b_till``,``trace_payment_mpesa_b2c_wallet``) etc.
Installation
- Place the module folder into your Odoo addons directory.
- Enable Developer Mode in Odoo.
- Navigate to :menuselection:`Apps --> Update Apps List` .
- Search for trace_payment_mpesa and click Install.
- Install the sub-modules (trace_payment_mpesa_c2b , trace_payment_mpesa_b2b_paybill) etc as required by your business flow.
Configuration
M-Pesa Provider Setup
Go to :menuselection:`Invoicing --> Configuration --> Payment Providers` and select M-Pesa.
- Consumer Key & Secret: Link your Daraja Portal App credentials for the Express checkout, B2C and B2B APIs.
- Shortcode: Enter your Business Paybill or Store Number.
- Initiator Name & Initiator Password: For B2B and B2C API's enter the operator Username and Password of the Initiator created on the M-Pesa G2 Portal
- Passkey: Required for triggering Lipa Na M-Pesa Online (STK Push).
Workflows
M-Pesa Express & Retries
- During checkout, the customer confirms their phone number.
- An STK Push is sent.
- If the customer cancels or the request times out, they can click Retry on the portal.
C2B Manual Reconciliation
In cases where the customer pays manually via Paybill:
- The system displays a Sanitized Account Number (e.g., SO005).
- The C2B Webhook listens for the BillRefNumber.
- The system matches the payment to the correct Transaction.
- The system converts Over Paid C2B Funds into reusable Partner Credits for seamless invoice reconciliation.
- For Quotation C2B Underpayments the system will create a Transaction for each Partial Payment and will Automatically Only Confirm the Quotation if the Sum of the all Done transactions amount is Greater Than Or Equals the Quotation's amount.
- B2B and B2C Payouts
- In the M-Pesa section on the partner's form, add M-Pesa Accounts and set the preferred account as primary.
- When registering a payment on a Bill(s) using the Account Payment Register wizard, select the M-Pesa Payment Method, The primary M-Pesa Account will be automatically selected but you can select another one.
- Click Create Payment on the wizard. Please note, If the M-Pesa Payment Method is selected and a M-Pesa Account Is Not set on the Partner the bill will be skipped.
- Depending on the Selected M-Pesa Account, a B2B Paybill,B2B Till(Buygoods),B2C Phone or B2C Wallet payment request will be sent to M-Pesa's API.
- The bill's Payment State will be updated accordingly after a Callback is received from M-Pesa.
Disbursement Queue
- When a B2C or B2B request is initiated, and the Queue Requests is enabled on the M-Pesa payment provider the transaction enters a Queued state.
- An Odoo Cron Job processes the queue at defined intervals.
- Cancellation Window: Admins can cancel a Pending Queued Transaction before the cron job executes the API call, providing a vital safety net against human error.
Technical Information
Cron Jobs:
M-Pesa Queue: Queue M-Pesa Requests: Handles outgoing disbursements.
Support & Troubleshooting
- Pending Payments: If a payment stays "Pending," check the Payment Transactions log to see Safaricom's response codes.
- URL Failures: Ensure your SSL certificate is valid; Safaricom will not send data to insecure (HTTP) or self-signed (HTTPS) endpoints.
Note
For further assistance, contact our technical support team via the Odoo App Store "Support" button.
Odoo Proprietary License v1.0 This software and associated files (the "Software") may only be used (executed, modified, executed after modifications) if you have purchased a valid license from the authors, typically via Odoo Apps, or if you have received a written agreement from the authors of the Software (see the COPYRIGHT file). You may develop Odoo modules that use the Software as a library (typically by depending on it, importing it and using its resources), but without copying any source code or material from the Software. You may distribute those modules under the license of your choice, provided that this license is compatible with the terms of the Odoo Proprietary License (For example: LGPL, MIT, or proprietary licenses similar to this one). It is forbidden to publish, distribute, sublicense, or sell copies of the Software or modified copies of the Software. The above copyright notice and this permission notice must be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Please log in to comment on this module