Bill Payment

Initiate a utility bill payment. The system debits the wallet, forwards the payment request to the operator via the provider network, calculates any commission earned, and automatically handles refunds if the transaction fails.

Endpoint: /v1/bbps/bill-pay
Method: POST
Content-Type: application/json
Authentication: Required (Basic Auth)

Request Body Parameters

Field	Type	Required	Description
`operator_id`	string \| integer	Yes	The unique operator identifier (e.g., `101`).
`number`	string	Yes	The consumer account number or primary customer identifier (e.g., consumer number / account ID).
`amount`	float	Yes	The payment amount in INR (must be greater than 0).
`p_order_id`	string	Yes	A unique transaction identifier generated by your application to prevent duplicate requests.
`circle_code`	string	Optional	State/circle code identifier (defaults to `""`).
`ad1`	string	Optional	Additional parameter field 1 required by some operators (defaults to `""`).
`ad2`	string	Optional	Additional parameter field 2 (defaults to `""`).
`ad3`	string	Optional	Additional parameter field 3 (defaults to `""`).
`ad4`	string	Optional	Additional parameter field 4 (defaults to `""`).
`ad5`	string	Optional	Additional parameter field 5 (defaults to `""`).
`ad6`	string	Optional	Additional parameter field 6 (defaults to `""`).
`customer_mobile`	string	Yes	Customer OR Agent mobile number
`remitter_name`	string	Yes	Customer OR Agent name

Request Body Example

{
  "operator_id": 101,
  "number": "9000182736",
  "amount": 1450.00,
  "p_order_id": "PARTNER_PAY_998877",
  "circle_code": "MH",
  "ad1": "Additional Info Value",
  "customer_mobile": "1234567890", // Customer/Agent number
  "remitter_name": "Rakesh Kumar" // Customer/Agent Name
}

Response Scenarios

1. Success Response (200 OK)

Returned when the bill payment has successfully completed at the operator network.

{
  "success": true,
  "status": "success",
  "orderId": "PARTNER_PAY_998877",
  "operatorRefId": "REF998877665544",
  "message": "Bill payment completed successfully",
  "data": {
    "number": "9000182736",
    "amount": 1450,
    "operator_id": "101",
    "operator_name": "Tata Power - Mumbai",
    "debit_amount": "1446.50",
    "opening_bal": "15353.25",
    "closing_bal": "13906.75",
    "order_id": "8aa18281-a67b-402a-bf31-0df0498111ab",
    "partner_order_id": "PARTNER_PAY_998877",
    "operator_ref_id": "REF998877665544",
    "commission_amount": "3.50",
    "timestamp": "2026-07-11 18:12:31"
  }
}

Response Data Fields:

Field	Type	Description
`success`	boolean	Overall transaction outcome flag.
`status`	string	Current transaction status (`success`).
`orderId`	string	The partner transaction order ID supplied in the request.
`operatorRefId`	string	The operator-level reference confirmation ID.
`data.debit_amount`	string	Actual amount debited from your wallet after adjusting for the commission earned.
`data.opening_bal`	string	Wallet balance before the transaction.
`data.closing_bal`	string	Wallet balance after the transaction and commission payout.
`data.order_id`	string	Internal system transaction UUID.
`data.commission_amount`	string	Commission earned on the transaction.
`data.timestamp`	string	Execution time in Indian Standard Time (IST).

2. Pending Response (200 OK)

Returned when the provider request is delayed. You should query the status later using the Recharge / Transaction Status endpoint with the returned orderId.

{
  "success": true,
  "status": "pending",
  "orderId": "PARTNER_PAY_998877",
  "message": "Bill payment is pending processing"
}

3. Failed Response (400 Bad Request)

Returned if the payment fails (e.g., amount mismatch, provider outage, expired bill). Any debited amount is fully refunded to your wallet.

{
  "success": false,
  "status": "failed",
  "message": "Bill payment failed"
}

Validation & Business Errors

Insufficient Balance (400 Bad Request)

{
  "error": "Insufficient balance"
}

Invalid Parameters (400 Bad Request)

Returned if operator_id, number, or p_order_id is missing, or the amount is invalid.

{
  "error": "Invalid request parameters"
}

Unknown Operator (400 Bad Request)

{
  "error": "Biller not found or inactive"
}

Getting Started

Balance API

Recharge API

BBPS API

Request Body Parameters

Request Body Example

Response Scenarios

1. Success Response (200 OK)

Response Data Fields:

2. Pending Response (200 OK)

3. Failed Response (400 Bad Request)

Validation & Business Errors

Insufficient Balance (400 Bad Request)

Invalid Parameters (400 Bad Request)

Unknown Operator (400 Bad Request)

​Request Body Parameters

​Request Body Example

​Response Scenarios

​1. Success Response (200 OK)

​Response Data Fields:

​2. Pending Response (200 OK)

​3. Failed Response (400 Bad Request)

​Validation & Business Errors

​Insufficient Balance (400 Bad Request)

​Invalid Parameters (400 Bad Request)

​Unknown Operator (400 Bad Request)

Request Body Parameters

Request Body Example

Response Scenarios

1. Success Response (200 OK)

Response Data Fields:

2. Pending Response (200 OK)

3. Failed Response (400 Bad Request)

Validation & Business Errors

Insufficient Balance (400 Bad Request)

Invalid Parameters (400 Bad Request)

Unknown Operator (400 Bad Request)