Your Gateway API Documentation

Simple payment gateway integration using KiliPay for merchants to collect payments securely.

1. Overview

Merchants use this API to initiate payments. Your Gateway handles communication with KiliPay and sends asynchronous payment status updates.

2. Authentication

Provide a valid merchant_key in your request to authenticate.

3. Payment Collection API (Payin)

Endpoint

POST https://yourgatewaydomain.com/api/payin.php

Request Headers

Header	Description
Content-Type	application/x-www-form-urlencoded

Request Parameters

Parameter	Required	Type	Description
merchant_key	Yes	string	Your unique merchant key
amount	Yes	float	Payment amount in PKR (integer)
currency	Yes	string	Currency code (usually "pkr")
txn_id	Yes	string	Unique transaction/order ID

Sample Request

POST /api/payin.php HTTP/1.1
Content-Type: application/x-www-form-urlencoded

merchant_key=abc123&amount=1000&currency=pkr&txn_id=order20250410xyz

Response

Field	Type	Description
status	string	"success" or "error"
message	string	Description message
transaction_id	string	Merchant's transaction ID
remark	string	Additional remarks
gateway_status	string	Status from KiliPay API
payment_url	string	URL to redirect user to payment

Sample Success Response

{
  "status": "success",
  "message": "Kili Fast initiated successfully",
  "transaction_id": "order20250410xyz",
  "remark": "Payment for TXN order20250410xyz",
  "gateway_status": "0015",
  "payment_url": "https://kilipay.com/payment/abc123"
}

Possible Errors

Missing parameters: {"status":"error","message":"Missing parameters"}
Invalid merchant_key: {"status":"error","message":"Invalid merchant key"}
Unsupported currency: {"status":"error","message":"Currency not supported"}
KiliPay API error: {"status":"error","message":"KiliPay error","details":"error message"}

4. Asynchronous Callback Notification

After payment completion, your gateway calls your configured webhook URL with payment status.

Callback URL

https://yourgatewaydomain.com/api/kilipay_callback.php

Callback POST Payload

Parameter	Type	Description
txn_id	string	Original transaction ID
status	string	Transaction status ("success" or "failed")
amount	string	Amount paid
order_sn	string	Order serial number (same as txn_id)
sign	string	Signature for verification

Important: Merchant must verify the signature and respond with OK to confirm receipt.

5. Integration Flow

Merchant generates unique txn_id (order number).
Merchant calls /payin.php API with merchant_key, amount, currency, txn_id.
Your gateway returns payment URL or status.
Merchant redirects user to payment URL to complete payment.
KiliPay processes payment.
Your gateway receives async callback from KiliPay.
Your gateway updates transaction and calls merchant webhook.
Merchant receives webhook and updates their system.

6. Support

If you face any issues integrating, contact: support@yourgatewaydomain.com