Bill Initiators

Bill Initiator APIs

Call Kuickpay's V3 REST APIs to look up and pay bills on behalf of consumers. Three calls: GetBillers → BillInquiryV3 → BillPaymentV3.

Base URLhttps://sandbox-kpcore.kuickpay.com

Which billers do you want to integrate?

Authentication

Pass these two headers on every request. Obtain them from business.kuickpay.com.

X-API-KEYYour Bill Initiator API key.

IN-IDYour Bill Initiator ID.

HTTP Headers

X-API-KEY: your_api_key
IN-ID: your_initiator_id
Content-Type: application/json

Missing or invalid headers return HTTP 401. Your server IP must also be whitelisted in the Business Portal.

POSTGet Billers

/api/GetBillers

Returns all active billers and their mnemonic codes. Cache this list — it changes infrequently.

Request

Field	Type	Req	Description
`reserved`	string	O	Optional. Pass empty string.

Request

POST /api/GetBillers

{
  "reserved": ""
}

Response

{
  "response_Code": "00",
  "response_description": "Success",
  "billers": [
    { "mnemonic": "SSGC", "name": "Sui Southern Gas Company", "category": "Utilities" },
    { "mnemonic": "LESCO", "name": "Lahore Electric Supply Co.", "category": "Utilities" }
  ]
}

POSTBill Inquiry V3

/api/BillInquiryV3

Look up a consumer's bill. Save the tran_auth_id from the response — it's required for payment.

Request Parameters

Field	Type	Req	Description
`BillerID`	string	O	Biller ID from GetBillers (same as the first 5 digits of consumer_number). Optional for Kuickpay billers.
`consumer_number`	string	M	Consumer's account/reference number.
`bank_mnemonic`	string	M	Biller code from GetBillers. e.g. SSGC, LESCO.
`reserved`	string	O	Optional.

Request

POST /api/BillInquiryV3

{
  "BillerID": "XXXXX",
  "consumer_number": "1234567890",
  "bank_mnemonic": "SSGC",
  "reserved": ""
}

Response

Field	Type	Req	Description
`response_Code`	string	M	00=Found, 01=Not found, 02=Blocked, 03=Unknown, 04=Invalid, 05=Failed, 06=Paid
`consumer_name`	string	M	Consumer name.
`bill_status`	string	M	U=Unpaid, P=Paid, B=Blocked.
`due_date`	string	M	yyyyMMdd
`amount_within_due_date`	string	M	Amount in paisa. 25000 = Rs. 250.00
`amount_after_due_date`	string	M	Surcharge amount in paisa.
`billing_month`	string	M	MMYY e.g. 0525
`tran_auth_id`	string	M	Pass this in the Bill Payment request.

Success Response (Unpaid)

{
  "response_Code": "00",
  "response_description": "Bill found",
  "consumer_name": "MUHAMMAD ALI",
  "bill_status": "U",
  "due_date": "20250531",
  "amount_within_due_date": "25000",
  "amount_after_due_date": "27500",
  "billing_month": "0525",
  "tran_auth_id": "698243"
}

Code	Meaning
00	Bill found — proceed to payment
01	Consumer number not found
02	Consumer blocked or inactive
03	Unknown error or bad request
04	Invalid data or credentials
05	Server error — retry
06	Bill already paid
401	Unauthorized — check X-API-KEY / IN-ID / IP whitelist

POSTBill Payment V3

/api/BillPaymentV3

Confirm payment after a successful inquiry. Use tran_auth_id from the inquiry response.

Request Parameters

Field	Type	Req	Description
`BillerID`	string	O	Biller ID from GetBillers (same as the first 5 digits of consumer_number). Optional for Kuickpay billers.
`consumer_number`	string	M	Same number used in inquiry.
`bank_mnemonic`	string	M	Same mnemonic used in inquiry.
`tran_auth_id`	string	M	Value returned by BillInquiryV3.
`paid_amount`	string	M	Amount in paisa. Must match amount_within_due_date.
`billing_month`	string	M	MMYY from inquiry response.
`reserved`	string	O	Optional.

Request

POST /api/BillPaymentV3

{
  "BillerID": "XXXXX",
  "consumer_number": "1234567890",
  "bank_mnemonic": "SSGC",
  "tran_auth_id": "698243",
  "paid_amount": "25000",
  "billing_month": "0525",
  "reserved": ""
}

Success Response

{
  "response_Code": "00",
  "response_description": "Payment successful",
  "tran_auth_id": "698243",
  "receipt_id": "KP20250507001234"
}

Code	Meaning
00	Payment processed successfully
01	Consumer not found
02	Consumer blocked
03	Duplicate or unknown transaction
04	Invalid data or credentials
05	Server error — verify before retrying; may have processed
06	Bill already paid
401	Unauthorized — check headers and IP whitelist