Webhooks

ParuPay POSTs the payment result to the URL you register, even when the customer never returns to your site. Your handler updates the order.

Register an endpoint

Webhooks are registered only in the merchant portal under Integrations → Webhooks. Add your public https:// URL, choose the events to receive (or * for every event), and save. One endpoint is allowed for sandbox and one for live. After you create the endpoint, the portal shows its signing secret (whsec_test_… or whsec_live_…). Store that secret on your server — you need it to verify deliveries. You can also send a sample event from the same screen to check your handler.

What ParuPay sends

POST https://your-store.example/webhooks/one9pay
Content-Type: application/json
User-Agent: ONE9PAY-Webhooks/1.0
X-One9Pay-Event: payment_intent.succeeded
X-One9Pay-Signature: t=sandbox,v1=0123456789abcdef

{
  "id": "evt_…",
  "object": "event",
  "type": "payment_intent.succeeded",
  "livemode": false,
  "data": {
    "object": {
      "id": "pi_…",
      "status": "succeeded",
      "amount": 1000,
      "currency": "usd",
      "metadata": { "order_id": "1042" }
    }
  }
}

Event	When it is sent
`payment_intent.succeeded`	Payment captured. Mark the order paid.
`payment_intent.payment_failed`	The card or one-time password failed.
`charge.refunded`	A full or partial refund was made on the charge.
`payment_intent.cancel`	Checkout was cancelled before the payment completed.

Metadata on webhooks contains only order_id. Look up everything else in your own database. Event types and data.object fields are listed above.

Verify and handle it

X-One9Pay-Signature is t=sandbox or t=live, then v1= and the last 16 characters of your webhook secret. Reject the request when the mode or the value does not match.

// Node.js (Express)
app.post('/webhooks/one9pay', express.json(), async (req, res) => {
  const [t, v1] = (req.get('X-One9Pay-Signature') || '').split(',');
  const mode = process.env.ONE9PAY_LIVE === 'true' ? 'live' : 'sandbox';
  const expected = process.env.ONE9PAY_WEBHOOK_SECRET.slice(-16);
  if (t !== `t=${mode}` || v1 !== `v1=${expected}`) return res.sendStatus(401);

  const event = req.body;
  const orderId = event.data.object.metadata?.order_id;

  // The same event can arrive twice: store event.id and skip it if already handled.
  if (await alreadyHandled(event.id)) return res.sendStatus(200);

  if (event.type === 'payment_intent.succeeded') await markOrderPaid(orderId);
  if (event.type === 'payment_intent.payment_failed') await markOrderFailed(orderId);
  if (event.type === 'charge.refunded') await markOrderRefunded(orderId);
  if (event.type === 'payment_intent.cancel') await markOrderCancelled(orderId);

  res.sendStatus(200);
});

Delivery rules

Respond with a 2xx status. Anything else, or no answer within 5 seconds, is recorded as failed.
Failed deliveries are not retried automatically. Send them again with POST /v1/charges/:id/resend_webhook or POST /v1/payment_links/:id/resend_webhook, or from the payment in the merchant portal.
Every attempt is logged. Read them with GET /v1/payments/:id/webhook_deliveries.
Check your handler from the merchant portal (Integrations → Webhooks → send a test), which posts a sample event (default payment_intent.succeeded).

Start

Accept payments

Developers

Register an endpoint

What ParuPay sends

Verify and handle it

Delivery rules