Best Practices - Razorpay

Available in🇮🇳 India

Follow these rules so customers are charged once, orders are fulfilled only after payment is confirmed and nothing is missed when webhooks or banks go down. Run these after Orders and before your method pages.

Before You Test

You need these on your side, plus each method’s success and failure triggers. Every sub-page uses them.

Tool	Used by
A public HTTPS URL for test-mode webhooks (staging, or a tunnel) with a webhook secret	Webhooks, Fetch APIs, Payment states
A switch that makes your webhook endpoint return `500`, or sleep 10 seconds	BP-04, BP-11
A store of raw webhook bodies and headers, and a script to replay one (or a changed copy)	BP-03, BP-06, BP-10, BP-37
A reconciler you can run on demand	BP-04, BP-05, BP-20
A way to drop an API response (proxy or fault injection)	BP-07, BP-08, BP-12

Webhooks set up in Test Mode do not carry over to live mode. Set them up again before you go live.

Best Practices

#	Topic	What it covers
1	Integrate the Right Way	Use S2S JSON V2 correctly: create an order first, forward real customer values, act on the webhook.
2	Order–Payment Relationship	The order and payment state machine; fulfil only when the order is `paid`.
3	Integration Health: Webhooks and Fetch APIs	Which events to subscribe to, webhook vs. fetch, design principles, scenarios, gaps and failures to simulate.
4	Payment States and Late Authorisation	Keep orders open after `payment.failed`; handle late authorisation, manual capture and repeat payments.
5	Error Handling	Branch on `error.code`, `reason` and `source`; errors available per method in Test Mode.
6	Retries and Idempotency	Make every retried call safe to repeat with `unique_receipt` and retries on the same order.
7	Downtime Handling	Hide methods that are down using Payment Downtime webhooks and the Downtime API; restore on `resolved`.
8	Security	Protect keys, verify payment and webhook signatures, keep amounts server-side.
9	Refunds	Test Normal and Instant refunds, failures and the Instant-to-Normal fallback. Covered in its own Refunds page.

Last modified on November 12, 2026