POSTPay BBPS Bill

Process a bill payment or recharge for any BBPS-connected biller.

POST/customer/payment/bbps

The money-debit call that pays a bill or submits a recharge on the BBPS network. For a bill payment, send the amount confirmed at Fetch Bill and the utilitycustomername it returned. A prepaid recharge skips Fetch Bill, so it sends the chosen plan's amount and omits utilitycustomername.

Pay the exact amount returned by Fetch Bill — a mismatch is rejected with status 208. On 208, re-fetch the bill and retry with a fresh client_ref_id; a client_ref_id identifies one payment attempt and must never be reused across retries. Persist tid and your client_ref_id before any retry — status 208 still returns a tid.

Parameters vary by operator. The fields below are the common set; pass every param_name returned by Get Operator Parameters as well. The parameter set sent here must match the set sent to Fetch Bill for the same operator.

Tip

This endpoint is used in these workflows:

BBPS — Pay a Utility Bill — Pick a biller by category, read the fields it requires, fetch the live bill, then pay the exact amount. Get Locations is an optional extra filter on the biller list, and UPPCL (operator 190) additionally needs a district_discome from Get District Discome — neither is a step here because neither applies to every biller.
BBPS — Prepaid Mobile / DTH Recharge — Detect the operator and circle from the customer's mobile number, read the operator's input fields, list the available plans, then submit the chosen plan as a payment.

Request

Body parameters

Field	Type	Required	Description
`initiator_id`	string	required	Registered mobile number of the API user (see Platform Credentials).e.g. 9962981729
`phone_operator_code`	string	required	Biller identifier — the `operator_id` from the Get Operators response.e.g. 53
`utility_acc_no`	string	required	Bill / account number. For a prepaid recharge, the customer's mobile number.e.g. 3287820071
`confirmation_mobile_no`	string	required	Customer mobile number.e.g. 9903457748
`sender_name`	string	required	Customer name.e.g. Asaad
`category`	number	required	The `operator_category_id` from Get Categories (e.g. `8` = Electricity).e.g. 8
`amount`	number	required	Amount to pay, in rupees. Must equal the `amount` returned by Fetch Bill.e.g. 2870
`utilitycustomername`	string	optional	Customer name as returned by Fetch Bill. Mandatory for bill payments where Bill Fetch is done. Not applicable to prepaid recharges, which skip Bill Fetch.e.g. Amit Kumar
`client_ref_id`	string	required	Unique partner reference for this payment attempt. Reuse the value sent to the matching Fetch Bill call; generate a fresh one for every retry.e.g. 2026010100123456789
`source_ip`	string	required	Originating client IP address.e.g. 192.168.1.1
`district_discome`	string	optional	District-level distribution company code. Required for operator 190 (UPPCL) only — pass the same value used at Fetch Bill.e.g. Lucknow-MVVNL

initiator_idstringRequired

Registered mobile number of the API user (see Platform Credentials).

example: 9962981729

phone_operator_codestringRequired

Biller identifier — the `operator_id` from the Get Operators response.

example: 53

utility_acc_nostringRequired

Bill / account number. For a prepaid recharge, the customer's mobile number.

example: 3287820071

confirmation_mobile_nostringRequired

Customer mobile number.

example: 9903457748

sender_namestringRequired

Customer name.

example: Asaad

categorynumberRequired

The `operator_category_id` from Get Categories (e.g. `8` = Electricity).

example: 8

amountnumberRequired

Amount to pay, in rupees. Must equal the `amount` returned by Fetch Bill.

example: 2870

utilitycustomernamestringoptional

Customer name as returned by Fetch Bill. Mandatory for bill payments where Bill Fetch is done. Not applicable to prepaid recharges, which skip Bill Fetch.

example: Amit Kumar

client_ref_idstringRequired

Unique partner reference for this payment attempt. Reuse the value sent to the matching Fetch Bill call; generate a fresh one for every retry.

example: 2026010100123456789

source_ipstringRequired

Originating client IP address.

example: 192.168.1.1

district_discomestringoptional

District-level distribution company code. Required for **operator 190 (UPPCL) only** — pass the same value used at Fetch Bill.

example: Lucknow-MVVNL

These headers authenticate and sign every request. See How Auth Works for details.

Field	Type	Required	Description
`developer_key`	string	required	Static API key issued to your account after KYC.
`secret-key`	string	required	Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).
`secret-key-timestamp`	string	required	Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.
`content-type`	string	required	application/jsone.g. application/json

developer_keystringRequired

Static API key issued to your account after KYC.

secret-keystringRequired

Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).

secret-key-timestampstringRequired

Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.

content-typestringRequired

application/json

example: application/json

Response types

response_type_id	Meaning	Next step
`333`	Payment successful — persist `tid` and `client_ref_id` for reconciliation.	—
`208`	Amount does not match the bill. Re-fetch the bill and retry with a fresh `client_ref_id`; a `tid` is still returned, so persist it first.	Fetch BBPS Bill

Responses

333Payment successful — persist `tid` and `client_ref_id` for reconciliation.

statusnumber
Primary success indicator (0 = success).
messagestring
Human-readable response / error message.
response_status_idnumber
Granular status id; see the shared error-codes table.
response_type_idnumber
A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.
tx_statusstring
Transaction state: 0=Success, 1=Fail, 2=Awaited, 3=Refund Pending, 4=Refunded, 5=On Hold.
txstatus_descstring
Human-readable transaction status.
dataobject
API-specific response payload.
- tidstring
  Eko transaction ID. Store it for reconciliation and dispute resolution — returned on failures too.
- tx_statusstring
  Transaction status (`0` = success).
- txstatus_descstring
  Human-readable transaction status.
- status_textstring
  Status label from the biller.
- amountstring
  Amount paid.
- totalamountstring
  Total amount debited, including any fee.
- feestring
  Fee charged for this transaction.
- tdsstring
  TDS deducted on the commission.
- commissionstring
  Agent commission earned on this payment.
- balancestring
  Agent wallet balance after the payment.
- operator_namestring
  Biller the payment was made to.
- utilitycustomernamestring
  Customer name on the bill.
- customermobilenumberstring
  Customer mobile number.
- accountstring
  Account / consumer number that was paid.
- approvalreferencenumberstring
  Biller approval reference, where provided.
- payment_mode_descstring
  Payment mode used.
- user_codestring
  Agent's user code.
- last_used_okekeystring
  Last used OkeKey.
- timestampstring
  Transaction timestamp.

POSTPay BBPS Bill

Request

Body parameters

Response types

Responses

Next steps

Related