Institution/End-to-End/Bill Inquiry Spec

Bill Inquiry — API Specification

This is the spec for the API you build. Kuickpay will call this endpoint when a consumer wants to inquire about your bill. Your endpoint must accept this request and respond in the format below.

What to build

Expose a POST endpoint on your server. Kuickpay will call it with the consumer number and channel info. You look up the bill in your system and return the details below.

POST https://your-domain.com/your/inquiry/endpoint

Share this URL with Kuickpay during onboarding. They configure it in the system.

Request (Kuickpay sends this)

Request Parameters

Parameter	Type	Required	Max Length	Description
`consumer_number`	numeric	required	18	Consumer/account number sent by Kuickpay. First 5 digits identify your biller. Numeric characters only.
`bank_mnemonic`	string	optional	7	Short code of the payment channel (e.g. MCB, HBL, UBL). Optional.
`reserved`	string	optional	100	Optional metadata. Can be empty string.

Request Example

POST https://your-domain.com/inquiry
Content-Type: application/json

{
  "consumer_number": "XXXXX0000000000001",
  "bank_mnemonic": "MCB",
  "reserved": ""
}

Response (you return this)

Response Parameters

Parameter	Type	Required	Max Length	Description
`response_Code`	string	required	2	Two-digit result code. "00" = success. See Response Codes table below.
`response_description`	string	required	100	Human-readable result message.
`consumer_detail`	string	required	50	Customer name. Please do not use special characters.
`bill_status`	string	required	1	"U" = Unpaid, "P" = Paid, "B" = Blocked. Omit this field when response_Code is "01".
`due_date`	string	required	8	Bill due date in YYYYMMDD format (e.g. "20250630").
`amount_within_due_date`	AN14	required	14	Amount payable before due date. AN14: 13-digit amount left-padded with zeros (last 2 digits are minor units) preceded by a +/- sign, e.g. "+0000000250000" = Rs. 2,500.00.
`amount_after_due_date`	AN14	required	14	Amount payable after due date. Same AN14 format as amount_within_due_date.
`billing_month`	string	required	4	Billing period in YYMM format (e.g. "2506" for June 2025).
`date_paid`	string	optional	8	Date payment was made in YYYYMMDD format, if already paid.
`amount_paid`	string	optional	12	Amount paid in paisa, if applicable. 000000250000
`tran_auth_id`	numeric	optional	6	Transaction auth ID returned after successful payment. Numeric characters only.
`contact_number`	string	required	15	Consumer contact number.
`email`	string	required	100	Consumer email address.
`reserved`	string	optional	100	Pass through from request.
`institution_id`	string	required	10	Your biller institution ID.
`institution_name`	string	required	50	Your institution name.

Amount Format

amount_within_due_date and amount_after_due_date use AN14: a +/- sign followed by a 13-digit amount left-padded with zeros (last 2 digits are the minor units). Example: Rs. 2,500.00 → +0000000250000

Response Example — Success (00) — FOR UNPAID

{
  "response_Code": "00",
  "response_description": "Bill Found",
  "consumer_detail": "JOHN DOE",
  "bill_status": "U",
  "due_date": "20250630",
  "amount_within_due_date": "+0000000250000",
  "amount_after_due_date": "+0000000265000",
  "billing_month": "2506",
  "date_paid": "",
  "amount_paid": "",
  "tran_auth_id": "",
  "contact_number": "03001234567",
  "email": "john.doe@example.com",
  "reserved": "",
  "institution_id": "XXXXX",
  "institution_name": "Your Company Name"
}

Response Example — Success (00) — FOR PAID

{
  "response_Code": "00",
  "response_description": "Bill Found",
  "consumer_detail": "JOHN DOE",
  "bill_status": "P",
  "due_date": "20250630",
  "amount_within_due_date": "+0000000250000",
  "amount_after_due_date": "+0000000265000",
  "billing_month": "2506",
  "date_paid": "",
  "amount_paid": "",
  "tran_auth_id": "",
  "contact_number": "03001234567",
  "email": "john.doe@example.com",
  "reserved": "",
  "institution_id": "XXXXX",
  "institution_name": "Your Company Name"
}

Response Example — Consumer Not Found (01)

When response_Code is "01", return only the fields below. Do not include bill_status or any bill detail fields.

{
  "response_Code": "01",
  "response_description": "Consumer number not found."
}

Response Codes

Your API must return one of these codes in response_Code.

Code	Meaning
00	Bill found successfully.
01	Consumer number not found.
02	Voucher is blocked or inactive.
03	Unknown error or bad request.
04	Invalid data — wrong credentials or malformed request.
05	Server error — your API or ERP system failed internally.

Bill Payment Spec

Bill Payment Spec →