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

# Create Order Control Number

> Generates a BillPay Control Number for a specific bill, transaction or invoice



## OpenAPI

````yaml POST /billpay/create-order-control-number
openapi: 3.0.1
info:
  title: CORE API - BillPay Control Number Creation
  description: API for creating BillPay Control Numbers
  version: 1.0.0
servers:
  - url: https://api.clickpesa.com/third-parties
security:
  - bearerAuth: []
paths:
  /billpay/create-order-control-number:
    post:
      description: >-
        Generates a BillPay Control Number for a specific bill, transaction or
        invoice
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                billDescription:
                  type: string
                  description: Description of the bill
                  example: Water Bill - July 2024
                billPaymentMode:
                  type: string
                  enum:
                    - ALLOW_PARTIAL_AND_OVER_PAYMENT
                    - EXACT
                  default: ALLOW_PARTIAL_AND_OVER_PAYMENT
                  description: >-
                    Payment mode for the bill. Applied only when billAmount is
                    set
                billAmount:
                  type: number
                  description: Amount of the bill
                  example: 90900
                billReference:
                  type: string
                  description: >-
                    Custom bill reference (alphanumeric). If provided, this will
                    be the number used to make payment. If not provided, the
                    system auto-generates one
            example:
              billDescription: Water Bill - July 2024
              billPaymentMode: EXACT
              billAmount: 90900
              billReference: CUSTOMJH121
      responses:
        '200':
          description: Successfully generated BillPay Control Number
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '400':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '409':
          description: Conflict Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictError'
components:
  schemas:
    Response:
      type: object
      properties:
        billPayNumber:
          type: string
          description: >-
            BillPay number - This is the number that will be used to make
            payment. If a custom `billReference` was provided in the request,
            this will match that value.
          example: '55042914871931'
        billDescription:
          type: string
          description: Description of the bill
          example: Generic Bamboo Chees
        billCustomerName:
          type: string
          description: Name of the customer - for customer billpay numbers
          example: Mr. Freddie Walker-Graham
        billAmount:
          type: number
          description: Amount of the bill
          example: 90900
        billPaymentMode:
          type: string
          description: Payment mode for the bill. Applied only when billAmount is set
          example: EXACT
    ValidationError:
      type: object
      properties:
        message:
          type: string
          description: Validation error message
          example: billPayNumber is required
    UnauthorizedError:
      type: object
      properties:
        message:
          type: string
          description: Unauthorized Error
          example: Unauthorized
    ConflictError:
      type: object
      properties:
        message:
          type: string
          description: Conflict error message
          example: 'Bill reference already used: Use a different reference'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Authorization header containing the JWT access token returned from the
        generate token endpoint. The token already includes the Bearer prefix.
        Example: `Authorization: Bearer eyJhbGciOi...`
      bearerFormat: JWT

````