> ## 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 **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**, 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>

### 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, 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**, **billDescription**, or **billPaymentMode**. Useful in reusing the reference number without recreating.
</Card>