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

# Risk Clarifications on a Sub-Merchant

> How Razorpay asks a sub-merchant for answers and documents after a risk review: the requirement on the payment_gateway product, its statuses and how you respond.

Available in🇮🇳 India

When a risk review needs answers from the sub-merchant, Razorpay raises a requirement on the account's `payment_gateway` product, at `products.payment_gateway.requirements`. You read it with the GET account API and answer it by uploading documents and updating the account.

Raising a requirement does not change the product's `status`. Only an [action](https://razorpay.com/docs/partners/aggregators/merchant-risk/actions.md) changes what the sub-merchant can do.

## The Journey

```mermaid theme={null}
sequenceDiagram
  participant R as Razorpay
  participant P as Your platform
  participant M as Sub-merchant
  R->>P: Webhook requirement.needs_clarification
  P->>R: GET /v1/accounts/:id
  P->>M: Show each requirement description
  M->>P: Answers and files
  P->>R: POST /v1/accounts/:id/documents/:document_type (one per file)
  P->>R: PATCH /v1/accounts/:id with every requirement_response
  R->>P: Webhook requirement.under_review
  alt Razorpay needs more
    R->>P: Webhook requirement.needs_clarification
  else Razorpay decides
    R->>P: Webhook requirement.resolved
  end
```

**1. Razorpay Raises a Requirement**

`account.product.payment_gateway.requirement.needs_clarification` arrives with the requirement, in `needs_clarification`. Razorpay may also take an action that points to it through `status_reason.requirement_id`. Know more about [clarifications webhooks](https://razorpay.com/docs/partners/aggregators/merchant-risk/clarifications-webhooks.md).

**2. Fetch the Account**

[Fetch the account](https://razorpay.com/docs/api/partners/accounts/merchant-risk/clarifications.md#fetch-the-requirements). The requirement sits at `products.payment_gateway.requirements`. `GET /v1/accounts/{id}`. To fetch one requirement by its `id`: `GET /v1/accounts/{id}/products/payment_gateway/requirements/{requirement_id}`

**3. Upload Each Document**

[Upload](https://razorpay.com/docs/api/partners/accounts/merchant-risk/clarifications.md#upload-a-document) one file per call, with the requirement's `requirement_code` as `document_type`. Keep each returned `id`. `POST /v1/accounts/{id}/documents/{document_type}`

**4. Send Every Response in One Update**

[Answer the requirements](https://razorpay.com/docs/api/partners/accounts/merchant-risk/clarifications.md#answer-requirements): mirror the requirement by `id` and send a `requirement_response` with `text` or `documents` on each `input` requirement. `PATCH /v1/accounts/{id}`. The requirement moves to `under_review`.

**5. Razorpay Reviews**

Razorpay resolves the requirement, with `account.product.payment_gateway.requirement.resolved`, or asks again, with `account.product.payment_gateway.requirement.needs_clarification` and the requirement back in `needs_clarification`. Send the new responses.

## The Requirement

A clarification is one requirement with its sub-requirements:

* **The top requirement:** A `composite` requirement for the review, with the `due_at` deadline. Its `id`, such as `req_UYTBV02QSYTRVK`, is the `requirement_id` that an action points to.
* **Its sub-requirements:** Listed in `sub_requirements`. Each is an `input`: a question (`value_type: text`) or a document request (`value_type: document`) that you answer.

Know more about the [requirement fields](https://razorpay.com/docs/api/partners/accounts/merchant-risk/clarifications.md#requirement-entity).

## Statuses

A requirement has 4 statuses:

| Status | What It Means | What You Do |
| - | - | - |
| `needs_clarification` | Razorpay needs a response. A new requirement starts here, and a requirement comes back here when Razorpay asks again after a review. | Send a `requirement_response` before `due_at`. |
| `overdue` | `due_at` passed with responses still due. Razorpay reviews the account and may act. | Send your responses as soon as you have them. |
| `under_review` | You sent your responses. Razorpay is reviewing them. | Wait. |
| `resolved` | Razorpay has decided. This is the final status. | Nothing. Check the [actions](https://razorpay.com/docs/partners/aggregators/merchant-risk/actions.md) on the product for the outcome. |

The diagram below shows who moves a requirement between statuses:

```mermaid theme={null}
stateDiagram-v2
  direction LR
  [*] --> needs_clarification : Razorpay raises
  needs_clarification --> under_review : you submit
  needs_clarification --> overdue : due_at passes
  overdue --> under_review : you submit
  under_review --> needs_clarification : Razorpay asks again
  under_review --> resolved : Razorpay decides
  needs_clarification --> resolved : Razorpay closes (exceptional)
  overdue --> resolved : Razorpay closes (exceptional)
  resolved --> [*]
```

The table below lists each move and its webhook. Each move fires the event named after the status it moves to:

| From | To | Who | Webhook |
| - | - | - | - |
| None | `needs_clarification` | Razorpay raises the requirement | `account.product.payment_gateway.requirement.needs_clarification` |
| `needs_clarification` | `under_review` | You submit your responses | `account.product.payment_gateway.requirement.under_review` |
| `needs_clarification` | `overdue` | `due_at` passes with responses still due | `account.product.payment_gateway.requirement.overdue` |
| `overdue` | `under_review` | You submit your responses | `account.product.payment_gateway.requirement.under_review` |
| `under_review` | `needs_clarification` | Razorpay asks again | `account.product.payment_gateway.requirement.needs_clarification` |
| `under_review` | `resolved` | Razorpay decides | `account.product.payment_gateway.requirement.resolved` |
| `needs_clarification` or `overdue` | `resolved` | Razorpay, in exceptional cases only, without your responses | `account.product.payment_gateway.requirement.resolved` |

Your only move is to submit. Every other move is Razorpay's. A resolved requirement no longer appears in `requirements` when you fetch the account.

## Deadline

If `due_at` passes while responses are still due, the requirement moves to `overdue` and Razorpay sends `account.product.payment_gateway.requirement.overdue`. Razorpay reviews the account and may disable payments, put settlement on hold or suspend the product, each with its own event. You can still respond: your submit moves the requirement to `under_review`.

## Next Steps

* [Clarifications API](https://razorpay.com/docs/api/partners/accounts/merchant-risk/clarifications.md): fetch the requirements, upload documents and answer.
* [Clarifications webhooks](https://razorpay.com/docs/partners/aggregators/merchant-risk/clarifications-webhooks.md): the 4 requirement events.
* [Actions](https://razorpay.com/docs/partners/aggregators/merchant-risk/actions.md): how an action points to a requirement.
