KontakPay API

Accept UPI payments from customers in India (payins) and send money to Indian bank accounts (payouts) through one REST API. All amounts are in INR.

How it works

1. Create a payin with the amount and your own order_id. You get a payment_link (our hosted payment page) and raw UPI links.
2. Show the payment — open the payment_link, embed it in an iframe, or build your own UI with the UPI links / QR string.
3. Receive a webhook (PAYIN_SUCCESS, PAYIN_FAILED or PAYIN_EXPIRED) and fulfil the order. You can also poll Get a payin.
4. Send payouts (if enabled on your account) from your payout balance to any Indian bank account.

Response format

Every successful response is wrapped in { "success": true, "data": … }. Errors return { "success": false, "error_code", "message", "field" } — see Errors. Fields only appear when they carry a value; there are no null placeholders.

Authentication

Every request carries your API key as a Bearer token:

Create and manage keys in the merchant dashboard under API Keys. Each key has its own webhook secret, shown once together with the key.

• Keep keys on your server. Never put them in a browser or mobile app.
• Rotate a key from the dashboard if it leaks: the old key and its webhook secret stop working immediately. Webhook URLs are kept.
• A missing or unknown key returns 401 UNAUTHORIZED; a revoked key returns 401 KEY_REVOKED.

Amounts & IDs

Amounts

Amounts are INR with at most two decimals. In requests you can send a number or a string — 500, 500.5, 500.00 and "500.00" are all accepted. Responses always return a string with two decimals, e.g. "1500.00".

IDs

Idempotency

Send an optional idempotency_key (up to 128 characters) in the body of Create a payin and Create a payout to retry safely after a timeout or network error.

• Same key, same body → the original record is returned with 200 instead of creating a new one.
• Same key, different body → 409 DUPLICATE_IDEMPOTENCY_KEY.
• Keys are kept for 24 hours, per merchant.

Webhooks

Set a webhook URL on your API key in the dashboard (optionally a separate payout webhook URL). We POST an event there every time a payin or payout reaches a new status. The URL is copied onto each payment when it is created, so changing it later never loses a notification.

Payload

data is exactly what Get a payin / Get a payout returns.

Headers

Verify the signature

Compute the HMAC over the raw request body (before any JSON parsing), compare in constant time, and reject requests older than 5 minutes.

Retries & best practices

Reply with any 2xx within 10 seconds. Otherwise we retry up to 6 more times: 30s → 5m → 30m → 2h → 6h → 24h. Redirects are not followed.

• Respond first, then process — keep the handler fast.
• Events can arrive more than once or out of order. De-duplicate on x-webhook-delivery-id and trust the status in data, not the arrival order.
• Webhook URLs must be public https addresses.
• Failed deliveries can be retried from the dashboard under Webhooks.

Payment page & iframe

payment_link opens our hosted payment page: UPI app buttons or a QR code, a countdown, and the result — updated live. Redirect the customer to it, or embed it in your checkout:

When the payment finishes, the page sends a message to the parent window. Use it to update your UI; always confirm with the webhook (or Get a payin) before fulfilling the order.

Errors

Errors return an HTTP status and a JSON body: