Institution/End-to-End/Bill Payment Spec

Bill Payment — API Specification

This is the spec for the API you build. After the consumer confirms payment, Kuickpay calls this endpoint to record the payment in your system. You must mark the bill as paid and return a confirmation.

What to build

Expose a POST endpoint. When called, mark the bill as paid in your DB using thetran_auth_idas the payment reference.

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

Idempotency

If a duplicate transaction is received, return response_Code: "03".

If a bill is already paid and the customer attempts repayment, validate all four of the following. If they all match, return "03":

Consumer number
Date paid
tran_auth_id
Amount paid

In case of mismatch, return response_Code: "04" with message "Transaction mismatch".

Note: Do not restrict tran_auth_id to a single consumer number. Two different banks may send the same tran_auth_id simultaneously for different consumers.

Request (Kuickpay sends this)

Request Parameters

Parameter	Type	Required	Max Length	Description
`consumer_number`	numeric	required	18	Consumer/account number. Numeric characters only.
`bank_mnemonic`	string	optional	7	Short code of the payment channel. Optional.
`tran_auth_id`	numeric	required	6	Transaction auth ID generated by the payment channel. Numeric characters only. Used for idempotency.
`paid_amount`	string	required	12	2500
`tran_date`	string	required	8	Transaction date in YYYYMMDD format (e.g. "20250615").
`tran_time`	string	required	6	Transaction time in HHMMSS format (e.g. "143025").
`reserved`	string	optional	100	Optional metadata.

Request Example

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

{
  "consumer_number": "XXXXX0000000000001",
  "bank_mnemonic": "MCB",
  "tran_auth_id": "123456",
  "paid_amount": "250000",
  "tran_date": "20250615",
  "tran_time": "143025",
  "reserved": ""
}

Response (you return this)

Response Parameters

Parameter	Type	Required	Max Length	Description
`response_Code`	string	required	2	"00" = Success, "01" = Invalid Voucher Number, "03" = Already Paid, "05" = Error.
`response_description`	string	required	100	Human-readable result message.
`Identification_parameter`	string	required	50	Your internal payment reference. Returned as-is by Kuickpay.
`reserved`	string	optional	100	Optional.

Response Example — Success

{
  "response_Code": "00",
  "response_description": "Payment Successful",
  "Identification_parameter": "YOUR-INTERNAL-REF-001",
  "reserved": ""
}

Response Codes

Your API must return one of these codes in response_Code.

Code	Meaning
00	Success.
01	Invalid Voucher Number.
02	Voucher is blocked. Payment not allowed.
03	Already paid — duplicate tran_auth_id received.
04	Invalid data — missing/wrong fields or bad credentials.
05	Server error — your API or ERP system failed internally.

Hybrid Integration — Insert Voucher

Insert Voucher →