---
title: "POST /billpay/create-customer-control-number"
method: POST
path: "/billpay/create-customer-control-number"
---

# POST /billpay/create-customer-control-number

`POST /billpay/create-customer-control-number`

Generates a BillPay Control Number for a specific customer

## Request body

- object
  - `customerName` string, required — Name of the customer
  - `customerEmail` string — Email address of the customer **(required if customerPhone is not provided)**
  - `customerPhone` string — Phone number of the customer **(required if customerEmail is not provided)**, starting with country code and without the plus sign, e.g., 255712345678
  - `billDescription` string — Description of the bill
  - `billPaymentMode` 'ALLOW_PARTIAL_AND_OVER_PAYMENT' | 'EXACT' — Payment mode for the bill. Applied only when billAmount is set
  - `billAmount` number — Amount of the bill
  - `billReference` string — Custom bill reference (alphanumeric). If provided, this will be the number used to make payment. If not provided, the system auto-generates one

## Response `200`

Successfully generated Customer BillPay Control Number

- object[]
  - `updatedAt` string, date-time — Last updated timestamp
  - `createdAt` string, date-time — Creation timestamp
  - `id` string — Payout ID
  - `orderReference` string — Associated order reference
  - `amount` string — Payout amount
  - `currency` string — Currency code
  - `fee` string — Transaction fee
  - `status` 'SUCCESS' | 'PROCESSING' | 'PENDING' | 'FAILED' | 'REFUNDED' | 'REVERSED' — Payout status
  - `channel` 'BANK TRANSFER' | 'MOBILE MONEY' — Payout channel
  - `channelProvider` string — Name of the payout channel provider
  - `transferType` 'ACH' | 'RTGS' — Transfer type - when applicable
  - `notes` string — Additional notes if available
  - `beneficiary` object
    - `accountNumber` string — Beneficiary's account number
    - `accountName` string — Beneficiary's account name
    - `swiftNumber` string — SWIFT number if applicable
    - `routingNumber` string — Routing number if applicable
    - `beneficiaryMobileNumber` string — Beneficiary's mobile number if applicable
    - `beneficiaryEmail` string, email — Beneficiary's email if applicable
  - `clientId` string — Application Client ID associated with the payout

## Other responses

- `400` — Validation Error
- `401` — Unauthorized
- `409` — Conflict Error

---

[API](https://skmtc.net/clickpesa/apis/core-api-openapi-specification.md) · [All operations](https://skmtc.net/clickpesa/apis/core-api-openapi-specification/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/clickpesa/core-api-openapi-specification/versions/9f70f35c5590/schema)