C2B Reconciliation

C2B Reconciliation

When customers pay a business directly by entering its shortcode into their M-Pesa app — rather than responding to an STK Push — those payments arrive through a different channel: the Safaricom C2B webhook. The iVendNext Kenya M-Pesa Integration captures these incoming payments automatically, records them in a structured register, and provides tools to link each payment to a customer and reduce the outstanding balance on the matching invoice. This article explains how the C2B payment capture and reconciliation workflow operates in iVendNext Desk.


How Incoming C2B Payments Reach iVendNext

For paybill or till payments initiated by customers, Safaricom posts a webhook notification to a registered callback URL the moment a payment is confirmed. iVendNext receives this webhook and automatically creates a Mpesa C2B Payment Register record — no manual entry is required.



NotesFor this to work, the callback URL must be registered with Safaricom once per shortcode before payments can be received. This registration is done from within iVendNext Desk using the Mpesa C2B Payment Register URL DocType.

Registering the Callback URL

  1. Go to Mpesa C2B Payment Register URL and click New.

  2. Enter the Business Shortcode that matches the Mpesa Settings record for your shortcode.

  3. Select your Company and the Mode of Payment that was created automatically by your Mpesa Settings.

  4. Click Register URL.


iVendNext builds the callback URL from your site address and submits it to Safaricom's Daraja API. This is a one-time step per shortcode. After registration, all incoming payments to that shortcode are delivered to iVendNext automatically.



The Mpesa C2B Payment Register Record

Each incoming C2B payment creates a Mpesa C2B Payment Register record. The company, currency, and Mode of Payment are populated automatically from the configuration set on the registered URL — the finance team does not need to fill these in manually.


Key fields on this record include:


  • Trans ID — Safaricom's unique transaction identifier for the incoming payment

  • Trans Time — the timestamp of the payment as reported by Safaricom

  • Trans Amount — the amount paid in KES

  • Bill Ref Number — the reference entered by the customer when paying (for example, an invoice number)

  • MSISDN — the customer's phone number

  • First Name, Last Name — customer name as registered with Safaricom

  • Customer — a link to the iVendNext customer record, which the finance team can set manually to enable reconciliation

  • Company, Currency, Mode of Payment — set automatically from the registered URL configuration

  • Posting Date — set automatically from the transaction time

  • Submit Payment — a checkbox controlling whether submitting the record triggers Payment Entry creation


Reconciling a C2B Payment Against an Invoice

Once a C2B Payment Register record has been created, the accountant links it to the correct customer by setting the Customer field. This lookup allows iVendNext to match the payment to open invoices for that customer.


When the record is submitted with Submit Payment enabled, iVendNext calls the Payment Entry creation logic, which:


  • Creates a Payment Entry linked to the customer and the Mode of Payment

  • Matches the payment against any outstanding invoice references associated with the customer

  • Reduces the outstanding balance on those invoices accordingly



Notes
From the moment the webhook is received to the point where the invoice balance is reduced, the entire process can be completed without leaving iVendNext Desk. No Safaricom portal login, no statement download, and no manual journal entry is required.



Auto Reconcile C2B

For businesses that prefer a fully hands-off workflow, the Auto Reconcile C2B setting on Mpesa Settings eliminates the manual submission step entirely. When this option is enabled, iVendNext automatically submits every incoming C2B Payment Register record the moment the webhook is received. If a matching customer can be determined from the Bill Ref Number or MSISDN, the Payment Entry is created and the invoice is reconciled without any human action.



Idea
This is particularly useful for high-volume retail environments where dozens of incoming payments arrive throughout the day and the finance team cannot afford to process each one individually. With Auto Reconcile C2B active, the reconciliation backlog is eliminated at source.


Duplicate Payment Protection

Safaricom's STK Push flow and the C2B webhook flow can sometimes reference the same underlying transaction. For example, a payment confirmed through an STK Push also generates a C2B webhook notification. Without a guard, this could result in the same transaction being recorded twice — once as an Mpesa Express Request and once as a C2B Payment Register — leading to a doubled Payment Entry.



NotesiVendNext prevents this with a before-insert check on the C2B Payment Register. When a new record is about to be created, the system checks whether an Mpesa Express Request already exists with the same transaction identifier. If a match is found, the insert is blocked and an error is raised: "Cannot record C2B payment: Express Request {name} already exists." This ensures that each payment is recorded exactly once, regardless of how many Safaricom callbacks reference it.


What the Finance Team Sees Day-to-Day

In normal operations, the finance team opens the Mpesa C2B Payment Register list at the start of the day and sees all overnight incoming payments already created and waiting. Each record shows the amount, the customer's phone number, and the Bill Ref Number. The accountant sets the Customer field, checks the amount against the invoice, and submits. If Auto Reconcile C2B is enabled, the list may already show records in Submitted status with Payment Entries linked.



Info
The reconciliation reports — C2B Payment Summary Group by Customer and C2B Reconciliation Report — give a date-range view of all incoming payments, their reconciliation status, and any unmatched amounts. These are covered in detail in the Setup and Reporting article.



    • Related Articles

    • Bank Reconciliation

      Overview Bank reconciliation in iVendNext helps verify your financial records by matching system transactions with your bank statement. This article walks you through manual and semi-automatic tools, plus tips for keeping records accurate. 1. What is ...

    • Semi-Auto Payment Reconciliation: Automating Reconciliation

      Overview The Semi-Auto Payment Reconciliation feature helps you quickly match payments to invoices with minimal effort. This article explains how to set it up and use it to streamline your financial tasks. You will have to manually enable the Auto ...

    • Payment Reconciliation: Matching Payments with Invoices

      Overview iVendNext’s Payment Reconciliation feature helps match payments to invoices accurately, using manual or semi-automated tools. This article walks you through the process to manage receivables and payables efficiently. You will have to ...

    • Understanding POS Invoice Posting and Reconciliation

      Overview This article explains the invoice lifecycle from creation to ledger posting, along with best practices for reconciliation. 1. The POS Invoice Lifecycle 1.1 Transaction Initiation When a sale occurs, iVendNext creates an interim POS invoice ...

    • Stock Reconciliation: Keeping Physical and Book Stock in Sync

      Overview This article outlines the steps to perform Stock Reconciliation in iVendNext. 1. What is Stock Reconciliation? Stock Reconciliation is the process of comparing the physical stock count with the stock recorded in your system. It involves ...