Skip to main content
Available in🇮🇳 India
Use the Merchant Risk APIs to see how Razorpay rates each sub-merchant, whether it can take payments and be settled right now, and what Razorpay needs from it after a risk review. You can also disable payments or settlement for a sub-merchant yourself, or suspend it, when your own checks find a problem. Everything here sits on the account you already use for onboarding, on its payment_gateway product. There is no separate risk resource to create or poll.

Risk Profile

Razorpay’s risk rating of the sub-merchant. Read it on the account and receive a webhook when it changes.

Actions

Disable payments, put settlement on hold or suspend the product, and reverse your own actions. See what Razorpay has done.

Clarifications

Requirements Razorpay raises after a risk review. Read them on the account, upload documents and send your responses.

How the Sections Fit Together

The diagram below shows where each part sits on the account: The table below lists each part, where it lives and where to read more: An action points to the requirement that must be answered to reverse it, through status_reason.requirement_id. A requirement never carries state about actions. The table below lists the terms these pages use:

Authenticate Your Platform

The Merchant Risk APIs use the same app, credentials and headers as the Onboarding APIs. Authenticate every request with HTTP Basic auth, using the client ID and secret of your app from the Razorpay Partner Dashboard:
  • Key: rzp_live_partner_<client ID> in live mode or rzp_test_partner_<client ID> in test mode.
  • Secret: The client secret of the same pair.
The key’s prefix sets the mode. Live mode and test mode share one base URL, https://api.razorpay.com.

Scopes

The table below lists the scope each call needs. A call that the pair’s scopes do not cover returns 403 with insufficient_scope.

Idempotency

Send the X-Idempotency-Key header on every write (POST and PATCH). Generate a unique key for each operation, 16-64 printable ASCII characters long.
  • Partner actions: The same key with the same request returns the first 200 again for 1 hour, with the response header Idempotent-Replayed: true. A refused or failed request holds no key, so a retry with the same key runs again.
  • Answers and uploads: A retry with the same key and body within 24 h returns the original response.

Partner Actions Switch

suspend, disable_payments and disable_settlement need partner actions switched on for your platform. Razorpay switches them on per platform. Without them, these calls return 403 with partner_actions_not_enabled. Reversing your own action always works. Know more about actions.

Receive Webhooks

Webhooks notify your server when something changes in a sub-merchant’s risk state. Each section lists its own events:
Watch Out!Webhooks are optional, and Razorpay delivers them asynchronously. Fetching the account stays the source of truth. If a flow needs the current state and the event has not arrived, fetch the account.

Subscribe and Handle

Subscribe on the Partner Dashboard, once per mode, with the same URL and secret you use for the Onboarding APIs. Events for test-mode accounts go to the test-mode subscription. Follow the same rules as for every onboarding event:
  1. Verify the signature: X-Razorpay-Signature is a hex-encoded HMAC-SHA256 of the raw request body, keyed with your secret. Compare in constant time, and reject the event if it does not match.
  2. Acknowledge quickly: Respond with any 2xx within 5 sec, then do the work. Razorpay retries with exponential backoff for up to 24 h.
  3. Expect repeats and any order: Process each X-Razorpay-Event-Id once. Order events by created_at, then by the updated_at of the object that changed.

Event Structure

Each event carries what changed, not the whole account. payload.account has the account’s id, plus each part that changed, in full, at its own path. Each event carries only the new state. To see what changed, compare it with the state you stored for the account. Each delivery carries the event’s ID in the X-Razorpay-Event-Id header, the same on every retry. An event fires on every change, including one your own call caused.

Your Responsibilities

As the partner platform, you take on these duties:
  • Show Razorpay’s text unchanged: Show the sub-merchant each status_reason.description and each requirement description as Razorpay sends them. Branch your logic on code, never on text.
  • Pass on clarifications in time: Show every requirement to the sub-merchant and send the responses before due_at. A late answer can lead Razorpay to disable payments or put settlement on hold.
  • Act only for a reason: Use an action only for one of your partner_* reasons, and reverse it once the reason is gone.
  • Keep the API as the source of truth: When your records and the account disagree, the account is right. Fetch it when an event is late.

Best Practices

Reference

Last modified on November 20, 2026