Automatically Reconcile Payments Using Order BillPay Control Numbers

While mobile money and bank transfers are convenient for customers, they often create administrative headaches for businesses, particularly when it comes to payment reconciliation.

Organizations like schools, SaaS providers, utilities, and NGOs frequently deal with the challenge of matching anonymous payments from mobile money or banks to specific customers or invoices. Manual bank statement checks, Excel spreadsheets, and phone confirmations are common, and incredibly time demanding.

ClickPesa offers a better way. Through Order BillPay Control Number, ClickPesa enables automatic, real-time reconciliation of payments tied to specific transactions. Whether you are collecting school fees or managing e-commerce payments, this solution makes it possible to track who paid what, when, and for which invoice, without manual intervention.

Understanding the Types of BillPay Control Numbers

ClickPesa BillPay supports three types of control numbers, each designed for different payment collection needs:

• Merchant BillPay-Namba: A 4-digit static number assigned to every merchant. It serves as the foundation for generating other types of control numbers and can be used for direct deposits into the merchant’s account. This is only used for deposit, there is currently no webhook notification. More
• Order BillPay Control Number (this article’s focus): A dynamic control number created for a specific transaction or invoice. It is best for one-time or ad-hoc payments like individual invoices or e-commerce orders. This number exists out of Merchant BillPay-Namba + a dynamic unique number. More
• Customer BillPay Control Number: A static number assigned to a specific customer, ideal for repeat or subscription-style payments (e.g., school fees paid termly using the same reference). This number exists out of your Merchant BillPay-Namba + a static unique number. More

In this article, we focus exclusively on the Order BillPay Control Number, how it works, how to implement it, and how it helps you automatically reconcile specific transactions in real time.

What Is an Order BillPay Control Number?

An Order BillPay Control Number is a dynamic payment reference created for a specific transaction. It is intended for one-time use and is ideal for e-commerce checkouts, unique invoices, or cases where individual customers must make specific payments. 

Important to note is that there is no API endpoint to create an Order BillPay Control Number. Instead, you create it on your side by combining your Merchant BillPay-Namba (assigned by ClickPesa) with a unique order reference from your system. This combined value is what you share with the customer as the payment reference. When a customer makes a payment using that BillPay number, ClickPesa uses the BillPay-Namba to route the payment to your account and sends you a webhook notification containing the full BillPay number and payment details.

Each Order BillPay Control Number is generated by combining two components:

1. Merchant BillPay-Namba – a 4-digit identifier assigned to you by ClickPesa.
2. Order Reference – any unique reference from your internal system (like an invoice number, customer ID, or transaction token). Length does not matter. Any letter or number works or both.
   

How It Is Generated:

Order BillPay Control Number = [Merchant BillPay-Namba] + [Order Reference]

Example:

• Merchant BillPay-Namba: 1122
• Order Reference: 231256
• Order BillPay Control Number: 1122231256

This method gives you full control over reference formatting, allowing it to reflect your internal system logic.

Making a Payment Using an Order BillPay Control Number

Once created, the customer can use the control number to pay through a wide range of payment channels, including:

• Tigopesa
• Airtel Money
• Halopesa
• M-Pesa
• CRDB SIM Banking (App & USSD)
• CRDB Internet Banking
• CRDB Wakalas

This accessibility ensures customers can easily pay from anywhere using their preferred mobile money or banking option.

The Workflow: How It All Comes Together

Here’s a step-by-step breakdown of how you would implement the Order BillPay Control Number for automated reconciliation:

1. Your system generates a unique Order Reference for each invoice or transaction.
2. You concatenate it with your ClickPesa-assigned BillPay-Namba, creating a unique control number.
3. The control number is shared with the customer, typically via invoice, SMS, or email.
4. The customer pays using this control number through any of the supported payment channels.
5. ClickPesa detects the payment and sends a webhook to your system, including:
   • The control number used
   • The Order Reference you set
   • Payment amount and status
6. Your system automatically matches the payment to the corresponding invoice and updates it as “paid.”
   

IMPORTANT: Once paid, the control number is closed or fulfilled, ensuring it’s not reused or misattributed. When it is partly paid or a transaction fails, the control number is also closed.

Real-World Example: School Fee Management

Lets say you run a school or provide school billing software. You want each parent to pay school fees for their child without confusion or manual intervention.

Here is how you would use Order BillPay Control Numbers:

• A parent receives an invoice for their child’s Term 1 fees.
• Your system creates an Order Reference: studentA2025term1.
• Your BillPay-Namba is 1122, so the full control number becomes 1122studentA2025term1.
• The parent pays using this control number via M-Pesa.
• ClickPesa detects the payment and sends a webhook to your backend with the orderReference.
• Your system finds the matching record and updates the payment status to “paid.”
  

This provides a closed-loop, automated flow with no manual verification needed.

Why This Beats Manual Reconciliation

Many businesses rely on bank statements or mobile money summaries, but this method is:

• Slow – statements are often delayed.
• Ambiguous – names and references may be unclear.
• Manual – requires time-consuming verification.
• Error-prone – duplication, typos, and missed payments are common.
  

With Order BillPay Control Numbers, you get:

• Real-time payment visibility via webhook
• Transaction-specific matching
• Automated updates to your backend systems
• Clean audit trails tied to invoice numbers or customer IDs
  

Implementation Guide

1. Get Your BillPay-Namba

Sign up with ClickPesa and request access to BillPay. You will receive your unique Merchant BillPay-Namba:  a 4-digit code tied to your merchant account.

2. Generate Order References

In your system, generate a unique Order Reference for each transaction. These should be meaningful and structured, such as:

• INV20250023
• studentMusaTerm2
• purchaseorder9876
  

3. Combine and Display

Concatenate your BillPay-Namba with the Order Reference to create the Order BillPay Control Number, and display this prominently on your invoice, email, or SMS.

4. Setup Webhook Notification Receiver

Find more information about Webhook Notifications. Webhooks only work for order and customer billpay order number.

Build a secure webhook listener to receive ClickPesa notifications when payments are completed. A good endpoint name would be /api/payments/webhook.

The webhook payload will include:

• controlNumber
• orderReference
• amount
• status (e.g., “fulfilled”)

Alternative:
It is also possible to use the API query for payments using the order / customer billpay order number.

5. Match and Update

When your backend receives the webhook:

• Use orderReference to find the corresponding invoice
• Mark it as paid
• Optionally, log the transaction and send a confirmation to the customer
  

Best Practices

• Use consistent formatting for orderReference values so they are easy to query and debug.
• Store webhook logs to ensure traceability and resolve disputes if needed.
• Secure your webhook endpoint with checksum.
  

Use Cases Beyond Schools

Order BillPay Control Numbers can be used across many industries:

• E-commerce – automatically reconcile checkout payments
• Property management – match rent payments to tenant records
• Subscription services – tag recurring invoices with unique references
• Government services – accept fines or fees with transparent tracking
• NGOs – tie incoming donations to specific campaigns or grant reports

Conclusion

ClickPesa’s Order BillPay Control Number system is a simple but powerful innovation for real-time, automated payment reconciliation. It helps businesses and platforms to move beyond static account numbers and vague references, replacing them with clear, structured, and automatically tracked transactions.

By combining your Merchant BillPay-Namba with custom Order References, and using ClickPesa’s webhook system, you can build a fully automated reconciliation flow,  one that saves time, reduces errors, and scales with your business.Whether you’re building a school platform, invoicing tool, or payment portal, if you’re handling mobile or bank payments in Tanzania, this tool is a must.