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

# Fetch and Answer Risk Clarifications

> Read Razorpay's risk requirements on the payment_gateway product with the GET account API, upload documents and send your responses with the PATCH account API.

Available in🇮🇳 India

Answering a clarification takes 3 calls on the Accounts API. Know more about [the clarifications journey and statuses](https://razorpay.com/docs/partners/aggregators/merchant-risk/clarifications.md).

| Step | Call | Endpoint |
| - | - | - |
| 1 | [Fetch the requirements](#fetch-the-requirements) | `GET /v1/accounts/{id}` |
| 1 | Or [fetch a requirement](#fetch-a-requirement) by its `id` | `GET /v1/accounts/{id}/products/payment_gateway/requirements/{requirement_id}` |
| 2 | [Upload a document](#upload-a-document), once per file | `POST /v1/accounts/{id}/documents/{document_type}` |
| 3 | [Answer requirements](#answer-requirements), all in one call | `PATCH /v1/accounts/{id}` |

## Fetch the Requirements

`GET /v1/accounts/{id}` returns the account. The requirements sit at `products.payment_gateway.requirements`. This is the same call as [Fetch an Account](https://razorpay.com/docs/api/partners/accounts/merchant-risk/risk-profile.md). It needs the `onboarding_accounts_read` scope.

```bash Request theme={null}
curl -X GET https://api.razorpay.com/v1/accounts/acc_Rk9Xm2Qp7Zt4Nb \
-u rzp_test_partner_[CLIENT_ID]:[CLIENT_SECRET]
```

The response below shows settlement on hold by Razorpay, pointing to the requirement to answer:

```json Response theme={null}
{
  "id": "acc_Rk9Xm2Qp7Zt4Nb",
  "entity": "account",
  "risk_profile": {
    "rating": {
      "band": "medium",
      "updated_at": 1786000000
    }
  },
  "products": {
    "payment_gateway": {
      "status": "activated",
      "payment_acceptance": {
        "status": "enabled",
        "status_reason": null,
        "initiated_by": null,
        "updated_at": 1786000000
      },
      "settlement": {
        "status": "on_hold",
        "status_reason": {
          "code": "prohibited_business",
          "description": "Razorpay can't support this business model.",
          "requirement_id": "req_UYTBV02QSYTRVK"
        },
        "initiated_by": "razorpay",
        "updated_at": 1794481600
      },
      "requirements": [
        {
          "id": "req_UYTBV02QSYTRVK",
          "requirement_code": "ri_bmc_additional_details",
          "requirement_level": "mandatory",
          "requirement_type": "composite",
          "description": "Resolve the observations raised during review.",
          "fulfillment_criteria": "all_of",
          "sub_requirements": [
            {
              "id": "req_BMC1clarify01",
              "requirement_code": "business_model_clarification",
              "requirement_level": "mandatory",
              "requirement_type": "input",
              "description": "Explain your Business Model in Detail for better understanding.",
              "field_path": "products.payment_gateway.requirements.requirement_response",
              "value_type": "text",
              "response": null,
              "status": "needs_clarification"
            },
            {
              "id": "req_PODdoc00021",
              "requirement_code": "proof_of_delivery",
              "requirement_level": "mandatory",
              "requirement_type": "input",
              "description": "Proof of Delivery",
              "field_path": "products.payment_gateway.requirements.requirement_response",
              "value_type": "document",
              "response": null,
              "status": "needs_clarification"
            },
            {
              "id": "req_F12Adoc0022",
              "requirement_code": "form_12a",
              "requirement_level": "mandatory",
              "requirement_type": "input",
              "description": "Form 12A",
              "field_path": "products.payment_gateway.requirements.requirement_response",
              "value_type": "document",
              "response": null,
              "status": "needs_clarification"
            },
            {
              "id": "req_ANYelse00004",
              "requirement_code": "additional_information",
              "requirement_level": "optional",
              "requirement_type": "input",
              "description": "Anything else you would like to add",
              "field_path": "products.payment_gateway.requirements.requirement_response",
              "value_type": "text",
              "response": null,
              "status": "needs_clarification"
            }
          ],
          "status": "needs_clarification",
          "due_at": 1795305600
        }
      ]
    }
  }
}
```

### Requirement Entity

Every requirement and sub-requirement has these parameters. A requirement carries only the keys its `requirement_type` uses.

**id** `string`

Unique identifier of this requirement, `req_`-prefixed. For example, `req_UYTBV02QSYTRVK`. Send it with the response.

**requirement\_code** `string`

A stable code for the requirement, from a closed list, such as `ri_bmc_additional_details`, `business_model_clarification`, `proof_of_delivery` or `form_12a`. For a `document` requirement, it is also the `document_type` to upload under. Razorpay can add codes.

**requirement\_level** `string`

Possible values:

* `mandatory`: Needed.
* `conditional`: Needed only in the case its `description` states, or as one of the choices under a `one_of`.
* `optional`: Not needed.

**requirement\_type** `string`

Possible values:

* `input`: Send a response at `field_path`, as its `value_type` says.
* `action`: Run the action named in `requirement_code`.
* `composite`: Answer its `sub_requirements` as its `fulfillment_criteria` says.

**description** `string`

What Razorpay asks, as text to show the sub-merchant. Do not branch on it.

**field\_path** `string`

An `input` only. Where the response goes in an update: `products.payment_gateway.requirements.requirement_response`, sent under the requirement's `id`.

**value\_type** `string`

An `input` only. Possible values:

* `text`: Send `requirement_response.text`.
* `enum`: Send one of `options` as `requirement_response.text`.
* `multi_select`: Send any of `options`.
* `boolean`: Send `true` or `false` as `requirement_response.text`.
* `document`: Send `requirement_response.documents`, each a document ID from [Upload a Document](#upload-a-document).

**response** `object`

An `input` only. The response on record, or `null` until you send one.

**properties**

**text** `string`

The text response. Present when `value_type` is `text`, `enum`, `multi_select` or `boolean`.

**documents** `array`

The documents sent, each `{ "id": "doc_..." }`. Present when `value_type` is `document`.

**created\_at** `integer`

Unix timestamp at which the response was first sent.

**updated\_at** `integer`

Unix timestamp at which the response last changed, such as after a new response when Razorpay asked again.

**metadata** `object`

Extra details for the response, when it has any.

**options** `array`

An `enum` or `multi_select` input only. The choices, each a `label` and a `value`.

**fulfillment\_criteria** `string`

A `composite` only. How its `sub_requirements` combine. Possible values:

* `all_of`: Answer every one.
* `any_of`: Answer at least one.
* `one_of`: Answer exactly one.

**sub\_requirements** `array`

A `composite` only. Its sub-requirements, each a requirement with these same keys.

**status** `string`

The requirement's status. Possible values:

* `needs_clarification`: Razorpay needs a response. A new requirement starts here, and comes back here when Razorpay asks again.
* `overdue`: `due_at` passed with responses still due. You can still respond.
* `under_review`: You sent your responses. Razorpay is reviewing them.
* `resolved`: Razorpay has decided.

Know more about [statuses](https://razorpay.com/docs/partners/aggregators/merchant-risk/clarifications.md#statuses).

**due\_at** `integer`

Unix timestamp by which Razorpay needs the responses. `null` when there is no deadline. Once it passes with responses still due, the requirement moves to `overdue`, with `account.product.payment_gateway.requirement.overdue`.

**metadata** `object`

Extra details for a requirement, when it has any.

## Fetch a Requirement

`GET /v1/accounts/{id}/products/payment_gateway/requirements/{requirement_id}` returns one requirement with its `sub_requirements`. It needs the `onboarding_accounts_read` scope.

```bash Request theme={null}
curl -X GET https://api.razorpay.com/v1/accounts/acc_Rk9Xm2Qp7Zt4Nb/products/payment_gateway/requirements/req_UYTBV02QSYTRVK \
-u rzp_test_partner_[CLIENT_ID]:[CLIENT_SECRET]
```

```json Response theme={null}
{
  "id": "req_UYTBV02QSYTRVK",
  "requirement_code": "ri_bmc_additional_details",
  "requirement_level": "mandatory",
  "requirement_type": "composite",
  "description": "Resolve the observations raised during review.",
  "fulfillment_criteria": "all_of",
  "sub_requirements": [
    {
      "id": "req_BMC1clarify01",
      "requirement_code": "business_model_clarification",
      "requirement_level": "mandatory",
      "requirement_type": "input",
      "description": "Explain your Business Model in Detail for better understanding.",
      "field_path": "products.payment_gateway.requirements.requirement_response",
      "value_type": "text",
      "response": null,
      "status": "needs_clarification"
    },
    {
      "id": "req_PODdoc00021",
      "requirement_code": "proof_of_delivery",
      "requirement_level": "mandatory",
      "requirement_type": "input",
      "description": "Proof of Delivery",
      "field_path": "products.payment_gateway.requirements.requirement_response",
      "value_type": "document",
      "response": null,
      "status": "needs_clarification"
    },
    {
      "id": "req_F12Adoc0022",
      "requirement_code": "form_12a",
      "requirement_level": "mandatory",
      "requirement_type": "input",
      "description": "Form 12A",
      "field_path": "products.payment_gateway.requirements.requirement_response",
      "value_type": "document",
      "response": null,
      "status": "needs_clarification"
    },
    {
      "id": "req_ANYelse00004",
      "requirement_code": "additional_information",
      "requirement_level": "optional",
      "requirement_type": "input",
      "description": "Anything else you would like to add",
      "field_path": "products.payment_gateway.requirements.requirement_response",
      "value_type": "text",
      "response": null,
      "status": "needs_clarification"
    }
  ],
  "status": "needs_clarification",
  "due_at": 1795305600
}
```

```json Failure theme={null}
{
  "error": {
    "code": "BAD_REQUEST_ERROR",
    "description": "The requirement doesn't exist on this account.",
    "source": "business",
    "step": "validation",
    "reason": "requirement_not_found",
    "field": "requirement_id",
    "metadata": {}
  }
}
```

### Fetch Parameters

**id** `string` *required*

The unique identifier of the account, `acc_` followed by 14 letters or digits. For example, `acc_Rk9Xm2Qp7Zt4Nb`.

**requirement\_id** `string` *required*

The `id` of the requirement, `req_`-prefixed. For example, `req_UYTBV02QSYTRVK`.

### Fetch Errors

> [accordion] The requirement doesn't exist on this account.
>
> **Code:** `404`
>
> **Reason:** `requirement_not_found`
>
> No requirement with this `requirement_id` is on the account's `payment_gateway` product.
>
> **Solution:** Check the ID in `error.field`. Use the `id` of a requirement on this account.

## Upload a Document

`POST /v1/accounts/{id}/documents/{document_type}` stores one file for a `document` requirement and returns its document ID.

* Send the request as `multipart/form-data`, with a PDF, JPEG or PNG file of up to 20 MB.
* Use the requirement's `requirement_code` as `document_type`, such as `proof_of_delivery` or `form_12a`, in the path and in the body.
* The upload alone answers nothing. Send the ID in `requirement_response.documents` with [Answer Requirements](#answer-requirements).
* Upload one file per call. For a requirement that takes several files, upload each and send all the IDs together.
* Razorpay keeps its own copy. Delete your copy once the upload succeeds, as your agreement with Razorpay requires.
* A retry with the same `X-Idempotency-Key` must send the same `document_type` and file.
* This endpoint needs the `onboarding_documents_write` scope.

```bash Request theme={null}
curl -X POST https://api.razorpay.com/v1/accounts/acc_Rk9Xm2Qp7Zt4Nb/documents/proof_of_delivery \
-u rzp_test_partner_[CLIENT_ID]:[CLIENT_SECRET] \
-H "X-Idempotency-Key: [UNIQUE_KEY]" \
-F "file=@proof_of_delivery.pdf" \
-F "document_type=proof_of_delivery"
```

The responses below are for the 2 document sub-requirements of the sample requirement: `proof_of_delivery` and `form_12a`.

```json proof_of_delivery theme={null}
{
  "id": "doc_PdL9mA2Qv7",
  "type": "proof_of_delivery",
  "status": "uploaded",
  "created_at": 1795300000
}
```

```json form_12a theme={null}
{
  "id": "doc_F12aRt4Pn8",
  "type": "form_12a",
  "status": "uploaded",
  "created_at": 1795300060
}
```

### Upload Parameters

**id** `string` *required*

The unique identifier of the account, `acc_` followed by 14 letters or digits. For example, `acc_Rk9Xm2Qp7Zt4Nb`.

**document\_type** `string` *required*

The document type: the requirement's `requirement_code`, such as `proof_of_delivery` or `form_12a`. The KYC document types of the Accounts API also work.

**X-Idempotency-Key** `string` *required*

A unique key you generate for each write, 16-64 printable ASCII characters long. A retry with the same key within 24 h returns the original response instead of acting twice.

**file** `file` *required*

The file: a PDF, JPEG or PNG of up to 20 MB. Razorpay reads the format from the bytes, not from the file name.

**document\_type** `string` *required*

The same document type as in the path.

### Upload Response

**id** `string`

Unique identifier for the document, `doc_`-prefixed. Send it in `requirement_response.documents`.

**type** `string`

The document type you sent.

**status** `string`

Always `uploaded`. Razorpay reviews the document once you send it in a `requirement_response`.

**created\_at** `integer`

Unix timestamp at which the document was uploaded.

### Upload Errors

> [accordion] The request is missing a required field.
>
> **Code:** `400`
>
> **Reason:** `invalid_request`
>
> The request has one of these problems:
>
> * The body is not `multipart/form-data`.
> * `file` or `document_type` is missing.
> * The request has more than 1 file.
> * `document_type` in the body is not the one in the path.
>
> **Solution:** Send a `multipart/form-data` body with 1 `file` and the same `document_type` as the path.

> [accordion] Choose one of the allowed values (document type).
>
> **Code:** `400`
>
> **Reason:** `invalid_option`
>
> `document_type` is not a document type.
>
> **Solution:** Send the requirement's `requirement_code`, or another valid document type.

> [accordion] The file can't be read. Upload it again.
>
> **Code:** `400`
>
> **Reason:** `invalid_file`
>
> Razorpay cannot read the file. For example, the PDF is truncated or corrupt.
>
> **Solution:** Check that the file is complete and readable, then upload it again.

> [accordion] Upload the file without a password.
>
> **Code:** `400`
>
> **Reason:** `password_protected_file`
>
> The file is password protected.
>
> **Solution:** Remove the password from the file, then upload it again.

> [accordion] The file is too large.
>
> **Code:** `413`
>
> **Reason:** `file_too_large`
>
> The file is larger than 20 MB.
>
> **Solution:** Compress or split the file to 20 MB or less, then upload it again.

> [accordion] Upload a PDF, JPEG or PNG file.
>
> **Code:** `415`
>
> **Reason:** `unsupported_media_type`
>
> The file is not a PDF, JPEG or PNG. `metadata.detected_type` names the type Razorpay found.
>
> **Solution:** Convert the file to PDF, JPEG or PNG, then upload it again.

The upload also returns the [write errors](#write-errors) and the [common errors](#common-errors).

## Answer Requirements

`PATCH /v1/accounts/{id}` with `products.payment_gateway.requirements` in the body sends your responses. Send a `requirement_response` for every requirement of the clarification in one call, so Razorpay reviews them together.

* This is the same call as Update an Account in the Accounts API.
* Mirror the requirement you fetched: the top requirement's `id`, then each of its `sub_requirements` by `id`.
* Send `requirement_response.text` for a `value_type` of `text`, or `requirement_response.documents` for `document`.
* The response is the account. Each requirement you answered carries its `response`, and the requirement moves to `under_review`. The product's `status`, `payment_acceptance` and `settlement` do not change.
* This endpoint needs the `onboarding_accounts_write` scope.

```bash Request theme={null}
curl -X PATCH https://api.razorpay.com/v1/accounts/acc_Rk9Xm2Qp7Zt4Nb \
-u rzp_test_partner_[CLIENT_ID]:[CLIENT_SECRET] \
-H "Content-Type: application/json" \
-H "X-Idempotency-Key: [UNIQUE_KEY]" \
-d '{
  "products": {
    "payment_gateway": {
      "requirements": [
        {
          "id": "req_UYTBV02QSYTRVK",
          "sub_requirements": [
            {
              "id": "req_BMC1clarify01",
              "requirement_response": {
                "text": "We sell healthy packaged meals online and at our studio cafe."
              }
            },
            {
              "id": "req_PODdoc00021",
              "requirement_response": {
                "documents": [
                  {
                    "id": "doc_PdL9mA2Qv7"
                  }
                ]
              }
            },
            {
              "id": "req_F12Adoc0022",
              "requirement_response": {
                "documents": [
                  {
                    "id": "doc_F12aRt4Pn8"
                  }
                ]
              }
            }
          ]
        }
      ]
    }
  }
}'
```

```json Response theme={null}
{
  "id": "acc_Rk9Xm2Qp7Zt4Nb",
  "entity": "account",
  "risk_profile": {
    "rating": {
      "band": "medium",
      "updated_at": 1786000000
    }
  },
  "products": {
    "payment_gateway": {
      "status": "activated",
      "payment_acceptance": {
        "status": "enabled",
        "status_reason": null,
        "initiated_by": null,
        "updated_at": 1786000000
      },
      "settlement": {
        "status": "on_hold",
        "status_reason": {
          "code": "prohibited_business",
          "description": "Razorpay can't support this business model.",
          "requirement_id": "req_UYTBV02QSYTRVK"
        },
        "initiated_by": "razorpay",
        "updated_at": 1794481600
      },
      "requirements": [
        {
          "id": "req_UYTBV02QSYTRVK",
          "requirement_code": "ri_bmc_additional_details",
          "requirement_level": "mandatory",
          "requirement_type": "composite",
          "description": "Resolve the observations raised during review.",
          "fulfillment_criteria": "all_of",
          "sub_requirements": [
            {
              "id": "req_BMC1clarify01",
              "requirement_code": "business_model_clarification",
              "requirement_level": "mandatory",
              "requirement_type": "input",
              "description": "Explain your Business Model in Detail for better understanding.",
              "field_path": "products.payment_gateway.requirements.requirement_response",
              "value_type": "text",
              "response": {
                "text": "We sell healthy packaged meals online and at our studio cafe.",
                "created_at": 1795305120,
                "updated_at": 1795305120,
                "metadata": {}
              },
              "status": "under_review"
            },
            {
              "id": "req_PODdoc00021",
              "requirement_code": "proof_of_delivery",
              "requirement_level": "mandatory",
              "requirement_type": "input",
              "description": "Proof of Delivery",
              "field_path": "products.payment_gateway.requirements.requirement_response",
              "value_type": "document",
              "response": {
                "documents": [
                  {
                    "id": "doc_PdL9mA2Qv7"
                  }
                ],
                "created_at": 1795305120,
                "updated_at": 1795305120,
                "metadata": {}
              },
              "status": "under_review"
            },
            {
              "id": "req_F12Adoc0022",
              "requirement_code": "form_12a",
              "requirement_level": "mandatory",
              "requirement_type": "input",
              "description": "Form 12A",
              "field_path": "products.payment_gateway.requirements.requirement_response",
              "value_type": "document",
              "response": {
                "documents": [
                  {
                    "id": "doc_F12aRt4Pn8"
                  }
                ],
                "created_at": 1795305120,
                "updated_at": 1795305120,
                "metadata": {}
              },
              "status": "under_review"
            },
            {
              "id": "req_ANYelse00004",
              "requirement_code": "additional_information",
              "requirement_level": "optional",
              "requirement_type": "input",
              "description": "Anything else you would like to add",
              "field_path": "products.payment_gateway.requirements.requirement_response",
              "value_type": "text",
              "response": null,
              "status": "under_review"
            }
          ],
          "status": "under_review",
          "due_at": 1795305600
        }
      ]
    }
  }
}
```

```json Failure theme={null}
{
  "error": {
    "code": "BAD_REQUEST_ERROR",
    "description": "The requested resource doesn't exist.",
    "source": "business",
    "step": "validation",
    "reason": "not_found",
    "field": "products.payment_gateway.requirements[0].sub_requirements[1].requirement_response.documents[0].id",
    "metadata": {}
  }
}
```

### Answer Parameters

**id** `string` *required*

The unique identifier of the account, `acc_` followed by 14 letters or digits. For example, `acc_Rk9Xm2Qp7Zt4Nb`.

**X-Idempotency-Key** `string` *required*

A unique key you generate for each write, 16-64 printable ASCII characters long. A retry with the same key within 24 h returns the original response instead of acting twice.

**products.payment\_gateway.requirements** `array` *required*

The requirements you answer, mirroring the requirement on the account.

**properties**

**id** `string` *required*

The `id` of a requirement, `req_`-prefixed. For example, `req_UYTBV02QSYTRVK`.

**sub\_requirements** `array`

For a `composite` requirement: its sub-requirements you answer, each with its `id` and `requirement_response`.

**requirement\_response** `object`

For an `input` requirement: the response.

**properties**

**text** `string`

The text response, for a `value_type` of `text`, `enum` or `boolean`.

**documents** `array`

The documents, for a `value_type` of `document`. Each entry is `{ "id": "doc_..." }`, a document uploaded to this account.

### Answer Response

The response is the account, as [Fetch the Requirements](#fetch-the-requirements) returns it. Each answered requirement carries its `response` and the status `under_review`.

## Write Errors

The upload and the PATCH also return these errors. `GET` does not.

| Code | Reason | Description |
| - | - | - |
| `400` | `missing_header` | A required header is missing. |
| `409` | `idempotency_key_mismatch` | This request conflicts with an earlier one. |
| `409` | `idempotency_in_progress` | The earlier request is still being processed. |

## Common Errors

The table below lists the errors all 3 calls return. Know more about [each error](https://razorpay.com/docs/api/partners/accounts/merchant-risk/errors.md).

| Code | Reason | Description |
| - | - | - |
| `401` | `invalid_credentials` | The credentials aren't valid. |
| `403` | `onboarding_not_enabled` | Onboarding isn't enabled for this platform. |
| `403` | `ip_not_allowed` | Requests from this address aren't allowed. |
| `403` | `insufficient_scope` | These credentials can't perform this operation. |
| `403` | `consent_withdrawn` | The business has withdrawn this platform's access to its Razorpay account. |
| `404` | `not_found` | The requested resource doesn't exist. |
| `429` | `rate_limited` | Too many requests. Try again shortly. |
| `500` | `internal_error` | Something went wrong on our side. Try again. |
