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 itsrequirement_type uses:
- Every requirement:
id,requirement_code,requirement_level,requirement_type,descriptionandstatus. It addsrequirement_reasonwhen a review or a check raised it, anddue_atwhen it has a deadline. - An input: Adds
field_pathandvalue_type. It also carriesresponseonce answered,optionsfor anenumormulti_selectandmetadatawhen it has any. - A composite: Adds
fulfillment_criteriaandsub_requirements, withmetadatawhen it has any. - An action: Adds
metadatawhen it has any.
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 ofrequirement_type composite. Its sub_requirements answer it, as its fulfillment_criteria says:
one_of: Answer any one sub-requirement. Each isconditional, 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 ismandatory, oroptionalwhen it can be left out, such as an address’saddress_line2.
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.
- CKYC Fetch
- Proof of Address
Razorpay fetches the Central KYC Records Registry (CKYC) record with a code, or the sub-merchant skips it:
ckyc_fetch
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 inneeds_clarification. Otherwise, it is listed assettlement_bank_account. Itsclarify_bank_accountoption appears only inneeds_clarification.website: Listed only inneeds_clarification. Otherwise, it is listed aswebsite_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’soptions. Itsvalue_typefollows the question’sbmc_input_type:single_selectbecomesenum,multi_selectstaysmulti_selectandfree_textbecomestext. Know more about the business model questions for each subcategory.
2.2.1 Input Paths
The Requirement Entity lists each input’svalue_type and field_path. Input paths follow the account:
- A person: Under
business_profile.authorized_person, orbusiness_profile.stakeholders.<stakeholder_id>for a stakeholder. - A business identifier or document: Under
business_profile.identity_numbersorbusiness_profile.documents. - An address: Its parts in the
business_profile.addressesitem of thattype, such asbusiness_profile.addresses[type=registered_address].line1. - The bank account: Under
bank_accounts.settlements_primary. - A reply: Under
products.<product_type>.clarification_responses, such asproducts.payment_gateway.clarification_responses.
2.2.2 How Composites Collapse
A document with 2 sides is anall_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_accountcomes back assettlement_bank_account. - Outside
needs_clarification,websitecomes back aswebsite_url.
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 a200, 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_failedandupi_payment_failedhave 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.
PAN and PAN Card
PAN and PAN Card
CKYC and Proof of Address
CKYC and Proof of Address
Bank Account
Bank Account
GSTIN and Udyam Number
GSTIN and Udyam Number
Website
Website
Links
Links
2.4 Review Reasons
Inneeds_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 itsrequirement_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.