> ## 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.

# BillPay API

> The BillPay API enables you to create BillPay Control Numbers for orders and customers to receive payments from mobile money wallets and bank accounts

## Prerequisites

1. **API Keys**
   [Create an Application](/application/api-application-setup) to generate **Client ID** and **API Keys** for API access.

2. **Authorization Token**
   Use **API Keys** to [Generate Authorization Token](/api-reference/authorization/generate-token).

## How It Works

### Step 1 – Create BillPay Control Number

<Card title="Create Order BillPay Control Number" icon="brackets-curly" href="/api-reference/collection/billpay/create-order-control-number" horizontal>
  This endpoint creates an **Order Control Number** for a specific transaction or invoice.
  You can specify the **amount**, **payment mode** (full or partial), a **max total** that can be collected, a **custom reference**, and other metadata.
</Card>

<Card title="Create Customer BillPay Control Number" icon="brackets-curly" href="/api-reference/collection/billpay/create-customer-control-number" horizontal>
  This endpoint creates a **Customer Control Number** for a specific customer.
  You can include **customer name**, **bill description**, **amount**, a **max total** that can be collected, and **payment mode**.
  Multiple control numbers can be generated per customer for different bills or purposes.
</Card>

<Card title="Bulk Create Order Control Numbers" icon="brackets-curly" href="/api-reference/collection/billpay/bulk-create-order-control-numbers" horizontal>
  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.
</Card>

<Card title="Bulk Create Customer Control Numbers" icon="brackets-curly" href="/api-reference/collection/billpay/bulk-create-customer-control-numbers" horizontal>
  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.
</Card>

<Note>
  You can pass your own references that already exist in your system (for example invoice IDs, loan IDs or order numbers) as `billReference`. That value becomes the customer-facing control number. It must be unique within ClickPesa for your account.
</Note>

### Step 2 – Share BillPay Control Number

<Card title="Share BillPay Control Number" icon="share" horizontal>
  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.
</Card>

### Step 3 – Verify Payment

#### Query Payment Status via API

<Card title="Query Payment Status" icon="brackets-curly" href="/api-reference/collection/querying-for-payments/querying-for-payments" horizontal>
  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.
</Card>

#### Receive Webhook Notifications

Configure **[Application webhooks](/home/webhooks#application-level-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.

<Card title="Application Webhooks" icon="webhook" href="/home/webhooks#application-level-webhooks" horizontal>
  Set up `PAYMENT RECEIVED` (and `PAYMENT FAILED` if needed) under **Settings → Developers → your application → Application Webhooks**.
</Card>

<Card title="Merchant Webhooks" icon="webhook" href="/home/webhooks#merchant-level-webhooks" horizontal>
  If you have not set up an application webhook for the event, notifications go to your merchant-level webhook instead (if configured).
</Card>

<Note>
  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](/api-reference/collection/querying-for-payments/querying-for-payments) to check payment status.
</Note>

### Step 4 – Fetch BillPay Details (Optional)

<Card title="Query BillPay Control Number Details" icon="brackets-curly" href="/api-reference/collection/billpay/querying-for-billpay-details" horizontal>
  Use this endpoint to retrieve full details of a BillPay Control Number, including amount, max total, how much can still be collected, reference, linked customer and invoice details.
  This is useful for displaying bill details to customers or performing audits.
</Card>

<Card title="Update BillPay Control Number Details" icon="brackets-curly" href="/api-reference/collection/billpay/update-billpay-reference" horizontal>
  Use this endpoint to update a BillPay Control Number Details: **billStatus**, **billAmount**, **billMaxCollectionAmount**, **billDescription**, or **billPaymentMode**. Useful in reusing the reference number without recreating.
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.