Until now, assigning a BillPay Control Number for specific orders or customers was something organizations did in the ClickPesa Merchant Dashboard, this is great for manual workflows and quick starts. We are now releasing our BillPay APIs, which allows you to create and manage both Customer and Order Control Numbers directly from your own systems via API integration. Generate numbers on demand inside your billing, ERP, or checkout; attach your own references and amounts; choose payment behavior (full, partial, or overpayment accepted); and receive real-time confirmations that keep balances, ledgers, and reports in sync.
Recap: What is a BillPay Control Number?
A BillPay Control Number (BillPay-Namba) is a static, unique number linked to a specific customer or bill. It acts like a payment rail that you can reuse for multiple transactions if you allow partial or recurring payments. Because each payment against the number triggers a webhook, your system can update balances, post entries, and reconcile automatically.
The APIs let you programmatically generate and manage control numbers, removing manual setup and reducing operational overhead. You can:
- Generate Customer or Order Control Numbers on demand
- Set amounts, descriptions, and custom references
- Automate tracking with real-time webhooks or the Payment Query API
- Operate across all Tanzanian mobile money and CRDB banking channels
Read more: https://docs.clickpesa.com/bill-pay/bill-pay-overview
Types of BillPay Control Numbers
Customer BillPay Control Numbers
A single, permanent number linked to a customer, contract, or cost center that accepts multiple payments against the same reference. Ideal for ongoing relationships, installments, subscriptions/retainers, maintenance, repeat donations, because the number never changes, reducing payer confusion and making reconciliation predictable.
Read more: https://docs.clickpesa.com/bill-pay/customer-billpay-namba
Order BillPay Control Numbers
A one-time number tied to a specific bill (invoice, order, POS/restaurant tab) so the payer completes that transaction in a single flow. You control its behavior and lifespan (amount rules, partial/overpayment settings, expiry/closure) and can add a description and custom reference.
Read more: https://docs.clickpesa.com/bill-pay/order-billpay-namba
How BillPay APIs works, end to end
- Generate
Create a control number for a customer, bill, or order using the Merchant Dashboard or the API. Set behavior to full amount only, allow partial payments, or accept overpayments. - Share
Present the number in your customer portal, send it by SMS or email, or print it on a slip. The same number works across supported channels. - Pay
Customers pay via Tanzanian mobile money and CRDB channels. No new apps or unfamiliar steps for the payer. - Confirm
Every successful payment triggers a real-time webhook. Your system can apply the payment immediately, update balances, and record clean accounting entries. - Verify and Reconcile
Use webhook events or the Payment Query API to verify totals, match payments to invoices or customers, and close the loop in finance.
Read more: https://docs.clickpesa.com/bill-pay/billpay-api-overview
Setup and Implementation BillPay APIs
We here explain how to integrate the BillPay APIs with your system and keeps data consistent from collection through accounting.
- Integrate the Create BillPay Control Numbers via the API
- API Docs for Customer BillPay Control Numbers: https://docs.clickpesa.com/api-reference/collection/billpay/create-customer-control-number
- API Docs for Order BillPay Control Numbers: https://docs.clickpesa.com/api-reference/collection/billpay/create-order-control-number
- Receive Webhooks
- Implement a secure webhook endpoint and verify payloads using the checksum.
- Docs: https://docs.clickpesa.com/home/webhooks#setting-up-webhooks
- Add webhook response in your database
This is not an API and has to happen on your side.- Log each payment event in your database
- Apply to the outstanding customer, order, invoice.
- (Optional) Create accounting journals automatically.
- Issue Receipts from your app (optional)
This is not an API and has to happen on your side.- Generate a receipt per payment and provide that to your customer
- Reconcile (optional but recommended)
- Run a daily reconciliation against the Payments Query API and settlement files.
Docs: https://docs.clickpesa.com/api-reference/collection/querying-for-payments/querying-for-payments
How do we charge
The BillPay API (for creating and managing Customer and Order Control Numbers) is a secure, maintained service that we operate end-to-end, cloud infrastructure, uptime monitoring, webhook delivery, fraud/abuse safeguards, and ongoing product support. That work carries real operating costs, so we charge a 1% per successful transaction. In return, businesses typically cut manual administration and reconciliation dramatically (companies report up to 85% less admin), turning BillPay into a net cost saver.
Why teams choose BillPay APIs
- Flexibility: Structure bills the way your business operates
- Cost Saving: Automate, reduce manual effort and remove errors
- Instant confirmation: See payments as they clear, in real time
- Market reach: Accept payments across Tanzanian mobile money and CRDB channels
FAQ
Can one customer have multiple control numbers?
Yes. Use separate numbers for different services, projects, or income centers.
Do you support partial payments and overpayments?
Yes, this can be done through Customer BillPay Control Numbers. You choose the behavior per control number.
How are confirmations delivered?
Each successful payment triggers a webhook so your system can update balances immediately.
What is my customers do not want to pay with a reference, can I still track payments coming from them?
Yes, we also provide USSD Push Payments. It triggers a USSD prompt from your app to ask the customer to pay, no reference entry required. The payment is automatically matched to the correct reference.
Which channels are supported?
All major Tanzanian mobile money networks and CRDB banking channels.
Why does it cost my business 1% per transaction?
The fee covers the secure operation and continuous improvement of the BillPay API, hosting, monitoring, webhook reliability, integrations and support. It is designed to reduce manual work and errors; many customers see up to 85% less admin effort.
What’s included in the fee?
API access, real-time webhooks, control-number management, observability/monitoring, and merchant support.
Does the 1% apply to both Customer and Order Control Numbers?
Yes. The fee applies to each successful payment processed via BillPay channels, regardless of control-number type.
How are partial payments handled?
Each successful payment against a control number (including partials) is processed and charged individually.
Can I still assign control numbers from the Merchant Dashboard without using the API?
Yes. The Dashboard flow remains available for manual workflows and quick starts; the API adds automation and system-to-system control.
Who pays the fee, us or our customers?
By default, fees for BillPay are charged to the merchant account.
Where do I see the fees and settlements?
In your settlement reports and transaction detail within the Merchant Dashboard (and via our reporting/Query APIs)
Do you have any questions about this setup? Contact us here: https://clickpesa.com/customer-support/
International Money Transfer and Remittances to Tanzania through TIPS