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 orrzp_test_partner_<client ID>in test mode. - Secret: The client secret of the same pair.
https://api.razorpay.com.
Scopes
The table below lists the scope each call needs. A call that the pair’s scopes do not cover returns403 with insufficient_scope.
Idempotency
Send theX-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
200again for 1 hour, with the response headerIdempotent-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:- Risk profile webhook: 1 event.
- Actions webhooks: 6 events.
- Clarifications webhooks: 4 events.
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:- Verify the signature:
X-Razorpay-Signatureis 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. - Acknowledge quickly: Respond with any
2xxwithin 5 sec, then do the work. Razorpay retries with exponential backoff for up to 24 h. - Expect repeats and any order: Process each
X-Razorpay-Event-Idonce. Order events bycreated_at, then by theupdated_atof 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.descriptionand each requirementdescriptionas Razorpay sends them. Branch your logic oncode, 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.