Integration Health: Webhooks and Fetch APIs

Available in🇮🇳 India

Webhooks are your source of truth; fetch APIs are your safety net. Build one state machine that both feed. Test it: subscribe to the events your method pages list. Verify the X-Razorpay-Signature header on every webhook, store event IDs and skip repeats and handle out-of-order and duplicate events. Confirm your reconciler recovers a missed webhook by calling GET /v1/orders/:id/payments. Bare-minimum events

Event	What to do
`payment.captured` or `order.paid`	The payment is captured: fulfil the order. `order.paid` carries both the order and the payment. Required.
`payment.failed`	Mark the attempt as failed and keep the order open. Required.
`payment.authorized`	Capture the payment if you capture manually. Required if manual capture.
`refund.processed`, `refund.failed`	Update the order and tell the customer. Required.

Recommended events

Event	What to do
`payment.downtime.started`, `updated`, `resolved`	Hide or restore a method. See Downtime Handling.
`token.confirmed`, `rejected`, `paused`, `cancelled`	Recurring only. Tested on Card recurring and UPI Autopay. On Card recurring, customer-driven pause and cancel are coming soon in Test Mode; cancelling through the Delete Token API works today.
`payment.dispute.created`	Pause fulfilment and gather evidence.

Handle every event correctly

Reply 2xx within 5 seconds, then process the event in the background.
Check that the webhook came from Razorpay: recompute X-Razorpay-Signature over the raw body before parsing.
Ignore duplicates using the x-razorpay-event-id header.
Do not rely on the order of events. Never move an order back from paid.

When webhooks are down

What happened	What Razorpay does	What you do
Your endpoint fails or times out	Retries for 24 hours, then disables the webhook and emails you	Fix the endpoint, re-enable the webhook, then fetch every order from the outage window
Webhooks are delayed	Delivers them late	Your reconciler fetches orders still pending after 15 minutes

Webhook or fetch?

You need to	Use	Why
Decide when to fulfil	Webhook: `payment.captured` or `order.paid`	It is pushed to you as soon as the payment is captured.
Know an attempt failed	Webhook: `payment.failed`. Fallback: `GET /v1/orders/:id/payments`	Mark the attempt failed and keep the order open.
Capture, if you capture manually	Webhook: `payment.authorized`. Fallback: `GET /v1/payments/:id`	Capture inside your capture window, or it is refunded.
Track a refund	Webhooks: `refund.processed`, `refund.failed`. Fallback: `GET /v1/payments/:id/refunds`	Update the order and tell the customer.
Show the customer a result after the callback	Verify the signature; fetch the payment once if unsure	The webhook may land a few seconds after the customer returns.
Catch up on a payment with no webhook after 15 minutes	Fetch: `GET /v1/orders/:id/payments`	Covers delayed or failed webhooks.
Recover after your endpoint was down	Fetch every order from the outage window	Webhooks retried for 24 hours may have been disabled.
Reconcile every day	Fetch payments and settlements by date	Confirms your books match Razorpay’s.

Design principles: one state machine, two inputs — webhooks and fetches update the same order record through the same code. Forward-only — ignore any update that would move a payment or order back; accept failed → authorized as a late authorisation. Back off — fetch a pending order a few times with growing gaps, then leave it to the reconciler. Idempotent — processing the same update twice changes nothing. APIs you’ll use

Purpose	API	Available on test mode
Create an order	`POST /v1/orders`	Available
Create a payment	`POST /v1/payments/create/json` (redirect: `/create/redirect`)	Available
Submit or resend OTP	`otp_submit` / `otp_resend` URLs in `next[]`	Available (cards)
Fetch a payment	`GET /v1/payments/:id`	Available
Fetch an order’s payments	`GET /v1/orders/:id/payments`	Available
Capture	`POST /v1/payments/:id/capture`	Coming soon (cards)
Refund	`POST /v1/payments/:id/refund`	Available
Fetch downtimes	`GET /v1/payments/downtimes`	Coming soon
Recurring: tokens and charges	`GET /v1/customers/:id/tokens`, `POST /v1/payments/create/recurring`	Available
Settlements	`GET /v1/settlements`	Live only

Scenarios to test your integration

Scenario ID	Area	Scenario	Trigger	Steps to follow	Test mode
BP-19	Setup	Subscribe to the bare-minimum events	Dashboard → Webhooks (Test Mode)	Subscribe to `order.paid` or `payment.captured`, `payment.failed`, `refund.processed`, `refund.failed` (and `payment.authorized` if you capture manually). Run a success and failure trigger on a method page and confirm each event arrives.	Available
BP-01	Fulfilment	Fulfil on the webhook, not the callback	Any success trigger	Pay, then drop the callback (close the tab or skip your handler). Confirm the order is fulfilled once, from the webhook.	Available
BP-03	Handling	Duplicate webhook	Replay a stored event	Replay the same event. Confirm it is processed once, keyed on `x-razorpay-event-id`.	Available
BP-30	Fulfilment	Customer closes the browser before the callback	Any success trigger	Same as BP-01: the webhook (or a fetch) still drives fulfilment.	Available
BP-04	Outage	Endpoint down, then recovery	Make your endpoint return `500`	Return `500` for a few minutes and make two payments. Run the reconciler; confirm both orders settle. Restore the endpoint; confirm late retries are ignored as duplicates.	Available
BP-05	Fallback	No webhook: fetch fallback	Unsubscribe from `order.paid`/`payment.captured`	Pay with a success trigger. Confirm your reconciler resolves it with `GET /v1/orders/:id/payments`, with back-off.	Available
BP-31	Any	Webhook delayed or missed	Unsubscribe from the event	Same as BP-05: fetch `GET /v1/orders/:id/payments` after 15 minutes and act on the result.	Available
BP-20	Reconciler	Reconcile pending orders after 15 minutes	Orders left `created` and `attempted`	Leave one order unpaid and fail one payment. Run the reconciler: it fetches both after 15 minutes and fulfils, waits or closes each.	Available
BP-10	Handling	Events arrive out of order	Replay `payment.failed` after `order.paid`	Replay the older event last. Confirm the order stays `paid`.	Available
BP-11	Handling	Reply within 5 seconds	Make your handler sleep 10 seconds	Confirm you reply `2xx` within 5 seconds and process the event in the background.	Available
BP-21	Callback	Show a result after the callback	A success trigger, webhook delayed	Verify the signature in the callback. If unsure, fetch the payment once (`GET /v1/payments/:id`) and show the result. Confirm fulfilment still waits for the webhook or the reconciler.	Available
BP-22	Design	One state machine, forward-only	Feed the same update by webhook and by fetch	Process a webhook, then the same state from a fetch. Confirm nothing changes the second time, and a paid order never moves back. Confirm `failed` → `authorized` is accepted (late authorisation).	Available
BP-23	Reconciler	Daily reconciliation	Fetch payments and settlements by date	Fetch yesterday’s payments and settlements. Confirm your records match.	Live only

Scenario details

BP-01 — Fulfil on the webhook, not the callback Before you start: webhook subscribed to order.paid (or payment.captured) and payment.failed. How to test: create an order and pay it with a success trigger. Do not run your callback handler (as if the customer closed the browser). Wait for the webhook. Expected result: the order is fulfilled once, from the webhook (payment.captured, order.paid). Your integration should: treat the callback as a hint — verify the signature and show a result, but fulfil only from the webhook or a fetch. BP-03 · BP-10 — Duplicate and out-of-order webhooks Before you start: a stored order.paid and an earlier payment.failed for the same order. How to test: replay order.paid with the same x-razorpay-event-id. Replay the earlier payment.failed after order.paid. Expected result: nothing changes — the duplicate is ignored and the order stays paid. Your integration should: key processing on x-razorpay-event-id; move states forward only. BP-04 — Endpoint down, then recovery Before you start: a reconciler you can run on demand. How to test: make your endpoint return 500. Pay two orders: one success, one failure. Run the reconciler. Restore the endpoint and let retries arrive. Expected result: both orders reach the right state from the reconciler; later retries are ignored. Your integration should: after a real outage, re-enable the webhook on the Dashboard and fetch every order from the outage window. Live mode differs: Razorpay retries for 24 hours, then disables the webhook. BP-05 · BP-20 — Fetch fallback and the reconciler Before you start: a reconciler you can run on demand; no webhook subscription for the success event. How to test: pay one order with a success trigger. Leave a second order unpaid; fail a payment on a third. Run the reconciler: it fetches GET /v1/orders/:id/payments for orders still created/attempted after 15 minutes. Expected result: the paid order is fulfilled; the other two stay open, or are closed by your own timeout. Your integration should: back off between fetches and never poll in a tight loop.

Webhooks: What Fires, and What It Lets You Decide

Every scenario above delivers a specific set of events, in a specific order. This table is the one place that says which, and — the part that actually matters — what each one entitles you to do. Most integration bugs that reach production are not missing webhooks; they are acting on the wrong one.

Scenario	What it is	Events, in order	What it lets you decide
BP-19	Subscribe to the bare-minimum events	`order.paid`, `payment.captured`, `payment.failed`, `refund.processed`, `refund.failed`, `payment.authorized`	The order is settled and will not accept another payment: close the cart and stop any retry loop, and money is yours — this is the event to fulfil on. This attempt is over: the error reason tells you whether to offer the same method again or move the customer to another one. The money has left Razorpay: this is when you confirm the refund to the customer. The refund did not go through: it needs a retry or a manual payout, it will not resolve itself. Money is held, not yet yours: do not fulfil on this alone.
BP-01	Fulfil on the webhook, not the callback	`payment.captured`, `order.paid`	Money is yours. This is the event to fulfil on. The order is settled and will not accept another payment: close the cart and stop any retry loop.

Before you trust any of them

Verify the signature on every event. Replay one event to your endpoint and send one with a changed body. The replay must be ignored and the tampered event rejected. An endpoint that skips this is an open write to your order state.
Expect duplicates. The same event can arrive more than once. Key your handler on the event ID and make it idempotent.
Order is not guaranteed across events. Do not assume payment.captured lands before order.paid; handle whichever arrives first.
Webhook first, callback second. The browser callback can be lost, blocked or forged. Fulfil on the webhook.

Common integration gaps to avoid

Gap	What goes wrong in production	What to do	Test with
Shipping on the callback	Uncaptured payments are refunded after you have shipped.	Fulfil on `order.paid`.	BP-01
Slow webhook endpoint	The webhook is disabled after 24 hours of failures.	Reply `2xx` right away and queue the work.	BP-11
No duplicate check	The order is fulfilled twice.	Check `x-razorpay-event-id`.	BP-03
Not re-enabling after an outage	Every later payment needs the reconciler.	Alert on the disable email; re-enable and backfill.	BP-04
Test webhooks assumed in live	No events arrive after go-live.	Set up live-mode webhooks again.	BP-19
No reconciler	Payments made during a webhook outage are never recorded.	Fetch orders still `created`/`attempted` after 15 minutes.	BP-20
Polling in a tight loop	You hit rate limits and still miss the result.	Back off; leave the rest to the reconciler.	BP-05
Two code paths for webhook and fetch	The same payment is processed differently, or twice.	One state machine, forward-only and idempotent.	BP-22

Simulate failures

Available in test mode

Failure	How to simulate	Expected handling	Scenario
Endpoint returns 5xx	Return `500`	Reconciler settles; late retries ignored	BP-04
Slow endpoint	Sleep 10 seconds	`2xx` within 5 seconds	BP-11
Duplicate event	Replay an event	Processed once	BP-03
Out-of-order event	Replay an older event last	State does not move back	BP-10
Tampered event	Change the body	Rejected	BP-37
Webhook missing	Unsubscribe from the event	Fetch fallback with back-off	BP-05
Callback before webhook	Delay your webhook handler	Fetch once to show the result; fulfil later	BP-21

Not available in test mode

Failure	Why not	How to cover it
Webhook disabled after 24 hours of failures	Not simulated	Alert on the email; re-enable and backfill
Settlement mismatches	Settlements are live only	Daily reconciliation in live (BP-23)

1. Build Integration

2. Test S2S Integration

3. Go Live Checklist

Features

Integration Health: Webhooks and Fetch APIs

Webhook or fetch?

Scenarios to test your integration

Scenario details

Webhooks: What Fires, and What It Lets You Decide

Common integration gaps to avoid

Simulate failures

Which events to subscribe to

Webhook or fetch?

Scenarios to test your integration

Scenario details

Webhooks: What Fires, and What It Lets You Decide

Common integration gaps to avoid

Simulate failures

Related Information