ERPNext ↔ M-Pesa Integration (C2B, B2C, B2B)
Payments rails for ERPNext: deterministic matching, safe retries, and evidence you can reconcile. Built for callbacks, reversals, and finance-grade audits.
Why payments integrations break ERP projects
Payments don’t fail cleanly. They duplicate, arrive late, reverse, and trigger retries. Without deterministic rules and evidence, finance teams end up reconciling with guesswork.
Callbacks and job retries are normal. If the integration is not idempotent, the same payment becomes multiple ERP entries.
- Duplicate callbacks happen; a payment can be announced more than once.
- Timeouts cause replays: money moved, but ERP didn’t post (or posted twice).
- Duplicate entries create customer disputes and finance cleanup work.
If you can’t prove what happened, you can’t reconcile. Screenshots are not evidence, and ‘it should be paid’ is not a ledger.
- Weak matching rules lead to wrong invoices being closed.
- No event trail makes dispute resolution slow and manual.
- Failures hide in background jobs until customers complain.
Deterministic matching + idempotent retries + evidence trails
This integration is engineered for accounting reality: every event is traceable, replay-safe, and explainable under audit.
Every transaction is processed with deterministic keys and “already applied” checks, so retries do not create duplicate postings.
Payments are matched using explicit rules (references, invoices, customers) - not heuristic guesswork.
Each event stores payload + ERP outcomes + status so you can prove what happened and why.
What’s included (and how it stays correct)
We implement payment rails that finance teams can operate - not just callbacks that ‘post something’.
Customer payments are recorded with deterministic matching and status tracking so invoices, receipts, and ledgers remain correct.
- Deterministic invoice matching (avoid wrong invoice closures).
- Partial payments and overpayments handled explicitly.
- Status tracking (received, posted, reversed, failed) with reasons.
Refunds and disbursements are processed idempotently with evidence and controlled workflows to avoid double sending.
- Idempotent disbursement requests (no double payouts).
- Posting rules aligned with your accounting structure.
- Evidence logs per transaction for disputes and audits.
Vendor and business payments are executed under approvals and traceability so finance retains operational control.
- Approval workflows (who approved what, when).
- Deterministic posting to the right accounts and documents.
- Evidence and audit trails for vendor disputes.
A production payments rail needs visibility: what failed, why it failed, what was retried, and what is safe to retry.
- Automated reconciliation views (prove received vs posted).
- Failure categories with actionable context (not raw logs).
- Retry controls designed to be replay-safe.
The payment realities we design for
These are common in Kenya. Treating them as edge cases is how payment systems become unreliable.
Same transaction can be sent multiple times. Duplicates are treated as normal and harmless.
Payment succeeded but ERP didn’t post. We can safely replay from evidence without duplicating.
Reversals require traceable linkage to original events and clear accounting outcomes.
How we implement without disrupting finance operations
Payments touch trust. We roll out in phases with verification and guardrails.
We define deterministic matching, posting rules, evidence capture, and safe retry semantics.
- Confirm document mapping (Invoice, Payment Entry, Journal rules).
- Define reference strategy (invoice refs, account refs, customer refs).
- Set up evidence logging + reconciliation views.
Enable live C2B/B2C/B2B flows with monitoring, safe retries, and reconciliation proof.
- Enable C2B with posting verification and exception handling.
- Enable B2C/B2B with approvals and double-send prevention.
- Train finance on evidence trails + dispute resolution workflow.
Frequently asked questions
Straight answers to the questions we hear most about this integration.
Yes. We connect M-Pesa to ERPNext so customer payments (C2B), disbursements and refunds (B2C), and vendor transfers (B2B) post directly to the right documents - invoices, payment entries and journals - with deterministic matching and a full evidence trail, rather than being keyed in by hand.
Through idempotency. M-Pesa callbacks and job retries can announce the same payment more than once, so every transaction is processed with a deterministic key and an 'already applied' check. A payment that arrives twice is recorded once, which is what keeps the ledger correct under real-world retries and timeouts.
That gap is the most common failure in payment integrations, and it is designed for explicitly. Every event stores its raw payload and outcome, so a payment that moved on M-Pesa but did not post in ERPNext is visible in the reconciliation view and can be safely replayed from the stored evidence - without any risk of double-posting.
For direct Daraja integration, yes - you need a registered paybill or buy-goods till plus API credentials from Safaricom. A personal M-Pesa line cannot be integrated through Daraja. If you cannot get Daraja on your line, we can still reconcile automatically by capturing the confirmation SMS, so you are not stuck with manual matching.
Through explicit, deterministic rules using the account reference - an invoice number, account number or customer reference - not amount-based guesswork, because two customers can owe the same figure. Part of the implementation is designing a clean reference scheme so payments auto-match instead of needing a person to sort them.
Yes. Where Daraja is not available - an unregistered till or a personal line - the M-Pesa confirmation SMS still arrives for every payment. A gateway forwards each message to your system, which parses the amount, code and reference and matches it to an invoice, giving you automatic reconciliation as a bridge until (or instead of) full Daraja integration.
Related insights
Plain-language guides on how M-Pesa integration and reconciliation actually work.
The Daraja conversation, callbacks, and where most integrations quietly drop payments.
No paybill or C2B feed? Reconcile automatically from the confirmation SMS instead.
How payment confirmations become correct ledger entries without manual data entry.
Want payments you can reconcile, audit, and trust?
We’ll review your payment flow (collections, refunds, vendor payouts), your ERPNext accounting configuration, and your reconciliation requirements - then propose an implementation plan that is provable under audit and safe under retries.