> ## Documentation Index
> Fetch the complete documentation index at: https://razorpay.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Merchant Risk APIs for Partner Platforms

> Read Razorpay's risk profile of each sub-merchant, act on its payments and settlement, and answer Razorpay's risk clarifications through the Accounts API.

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.

> [card] [Risk Profile](https://razorpay.com/docs/partners/aggregators/merchant-risk/risk-profile.md)
>
> Razorpay's risk rating of the sub-merchant. Read it on the account and receive a webhook when it changes.

> [card] [Actions](https://razorpay.com/docs/partners/aggregators/merchant-risk/actions.md)
>
> Disable payments, put settlement on hold or suspend the product, and reverse your own actions. See what Razorpay has done.

> [card] [Clarifications](https://razorpay.com/docs/partners/aggregators/merchant-risk/clarifications.md)
>
> 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:

```mermaid theme={null}
flowchart TD
  A["account"] --> RP["risk_profile.rating"]
  A --> PG["products.payment_gateway<br/>status: activated | suspended"]
  PG --> PA["payment_acceptance<br/>status: enabled | disabled<br/>status_reason"]
  PG --> ST["settlement<br/>status: enabled | on_hold<br/>status_reason"]
  PG --> RQ["requirements"]
  RQ --> C["requirement req_UYTBV02QSYTRVK<br/>with sub_requirements"]
  PA -. "status_reason.requirement_id" .-> C
  ST -. "status_reason.requirement_id" .-> C
```

The table below lists each part, where it lives and where to read more:

| Part | Field on the Account | Set By | Explanation | API | Webhooks |
| - | - | - | - | - | - |
| Risk profile | `risk_profile.rating` | Razorpay | [Risk profile](https://razorpay.com/docs/partners/aggregators/merchant-risk/risk-profile.md) | [API and webhooks](https://razorpay.com/docs/api/partners/accounts/merchant-risk/risk-profile.md) | [Risk profile webhook](https://razorpay.com/docs/api/partners/accounts/merchant-risk/risk-profile.md#webhook) |
| Suspension | `products.payment_gateway.status` | Razorpay or you | [Actions](https://razorpay.com/docs/partners/aggregators/merchant-risk/actions.md) | [Partner actions API](https://razorpay.com/docs/api/partners/accounts/merchant-risk/actions.md) | [Actions webhooks](https://razorpay.com/docs/partners/aggregators/merchant-risk/actions-webhooks.md) |
| Payment acceptance | `products.payment_gateway.payment_acceptance` | Razorpay or you | [Actions](https://razorpay.com/docs/partners/aggregators/merchant-risk/actions.md) | [Partner actions API](https://razorpay.com/docs/api/partners/accounts/merchant-risk/actions.md) | [Actions webhooks](https://razorpay.com/docs/partners/aggregators/merchant-risk/actions-webhooks.md) |
| Settlement | `products.payment_gateway.settlement` | Razorpay or you | [Actions](https://razorpay.com/docs/partners/aggregators/merchant-risk/actions.md) | [Partner actions API](https://razorpay.com/docs/api/partners/accounts/merchant-risk/actions.md) | [Actions webhooks](https://razorpay.com/docs/partners/aggregators/merchant-risk/actions-webhooks.md) |
| Clarifications | `products.payment_gateway.requirements` | Razorpay raises, you respond | [Clarifications](https://razorpay.com/docs/partners/aggregators/merchant-risk/clarifications.md) | [Clarifications API](https://razorpay.com/docs/api/partners/accounts/merchant-risk/clarifications.md) | [Clarifications webhooks](https://razorpay.com/docs/partners/aggregators/merchant-risk/clarifications-webhooks.md) |

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:

| Term | Meaning |
| - | - |
| Partner platform, or you | The business that onboards sub-merchants through the Onboarding APIs and acts on them. |
| Sub-merchant | A business on your platform with a Razorpay account. |
| Risk rating | Razorpay's risk rating of the sub-merchant: `low`, `medium`, `high` or `not_rated`. |
| Action | A change to payment acceptance (`disable_payments`, `enable_payments`), settlement (`disable_settlement`, `enable_settlement`) or the product (`suspend`, `unsuspend`). |
| Suspension | The `payment_gateway` product is `suspended`. Payment acceptance and settlement are both stopped. |
| Clarification | A requirement Razorpay raises after a risk review: questions and document requests, with its own `id`. |

## 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`.

| Call | Scope |
| - | - |
| [Fetch an account](https://razorpay.com/docs/api/partners/accounts/merchant-risk/risk-profile.md): risk profile, actions and requirements | `onboarding_accounts_read` |
| [Partner actions](https://razorpay.com/docs/api/partners/accounts/merchant-risk/actions.md): suspend, disable or enable | `onboarding_accounts_write` |
| [Answer requirements](https://razorpay.com/docs/api/partners/accounts/merchant-risk/clarifications.md#answer-requirements) | `onboarding_accounts_write` |
| [Upload a document](https://razorpay.com/docs/api/partners/accounts/merchant-risk/clarifications.md#upload-a-document) | `onboarding_documents_write` |

### 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](https://razorpay.com/docs/partners/aggregators/merchant-risk/actions.md).

## 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](https://razorpay.com/docs/api/partners/accounts/merchant-risk/risk-profile.md#webhook): 1 event.
* [Actions webhooks](https://razorpay.com/docs/partners/aggregators/merchant-risk/actions-webhooks.md): 6 events.
* [Clarifications webhooks](https://razorpay.com/docs/partners/aggregators/merchant-risk/clarifications-webhooks.md): 4 events.

> [!WARNING]
>
> **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](https://razorpay.com/docs/api/partners/accounts/merchant-risk/risk-profile.md).

### 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.

| Field | Description |
| - | - |
| `entity` | Always `event`. |
| `account_id` | The account the event is about. |
| `event` | The event name, such as `account.product.payment_gateway.settlement.on_hold`. |
| `payload.account` | What changed on the account. |
| `created_at` | Unix timestamp at which the event happened. |

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

| Practice | Why |
| - | - |
| Read `status` on `payment_acceptance` and `settlement`, not the product status alone. | `status` is the effective state. Settlement can be on hold while the product is `activated`. |
| Store the state of each object when an event arrives. | Each event carries the new state. Compare it with what you stored to see what changed. |
| Process each `X-Razorpay-Event-Id` once, and order events by `created_at`. | Events can repeat and arrive out of order. |
| Follow `status_reason.requirement_id` from an action to its requirement. | It tells the sub-merchant what to answer to get the action reviewed. |
| Send every response of a clarification in one update. | Razorpay reviews the responses together. |
| Use `partner_other` only with a clear `description`. | The sub-merchant and Razorpay see it. |
| Reverse your own actions once the reason is gone. | Razorpay never reverses an action you took, except that reversing a suspension clears earlier actions. |

## Reference

* [Errors](https://razorpay.com/docs/api/partners/accounts/merchant-risk/errors.md)
* [Reason codes](https://razorpay.com/docs/api/partners/accounts/merchant-risk/reason-codes.md)
