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

# 3. Supply Requirements

> Upload documents and answer the requirements Razorpay needs before activating a payment method instrument for a sub-merchant.

Available in
🇮🇳 India

A requirement is something Razorpay still needs about the account before it can activate an instrument. It is the same Requirement object the Onboarding APIs return, filtered to the instrument. A clarification is a requirement too, so there is no separate clarification object to track.

A requirement describes the account. One requirement can appear on several instruments, and answering it once fulfils it for all of them.

Two endpoints supply requirements. Here, `…` stands for `/v3/accounts/{account_id}`.

| Method | Path | Purpose |
| - | - | - |
| `POST` | `…/documents` | Upload one file. Returns its document id. |
| `POST` | `…/requirements` | Answer one instrument's requirements in one call: values, replies and document ids. |

## 3.1 Read the Requirements

Read `requirements` on the instrument, in the fetch response or in the response to enabling it. It lists only what Razorpay still needs. An answered requirement drops out of the list. For a netbanking bank that needs onboarding:

```json Response theme={null}
{
  "instrument": "netbanking/banks/kkbk",
  "name": "Kotak Mahindra Bank",
  "status": "in_progress",
  "enabled": false,
  "requirements": [
    {
      "id": "req_Qd3Kp8Lm2Vx7Tn",
      "code": "gstin",
      "description": "The GSTIN of the business.",
      "reason": "Kotak Mahindra Bank needs it to onboard the account.",
      "level": "mandatory",
      "field_path": "business_profile.identity_numbers.gstin",
      "value_type": "text"
    },
    {
      "id": "req_Rf6Hs1Zb9Yc4Wg",
      "code": "shop_establishment",
      "description": "The shop and establishment certificate of the business.",
      "reason": "Kotak Mahindra Bank needs it to onboard the account.",
      "level": "mandatory",
      "field_path": "business_profile.documents.shop_establishment",
      "value_type": "document",
      "metadata": {
        "constraints": {
          "accept": ["application/pdf", "image/jpeg", "image/png"],
          "max_size_mb": 20
        }
      }
    }
  ]
}
```

| Field | Description |
| - | - |
| `id` | Unique id of the requirement. Send it when you answer. |
| `code` | The requirement's code, such as `gstin`. For an action, the action to run. |
| `description` | A sentence to show the merchant: what is needed. |
| `reason` | Why it was raised, such as a reviewer's comment. `null` when there is none. |
| `level` | `mandatory`, `conditional` or `optional`. A `conditional` requirement is needed only in some cases, such as the option you take in a `one_of`. |
| `value_type` | What an input takes: `text`, `enum`, `multi_select`, `boolean` or `document`. |
| `options` | The label and value pairs to choose from, for `enum` and `multi_select`. |
| `fulfillment_criteria` and `sub_requirements` | On a composite: `one_of` (any one is enough) or `all_of` (every mandatory one). |
| `metadata.constraints` | The rules an answer must meet. For text: `minLength`, `maxLength`, `pattern` and `format`. For a document: `accept` and `max_size_mb`, which is 20. |

Know more about the [requirement object](https://razorpay.com/docs/api/partners/accounts/requirement-entity.md).

## 3.2 Upload a Document

For a requirement with `value_type: document`, upload the file first. Call `POST …/documents` as `multipart/form-data`, with `type` set to the requirement's `code` and one `file` that meets `constraints.accept` and `constraints.max_size_mb`.

```bash Curl theme={null}
curl -X POST https://api.razorpay.com/v3/accounts/acc_HQVlm3bnPmccC0/documents \
-u rzp_live_partner_[CLIENT_ID]:[CLIENT_SECRET] \
-H "X-Idempotency-Key: 6c2a9e14-0f3b-4d7e-a1c5-98b2e4f7d031" \
-F "type=shop_establishment" \
-F "file=@shop_establishment.pdf"
```

```json Response theme={null}
{
  "id": "doc_Sh7Ke2Rt9Lm4Qw",
  "entity": "document",
  "type": "shop_establishment",
  "url": "https://files.razorpay.com/documents/doc_Sh7Ke2Rt9Lm4Qw",
  "metadata": {
    "source": "upload",
    "file_name": "shop_establishment.pdf",
    "mime_type": "application/pdf",
    "size_bytes": 482113
  },
  "verification": null,
  "created_at": "2026-11-14T05:11:40Z",
  "deleted_at": null
}
```

An upload answers nothing by itself. Keep the `id` and send it in the next step.

| Field | In | Required | Description |
| - | - | - | - |
| `account_id` | Path | Yes | The sub-merchant account. |
| `X-Idempotency-Key` | Header | Yes | 16 to 64 printable ASCII characters. A retry must send the same `type` and `file`. |
| `type` | Form | Yes | The document type, such as `shop_establishment` or `gst_certificate`. |
| `file` | Form | Yes | One file: PDF, JPEG or PNG, up to 20 MB. The format is read from the file's bytes, not its name. |

This is the Upload a Document endpoint of the Onboarding APIs v3, with the same request, response and errors.

> [!NOTE]
>
> **Handy Tips**
>
> * Send one file per call. One file answers one requirement.
> * A document id works only on the account it was uploaded to.
> * The response returns `created_at` and `deleted_at` as ISO 8601 strings. Every other timestamp in this API is a Unix timestamp in seconds.
> * Allow a timeout of at least 30 seconds. An upload typically takes 1 to 3 seconds.
> * Retry an upload with the same `X-Idempotency-Key`. With a new key, the file is stored again.

| HTTP code | `reason` | When |
| - | - | - |
| 400 | `invalid_request` | The body is not `multipart/form-data`. `field` is `Content-Type`. |
| 400 | `invalid_request` | `file` is missing, `type` is missing, or there is more than one file. `field` names it. |
| 400 | `invalid_option` | `type` is not a document type. |
| 400 | `invalid_file` | The file is empty or damaged. |
| 400 | `invalid_file_name` | The file name has characters that are not allowed. |
| 400 | `file_name_too_long` | The file name is longer than allowed. |
| 400 | `password_protected_file` | The PDF is protected with a password. |
| 413 | `file_too_large` | The file is over 20 MB. `metadata.max_size_mb` gives the limit. |
| 415 | `unsupported_media_type` | The file is not a PDF, JPEG or PNG. `metadata.detected_type` says what was found. |
| 409 | `idempotency_key_mismatch` | You reused a key within 24 hours with a different `type` or file. |

## 3.3 Answer the Requirements

Call `POST …/requirements` for one instrument and send every answer together. The same call answers what an instrument needs for onboarding (`in_progress`) and what a reviewer or the bank flagged (`needs_clarification`).

```bash Curl theme={null}
curl -X POST https://api.razorpay.com/v3/accounts/acc_HQVlm3bnPmccC0/requirements \
-u rzp_live_partner_[CLIENT_ID]:[CLIENT_SECRET] \
-H "X-Idempotency-Key: 2d4f6a8c-1b3e-4c5d-9e7f-0a1b2c3d4e5f" \
-H "Content-Type: application/json" \
-d '{
  "instrument": "netbanking/banks/kkbk",
  "requirements": [
    {
      "id": "req_Qd3Kp8Lm2Vx7Tn",
      "text": "29ABCDE1234F1Z5"
    },
    {
      "id": "req_Rf6Hs1Zb9Yc4Wg",
      "document_id": "doc_Sh7Ke2Rt9Lm4Qw"
    }
  ]
}'
```

```json Response theme={null}
{
  "status": "success",
  "instrument": "netbanking/banks/kkbk"
}
```

The response is `201 Created` when every answer was accepted.

| Field | In | Required | Description |
| - | - | - | - |
| `account_id` | Path | Yes | The sub-merchant account. |
| `X-Idempotency-Key` | Header | Yes | 16 to 64 printable ASCII characters, unique per intended change. |
| `instrument` | Body | Yes | The instrument the answers are for, such as `netbanking/banks/kkbk`. Every requirement in the call must be one of its requirements. |
| `requirements` | Body | Yes | 1 to 20 answers, one per requirement, in any order. |
| `requirements[].id` | Body | Yes | The id of an input requirement. For a composite, the id of the sub-requirement you chose. Each id at most once per call. |
| `requirements[].text` | Body | For `text`, `enum` | The value or the reply. It meets the requirement's `metadata.constraints` and, for an `enum`, is one of its `options`. |
| `requirements[].document_id` | Body | For `document` | The id from the upload, such as `doc_Sh7Ke2Rt9Lm4Qw`. |

Send `text` or `document_id`, as the requirement's `value_type` says. Never send both.

> [!WARNING]
>
> **Watch Out!**
>
> * The call is all or nothing. Razorpay checks every answer first. If any fails, none is saved, and the error lists every answer to fix. Fix them and send the same call again.
> * Send one instrument per call. An id that belongs to another instrument returns `requirement_not_for_instrument`.
> * Do not send files here. Upload each file first, then send its id.
> * A composite cannot be answered directly. Answer one of its `sub_requirements`. An `action` requirement is run with `POST /v3/accounts/{account_id}/actions/{action}` of the Onboarding APIs v3, not with this call.
> * Check text against `metadata.constraints` before you send it. A value that breaks them returns `400 invalid_format` and nothing in the call is submitted.
> * Allow a timeout of at least 5 seconds. The call typically takes under 1 second.

When an answer is refused, `error.field` names it by its place in the list, counted from 0, such as `requirements[2].text` for the third answer. When several fail, `field` and `reason` name the first and `metadata.errors` lists all of them, each with `field`, `reason` and `description`.

| HTTP code | `reason` | When |
| - | - | - |
| 400 | `invalid_request` | `instrument` is missing or null, `requirements` is missing, empty or has more than 20 items, an id appears more than once, two options of the same `one_of` choice are answered, or neither or both of `text` and `document_id` are sent. `field` names it. |
| 404 | `not_found` | `instrument` is not an instrument id of the account, or no requirement has this id. |
| 400 | `requirement_not_for_instrument` | An id belongs to another instrument. |
| 400 | `wrong_value_type` | `text` was sent for a document requirement, or `document_id` for a text one. |
| 400 | `invalid_format` | The text breaks `metadata.constraints`, or is not one of the `options`. |
| 400 | `invalid_document` | The document does not exist, belongs to another account, or is a file type the requirement does not accept. |
| 400 | `requirement_not_answerable` | The id is a composite or an action. |
| 400 | `requirement_closed` | The requirement was already answered, or is no longer needed. |
| 409 | `idempotency_key_mismatch` | You reused a key within 24 hours with a different request. |

## 3.4 Confirm the Answer

Razorpay has the answers once you get `status: success`. There is nothing to resubmit or restart. Once nothing is due, Razorpay continues the onboarding on its own. The instrument then moves to `under_review`, and later to `activated`, `rejected` or `needs_clarification`. Know more about [subscribing to webhooks](https://razorpay.com/docs/partners/aggregators/onboarding-api/payment-methods/follow-onboarding.md).

An answered requirement drops out of the instrument's `requirements`. If a later check rejects an answer, you receive `account.payment_methods.requirements.updated` and the requirement is back in the list, with `reason` saying why. Answer it again with the same call.

## 3.5 Answer a Clarification

When Razorpay or a bank asks for more, the instrument's status is `needs_clarification`. `requirements` lists the flagged points, with the reviewer's comment in `reason`. The `account.payment_methods.updated` event carries the same points, so you can show them to the merchant without fetching.

| What the requirement shows | What to do |
| - | - |
| `value_type: document` | Upload the file, then answer with `document_id`. |
| `value_type: text` | Answer with `text`. |
| A composite with `fulfillment_criteria: one_of` | The merchant chooses one way. Answer one of its `sub_requirements`. |
| Several requirements | Answer them all in one call. The status moves on when the last is answered. |

You cannot answer by webhook. The reply to an event is only your `2xx` acknowledgement. Events never carry an answer or a file.

## Next Step

[Subscribe to Webhooks](https://razorpay.com/docs/partners/aggregators/onboarding-api/payment-methods/follow-onboarding.md)
