Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.clickpesa.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Prerequisites

  1. API Keys Create an Application to generate Client ID and API Keys for API access.
  2. Authorization Token Use API Keys to Generate Authorization Token.

​
How It Works

​
Step 1 – Create BillPay Control Number

Create Order BillPay Control Number

This endpoint creates an Order Control Number for a specific transaction or invoice. You can specify the amount, payment mode (full or partial), a custom reference, and other metadata.

Create Customer BillPay Control Number

This endpoint creates a Customer Control Number for a specific customer. You can include customer name, bill description, amount, and payment mode. Multiple control numbers can be generated per customer for different bills or purposes.

Bulk Create Order Control Numbers

Bulk create up to 50 Order Control Numbers per request. Same item shape as the single create endpoint. Supports partial success with per-item error reporting.

Bulk Create Customer Control Numbers

Bulk create up to 50 Customer Control Numbers per request. Same item shape as the single create endpoint. Supports partial success with per-item error reporting.

​
Step 2 – Share BillPay Control Number

Share BillPay Control Number

Once created, the BillPay Control Number can be shared with customers via:
  • SMS or WhatsApp message with the control number and payment instructions.
  • Email with bill details and the control number.
  • Embedded in invoices or payment links on your website.
Customers can then pay using mobile money wallets or bank accounts by providing the control number at the time of payment.

​
Step 3 – Verify Payment

​
Query Payment Status via API

Query Payment Status

You can check the payment status using the payment’s Order Reference by querying the API. This allows you to retrieve real-time payment information for reconciliation or reporting.

​
Receive Webhook Notifications

Configure Application webhooks on the same application you use to create control numbers. When a customer pays via mobile money or bank BillPay against that number, you receive PAYMENT RECEIVED on your application webhook if you have configured it.

Application Webhooks

Set up PAYMENT RECEIVED (and PAYMENT FAILED if needed) under Settings → Developers → your application → Application Webhooks.

Merchant Webhooks

If you have not set up an application webhook for the event, notifications go to your merchant-level webhook instead (if configured).
This applies to order and customer control numbers you create through the BillPay API. For offline BillPay references, use merchant webhooks or the payments API to check payment status.

​
Step 4 – Fetch BillPay Details (Optional)

Query BillPay Control Number Details

Use this endpoint to retrieve full details of a BillPay Control Number, including, amount, reference, linked customer and invoice details. This is useful for displaying bill details to customers or performing audits.

Update BillPay Control Number Details

Use this endpoint to update a BillPay Control Number Details: billStatus, billAmount, billDescription, or billPaymentMode. Useful in reusing the reference number without recreating.