Webhooks

In addition to letting you poll the Check Order Status endpoint, Indicpay proactively notifies your server
the moment an order's status changes — for example, when a payment succeeds, fails, or is confirmed by the
bank/UPI network.

This means you don't need to keep polling POST /api/v1/order/search — simply configure a webhook URL and
Indicpay will POST a JSON payload to it in real time.

How it works

When creating an order, Indicpay associates it with your account's registered webhook URL.
As soon as the transaction's status is updated, Indicpay sends an HTTP POST request to that URL with the
transaction details.
Your endpoint should respond with a 200 OK to acknowledge receipt. If Indicpay doesn't receive a 200, the
webhook will be retried a limited number of times.

Example payload

{
  "txnid": "INPDUMMY0E31431CA",
  "merchantTxnId": "ORD1730900012345",
  "amount": "100.00",
  "rrn": "999999999999",
  "status": "Success",
  "payee": {
    "name": "Anita Verma",
    "vpa": "anita.verma@upiexample"
  },
  "metadata": {
    "udf1": "",
    "udf2": "",
    "udf3": ""
  },
  "datetime": "2026-07-28 07:25:27"
}

Field reference

Field	Type	Description
`txnid`	string	Indicpay's unique transaction ID — matches `data.transaction.id` from the Create/Search Order response.
`merchantTxnId`	string	The `order_id` you originally supplied — use this to match the webhook back to your internal order record.
`amount`	string	Final transaction amount.
`rrn`	string	Retrieval Reference Number issued by the bank/UPI network — useful for reconciliation and support queries.
`status`	string	One of `Initiate`, `Pending`, `Success`, `Failed`. See the status definitions below.
`payee.name`	string	Name registered against the payer's account/UPI ID (present for UPI payments).
`payee.vpa`	string	Payer's UPI ID (Virtual Payment Address), present for UPI payments.
`metadata`	object	Echo of the `udf1`/`udf2`/`udf3` values you sent when creating the order.
`datetime`	string	Timestamp of the event, in `YYYY-MM-DD HH:mm:ss` format (IST).

Transaction status values

Status	Meaning
`Initiate`	Order created; payment not yet attempted.
`Pending`	Payment in progress; awaiting confirmation from the bank/UPI network.
`Success`	Payment completed successfully.
`Failed`	Payment failed, was declined, or expired.

Best practices

Verify before you trust: treat the webhook as a signal to re-check the order, not as the sole source of
truth — call Check Order Status with merchantTxnId to confirm before releasing goods/services or
updating balances.
Make your handler idempotent: the same webhook can be delivered more than once (e.g. during retries) —
key your processing off txnid so duplicate deliveries don't double-credit an order.
Respond fast: return 200 OK immediately after saving the payload, then process it asynchronously if it
involves heavier work (emails, inventory updates, etc.).
Use HTTPS: your webhook URL must be a public HTTPS endpoint — Indicpay does not deliver webhooks over
plain HTTP.