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.
Requirement Entity
Every requirement and sub-requirement has these parameters. A requirement carries only the keys itsrequirement_type uses.
Unique identifier of this requirement,
req_-prefixed. For example, req_UYTBV02QSYTRVK. Send it with the response.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.Possible values:
mandatory: Needed.conditional: Needed only in the case itsdescriptionstates, or as one of the choices under aone_of.optional: Not needed.
Possible values:
input: Send a response atfield_path, as itsvalue_typesays.action: Run the action named inrequirement_code.composite: Answer itssub_requirementsas itsfulfillment_criteriasays.
An
input only. Where the response goes in an update: products.payment_gateway.requirements.requirement_response, sent under the requirement’s id.An
input only. Possible values:text: Sendrequirement_response.text.enum: Send one ofoptionsasrequirement_response.text.multi_select: Send any ofoptions.boolean: Sendtrueorfalseasrequirement_response.text.document: Sendrequirement_response.documents, each a document ID from Upload a Document.
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.
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_atpassed with responses still due. You can still respond.under_review: You sent your responses. Razorpay is reviewing them.resolved: Razorpay has decided.
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.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
The unique identifier of the account,
acc_ followed by 14 letters or digits. For example, acc_Rk9Xm2Qp7Zt4Nb.Fetch Errors
The requirement doesn't exist on this account.
The requirement doesn't exist on this account.
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_codeasdocument_type, such asproof_of_deliveryorform_12a, in the path and in the body. - The upload alone answers nothing. Send the ID in
requirement_response.documentswith 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-Keymust send the samedocument_typeand file. - This endpoint needs the
onboarding_documents_writescope.
proof_of_delivery and form_12a.
Upload Parameters
The unique identifier of the account,
acc_ followed by 14 letters or digits. For example, acc_Rk9Xm2Qp7Zt4Nb.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.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.
The file: a PDF, JPEG or PNG of up to 20 MB. Razorpay reads the format from the bytes, not from the file name.
Upload Response
Upload Errors
The request is missing a required field.
The request is missing a required field.
Code:
400Reason: invalid_requestThe request has one of these problems:- The body is not
multipart/form-data. fileordocument_typeis missing.- The request has more than 1 file.
document_typein the body is not the one in the path.
multipart/form-data body with 1 file and the same document_type as the path.Choose one of the allowed values (document type).
Choose one of the allowed values (document type).
Code:
400Reason: invalid_optiondocument_type is not a document type.Solution: Send the requirement’s requirement_code, or another valid document type.The file can't be read. Upload it again.
The file can't be read. Upload it again.
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.Upload the file without a password.
Upload the file without a password.
Code:
400Reason: password_protected_fileThe file is password protected.Solution: Remove the password from the file, then upload it again.The file is too large.
The file is too large.
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.Upload a PDF, JPEG or PNG file.
Upload a PDF, JPEG or PNG file.
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.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 itssub_requirementsbyid. - Send
requirement_response.textfor avalue_typeoftext, orrequirement_response.documentsfordocument. - The response is the account. Each requirement you answered carries its
response, and the requirement moves tounder_review. The product’sstatus,payment_acceptanceandsettlementdo not change. - This endpoint needs the
onboarding_accounts_writescope.
Answer Parameters
The unique identifier of the account,
acc_ followed by 14 letters or digits. For example, acc_Rk9Xm2Qp7Zt4Nb.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.
Answer Response
The response is the account, as Fetch the Requirements returns it. Each answered requirement carries itsresponse and the status under_review.
Write Errors
The upload and the PATCH also return these errors.GET does not.