C2B Payments (Customer to Business)

C2B integration allows your ERPNext instance to automatically receive and log payments made by customers via M-Pesa to your Paybill or Till number. Instead of manually recording each incoming payment, the system captures them in real time through Safaricom's Daraja callback mechanism.

C2B

How It Works

When a customer makes an M-Pesa payment to your Paybill or Till number, Safaricom sends a notification (callback) to a URL registered on your server. The app captures this callback and records it as a Mpesa C2B Payment Register entry. From there, the payment can be matched to an outstanding invoice either automatically or manually.

Setup: Registering Callback URLs

Before any payments can be received, you must register your callback URLs with Safaricom. This is a one-time setup per Mpesa Settings configuration.

Steps

1. Use the Awesome Bar or Mpesa workspace to navigate to Mpesa C2B Payment Register URL.
2. Click New to create a new registration record.
3. Fill in the following fields:

4. Save the document.

After saving, the app sends a URL registration request to Safaricom's Daraja API. If successful, the Register Status field will update to Success.

Confirming Registration

Always verify that Register Status shows Success before expecting to receive callbacks. If it shows a failed state, refer to the troubleshooting steps below.

Receiving Payments

Once the URLs are registered:

1. A customer makes an M-Pesa payment to your Paybill or Till number.
2. Safaricom sends a callback to your registered URL.
3. The app records the transaction in the Mpesa C2B Payment Register.

Each record captures:

• Customer name (as entered in M-Pesa)
• Transaction ID
• Transaction time and amount
• Bill Reference Number (account number entered by the customer)
• Business shortcode

Smart Matching Logic

When a customer makes a Paybill payment, M-Pesa prompts them to enter an account number. If the customer enters:

• A Sales Invoice number: the system checks if it matches an existing invoice and automatically links it.
• A Customer name or customer number: the system checks if it matches a customer record and automatically fills the Customer field on the payment register.

This matching happens automatically on callback receipt. Payments where the account number does not match any known reference remain unlinked and require manual reconciliation.

Auto-Reconciliation

If Auto Reconcile C2B Payments is enabled in Mpesa Settings:

1. When a Mpesa C2B Payment Register record is submitted, the system attempts to find and match an outstanding invoice.
2. If a matching invoice is found (by invoice number or customer reference), the payment is applied to it.
3. If no specific invoice match is found, the payment is applied to the customer's oldest unpaid invoices using FIFO (First-In First-Out) logic.

If auto-reconciliation is disabled, submitted payment records must be matched manually using the Mpesa Payment Reconciliation tool.

Registration Failures: Common Causes and Fixes