Skip to main content
Available in🇮🇳 India
Answering a clarification takes 3 calls on the Accounts API. Know more about the clarifications journey and statuses.

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. It needs the onboarding_accounts_read scope.
The response below shows settlement on hold by Razorpay, pointing to the requirement to answer:

Requirement Entity

Every requirement and sub-requirement has these parameters. A requirement carries only the keys its requirement_type uses.
string
Unique identifier of this requirement, req_-prefixed. For example, req_UYTBV02QSYTRVK. Send it with the response.
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.
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.
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.
string
What Razorpay asks, as text to show the sub-merchant. Do not branch on it.
string
An input only. Where the response goes in an update: products.payment_gateway.requirements.requirement_response, sent under the requirement’s id.
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.
object
An input only. The response on record, or null until you send one.
array
An enum or multi_select input only. The choices, each a label and a value.
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.
array
A composite only. Its sub-requirements, each a requirement with these same keys.
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.
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.
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.

Fetch Parameters

string
required
The unique identifier of the account, acc_ followed by 14 letters or digits. For example, acc_Rk9Xm2Qp7Zt4Nb.
string
required
The id of the requirement, req_-prefixed. For example, req_UYTBV02QSYTRVK.

Fetch Errors

Code: 404Reason: requirement_not_foundNo 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.
  • 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.
The responses below are for the 2 document sub-requirements of the sample requirement: proof_of_delivery and form_12a.

Upload Parameters

string
required
The unique identifier of the account, acc_ followed by 14 letters or digits. For example, acc_Rk9Xm2Qp7Zt4Nb.
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.
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
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.
string
required
The same document type as in the path.

Upload Response

string
Unique identifier for the document, doc_-prefixed. Send it in requirement_response.documents.
string
The document type you sent.
string
Always uploaded. Razorpay reviews the document once you send it in a requirement_response.
integer
Unix timestamp at which the document was uploaded.

Upload Errors

Code: 400Reason: invalid_requestThe 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.
Code: 400Reason: invalid_optiondocument_type is not a document type.Solution: Send the requirement’s requirement_code, or another valid document type.
Code: 400Reason: invalid_fileRazorpay 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.
Code: 400Reason: password_protected_fileThe file is password protected.Solution: Remove the password from the file, then upload it again.
Code: 413Reason: file_too_largeThe file is larger than 20 MB.Solution: Compress or split the file to 20 MB or less, then upload it again.
Code: 415Reason: unsupported_media_typeThe 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 and the 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.

Answer Parameters

string
required
The unique identifier of the account, acc_ followed by 14 letters or digits. For example, acc_Rk9Xm2Qp7Zt4Nb.
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.
array
required
The requirements you answer, mirroring the requirement on the account.

Answer Response

The response is the account, as 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.

Common Errors

The table below lists the errors all 3 calls return. Know more about each error.
Last modified on November 20, 2026