Skip to main content
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}.

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:
Response
Know more about the requirement object.

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.
Curl
Response
An upload answers nothing by itself. Keep the id and send it in the next step. This is the Upload a Document endpoint of the Onboarding APIs v3, with the same request, response and errors.
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.

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).
Curl
Response
The response is 201 Created when every answer was accepted. Send text or document_id, as the requirement’s value_type says. Never send both.
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.

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. 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. 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
Last modified on November 20, 2026