Skip to main content
Available in🇮🇳 India
Raise a reviewer’s clarification on a test account, answer each flagged point and resubmit the product before you go live. After submission, a Razorpay reviewer can ask for more. The product’s status becomes needs_clarification, and its requirements list only the points the reviewer flagged. Answer each point with a corrected value, a document, a ₹1 UPI payment or a text reply. Then send submit_clarification to return the product to review. Start with the overview for test credentials and headers.

1. Test Mode Coverage

Test Mode Differences

The table below lists how a clarification behaves in each mode:

What You Can Test

The table below lists the areas to test for a clarification:

Endpoint Coverage in Test Mode

The table below lists the endpoints this page uses:

2. Before You Begin

Prepare the following before you run the scenarios:
  • Submit an account with settlement account 000000000003, as in scenario 10 on Terms and Submission. Or use another test value from the table below.
  • Wait about 5 sec after submission for the clarification to arrive.

Raise a Clarification

Each test value below flags its point after submission. Combine them to flag several points at once. The table below lists the test values that raise each review reason:

Read the Flagged Points

A product in needs_clarification lists only the points the reviewer flagged. A point with alternatives is a one_of composite requirement. Its description is the reviewer’s comment, and its requirement_reason says why the reviewer flagged it. Each sub-requirement keeps its usual description. Once every flagged point is answered, products.payment_gateway.submit_clarification is due. The response below is test business Individual A, submitted with settlement account 000000000003.
Curl
Response

Answer and Resubmit

Answer each point in an update, as for any requirement. Each call returns the account, as Update an Account does. Send a text reply in the product’s clarification_responses, keyed by the path of what it answers. This reply answers the bank point:
Curl
Once every point is answered, submit_clarification is the only requirement left. Resubmit in a second call:
Curl
Know more about the request parameters.

3. Test Scenarios

Work through these scenarios in order. Each row gives the trigger to send and what to confirm in the response.

3.1 Scenarios

Live scenarios work in test mode today. Coming soon scenarios are not available in test mode yet. The table below lists 10 scenarios. All 10 are coming soon:
#ScenarioTriggerWhat to confirm
1Read the flagged points Coming soonSettlement account 000000000003, submittedFetch the account. Show each flagged requirement’s description, which is the reviewer’s comment. Show the sub-requirements of a one_of composite as 1 choice.
2Answer with a corrected value Coming soonA new bank account, such as 1234567890Send bank_accounts.settlements_primary. Confirm bank_account clears.
3Answer with a ₹1 UPI payment Coming sooncreate_upi_link, then Pay ₹1 on the hosted test pageRun the action and open the link. Pick Pay ₹1. Confirm bank_account clears.
4Answer with a text reply Coming soon50 to 300 charactersSend it in products.payment_gateway.clarification_responses, keyed by the path of what it answers. For the clarify_bank_account input, the key is bank_accounts.settlements_primary. Confirm the reply shows in the product’s clarification_responses.
5A reply too short or too long Coming soon20 characters, or 400 charactersConfirm 400 invalid_format.
6A reply to a point that does not offer one Coming soonA reply keyed to business_profile.business_categoryConfirm 400 step_not_due.
7Change something not flagged Coming soonA new PANConfirm 409 field_locked.
8Resubmit with points still open Coming soonsubmit_clarification: true too earlyConfirm 400 step_not_due with metadata.due.
9Resubmit Coming soonsubmit_clarification: trueSend it once every point is answered. Confirm under_review, then activated about 5 sec later.
10The status event Coming soonaccount.product.needs_clarificationHandle the event. Fetch the account and show the points.

3.2 Scenario Details

The details below expand the scenarios that need more than one step:
Before you begin: Submit an account with settlement account 000000000003, as in scenario 10 on Terms and Submission.How to test: Fetch the account, as in Read the Flagged Points.Expected result: The product is needs_clarification, and requirements lists only the flagged points. The bank point is the bank_account composite, raised for the review reason bank_account_ownership_unconfirmed. Its requirement_reason explains it. It is a one_of of 3 sub-requirements:
  • A corrected account (settlement_bank_account)
  • A ₹1 UPI payment (create_upi_link)
  • A reply (clarify_bank_account)
Webhooks: account.product.under_review, then account.product.needs_clarification.Your integration should: Show the reviewer’s comment as written and offer every sub-requirement, nothing else. The review reasons list what a reviewer can flag.
How to test: Send the clarification_responses request in Answer and Resubmit.Expected result: HTTP 200, and bank_account clears. The reply shows in products.payment_gateway.clarification_responses, keyed by the path of what it answers:
Your integration should: Count characters in your form: 50 to 300.
How to test: Send a 20-character reply.Expected result: HTTP 400 with reason: invalid_format and field: products.payment_gateway.clarification_responses.bank_accounts.settlements_primary. metadata carries minimum: 50 and maximum: 300.
How to test: Send a new PAN while the product is needs_clarification.Expected result: HTTP 409 with reason: field_locked, field: business_profile.authorized_person.identity_numbers.individual_pan and metadata.status: needs_clarification.Your integration should: Lock everything in your UI except the flagged points.
Before you begin: Answer every flagged point. The only requirement left is products.payment_gateway.submit_clarification.How to test: Send the resubmit request in Answer and Resubmit.Expected result: HTTP 200 with the product under_review. About 5 sec later, it is activated. A test value raises a clarification once per account.Webhooks: account.product.under_review, then account.product.activated.Your integration should: Resubmit only once submit_clarification is the last requirement.

3.3 Errors to Handle

Every error returns the same object. Branch on error.reason and error.field, because the description can change. The overview lists the errors every operation shares. The table below lists the errors a clarification returns:

4. Common Integration Gaps

These mistakes most often stall an onboarding or leave an account in the wrong state after go-live. The Test with column points to the scenario that proves you have handled each one. Answering The table below lists the gaps in answering a clarification:

5. Best Integration Practices

These practices apply to every onboarding integration. The On this page column says what each one means here. The table below lists the practices for a clarification:
Last modified on November 18, 2026