Skip to main content
Available in🇮🇳 India
Each product’s requirements list what is still due, in any status and in journey order. A requirement disappears once it is satisfied, and its data then lives on the account. The list is empty when nothing is due. Build your forms from this list, not from hard-coded rules.

2.1 Read a Requirement

The table below lists the attributes of a requirement: Every sub-requirement of a one_of is conditional, needed only if it is the option chosen. Some requirements depend on the business, such as a Goods and Services Tax Identification Number (GSTIN). These are conditional, with the condition in the description. A document input takes a pre-signed { "url" } or an uploaded document’s { "id" }. Know more about uploading documents.

2.1.1 Requirement Metadata

metadata is an optional, free-form object of key-value pairs for extensibility on any requirement. It carries more context or configuration, such as what an action needs on an action requirement, without changing the requirement schema.

2.1.2 Requirement Keys

A requirement carries only the keys its requirement_type uses:
  • Every requirement: id, requirement_code, requirement_level, requirement_type, description and status. It adds requirement_reason when a review or a check raised it, and due_at when it has a deadline.
  • An input: Adds field_path and value_type. It also carries response once answered, options for an enum or multi_select and metadata when it has any.
  • A composite: Adds fulfillment_criteria and sub_requirements, with metadata when it has any.
  • An action: Adds metadata when it has any.
Every other object the API returns has every declared property present, with null when it does not apply. Maps list only the entries that exist. Why a value failed sits on the element itself, in its verification.error_code, with the requirement due again. See Failed-Check Codes. Refer to the Requirement Entity for every attribute.

2.2 Composite Requirements

A point answered in more than one way, or with several values, is one requirement of requirement_type composite. Its sub_requirements answer it, as its fulfillment_criteria says:
  • one_of: Answer any one sub-requirement. Each is conditional, so offer them as one choice. Sending one clears the composite.
  • any_of: Answer one or more sub-requirements.
  • all_of: Answer every sub-requirement. Each is mandatory, or optional when it can be left out, such as an address’s address_line2.
The composite’s requirement_code names the point. A sub-requirement can itself be a composite. The person a requirement is about is in its inputs’ field_path.
Razorpay fetches the Central KYC Records Registry (CKYC) record with a code, or the sub-merchant skips it:
ckyc_fetch
The table below lists the composite requirements: Some composites apply only in certain cases:
  • business_identity: For a private limited, public limited or Section 8 company. The Corporate Identification Number (CIN) or the certificate of incorporation answers it.
  • proof_of_business: For a proprietorship.
  • bank_account: Listed only after a failed check or in needs_clarification. Otherwise, it is listed as settlement_bank_account. Its clarify_bank_account option appears only in needs_clarification.
  • website: Listed only in needs_clarification. Otherwise, it is listed as website_url.
  • payment_channels: Optional. Any one channel answers it.
  • accept_terms_of_service: Sending it submits the product.
  • business_model_clarifications: One input per question, coded by the question’s ID, with the question’s options. Its value_type follows the question’s bmc_input_type: single_select becomes enum, multi_select stays multi_select and free_text becomes text. Know more about the business model questions for each subcategory.

2.2.1 Input Paths

The Requirement Entity lists each input’s value_type and field_path. Input paths follow the account:
  • A person: Under business_profile.authorized_person, or business_profile.stakeholders.<stakeholder_id> for a stakeholder.
  • A business identifier or document: Under business_profile.identity_numbers or business_profile.documents.
  • An address: Its parts in the business_profile.addresses item of that type, such as business_profile.addresses[type=registered_address].line1.
  • The bank account: Under bank_accounts.settlements_primary.
  • A reply: Under products.<product_type>.clarification_responses, such as products.payment_gateway.clarification_responses.

2.2.2 How Composites Collapse

A document with 2 sides is an all_of pair. Both sides are due together, and a request can send them at once or one at a time. A satisfied requirement drops out, and a composite drops out once it is satisfied. A composite left with one sub-requirement is returned as that sub-requirement, at the composite’s requirement_level:
  • Before any bank check has failed, bank_account comes back as settlement_bank_account.
  • Outside needs_clarification, website comes back as website_url.
The exception is ckyc_fetch, which always comes back whole. Send the bank account’s 3 inputs together in one update, under bank_accounts.settlements_primary. A GSTIN asked for on its own, for a business type other than a proprietorship, is conditional. The condition is in its description, for example: Your GSTIN. Needed if your turnover is over ₹40 lakh or you sell across states.

2.3 Failed-Check Codes

A failed check is a 200, not an error. The element’s verification.status is rejected, with the code in verification.error_code. Its requirement comes back due, with a requirement_reason. Branch on the code and show verification.error_description to the sub-merchant. Some checks behave differently:
  • Link codes: link_expired, video_kyc_failed, digilocker_failed and upi_payment_failed have no element to carry them. The action comes back due, without a link.
  • Phone or email One-Time Password (OTP): Carries no error code. A wrong code leaves the code due. An expired code, or 3 wrong tries, brings the send action back.
The tables below list every code a failed check can carry, grouped by check:

2.4 Review Reasons

In needs_clarification, a reviewer’s flag comes back on the flagged point’s requirements, with the reviewer’s reason in requirement_reason. Know more about handling clarifications. The table below lists the reasons a reviewer can give:

2.5 Build Your Forms

Arrange requirements into steps the sub-merchant recognises, such as business details, identity, bank account and website. Render each one by its requirement_type, with a label and help text from description. Mark the optional ones.

Input

Show a control that matches its value_type. Use a text box for text. Use a picker for enum, a multi-pick for multi_select, a toggle for boolean and a file picker for document.

Action

Show a button that runs the action. Then show what its response returns: a box for the code it sent, or the link to open.

Composite

Render its sub_requirements the same way, by fulfillment_criteria. Offer one choice between them for one_of, one or more for any_of and every one for all_of.
Handy TipsNew requirements can appear. Render an unknown requirement_code generically from its requirement_type and value_type rather than failing.

Next Step

Submit Information
Last modified on November 18, 2026