> ## Documentation Index
> Fetch the complete documentation index at: https://razorpay.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Needs Clarification Tests

> Test needs clarification on Onboarding APIs in Test Mode, including reply and resubmission scenarios.

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](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration) for test credentials and headers.

## 1. Test Mode Coverage

### Test Mode Differences

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

| Behaviour | Live mode | Test mode |
| - | - | - |
| Flagged points | A reviewer flags points after submission, in their own words. | A test value raises the clarification about 5 sec after submission, with the reviewer's wording. |
| Locks | Only the flagged points can change once a product is flagged. | The same lock rules as live mode. |
| Resubmission | The product returns to review, and a reviewer decides. | The product returns to `under_review`, then turns `activated` about 5 sec later. |

### What You Can Test

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

| Area | What to test | In test mode |
| - | - | - |
| Flagged points | Reading them, and each kind of answer | Available |
| Locks | Only flagged points can change | Available |
| Resubmission | `submit_clarification` | Available |

### Endpoint Coverage in Test Mode

The table below lists the endpoints this page uses:

| API | Endpoint | Available in test mode |
| - | - | - |
| [Fetch Accounts](https://razorpay.com/docs/api/partners/accounts/fetch.md) | `GET /v1/accounts/{account_id}` | Available |
| [Update an Account](https://razorpay.com/docs/api/partners/accounts/update.md) | `PATCH /v1/accounts/{account_id}`, to answer and resubmit | Available |
| [Run an Action](https://razorpay.com/docs/api/partners/accounts/run-action.md) | `POST /v1/accounts/{account_id}/actions/create_upi_link` | Available |

## 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](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/terms-and-submission.md). 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:

| Review reason | The point it flags | Test value |
| - | - | - |
| `bank_account_ownership_unconfirmed` | `bank_account` | Settlement account `000000000003` |
| `category_mismatch` | The category | A Merchant Category Code (MCC) that does not match the website, such as `https://curlec.com` with MCC `5399` |
| `website_no_products` | `website` | Website `https://www.kc-no-products.com` |
| `website_policies_missing` | `website` | Website `https://www.kc-no-policies.com` |
| `business_proof_unclear` | `proof_of_business` | A business proof file named `UNCLEAR_` plus the PAN, such as `UNCLEAR_AANPI2846K.pdf` |
| `address_proof_unclear` | `proof_of_address_for_individual` | An Aadhaar front named `AADHAARUNCLEARFRONT.jpg` |

### 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`.

```bash Curl theme={null}
curl -X GET https://api.razorpay.com/v1/accounts/acc_TcdGEzmfKQzEl1 \
-u rzp_test_partner_[CLIENT_ID]:[CLIENT_SECRET]
```

> [accordion] Response: HTTP 200
>
> ```json Response theme={null}
> {
>   "id": "acc_TcdGEzmfKQzEl1",
>   "country": "IN",
>   "statement_descriptor": {
>     "value": "Rzp Test Store",
>     "verification": {
>       "status": "verified",
>       "verified_at": 1793164800
>     }
>   },
>   "is_mfa_enabled": false,
>   "user": {
>     "role": "owner",
>     "email": "test.owner@example.com",
>     "phone": "+919876543210",
>     "name": "Rzp Test QA Merchant",
>     "is_email_verified": true,
>     "is_phone_verified": true
>   },
>   "business_profile": {
>     "business_type": "individual",
>     "business_name": "Rzp Test QA Merchant",
>     "date_of_establishment": null,
>     "identity_numbers": {},
>     "documents": {},
>     "business_category": {
>       "category": "ecommerce",
>       "subcategory": "computers_peripheral_equipment_software",
>       "mcc": "5732",
>       "business_description": "Payment and billing software, sold online"
>     },
>     "authorized_person": {
>       "name": "Rzp Test QA Merchant",
>       "identity_numbers": {
>         "individual_pan": {
>           "type": "individual_pan",
>           "value": "ABCPD1234A",
>           "verification": {
>             "status": "verified",
>             "error_code": null,
>             "error_description": null,
>             "verified_at": 1793164860,
>             "metadata": {},
>             "created_at": 1793164858
>           },
>           "metadata": {},
>           "is_skipped": false,
>           "created_at": 1793164858,
>           "updated_at": 1793164860
>         },
>         "individual_ckyc": {
>           "type": "individual_ckyc",
>           "value": null,
>           "verification": {
>             "status": "verified",
>             "error_code": null,
>             "error_description": null,
>             "verified_at": 1793165040,
>             "metadata": {},
>             "created_at": 1793165038
>           },
>           "metadata": {
>             "ckyc_mobile": "+919845098450"
>           },
>           "is_skipped": false,
>           "created_at": 1793165038,
>           "updated_at": 1793165040
>         }
>       },
>       "documents": {},
>       "address": null,
>       "date_of_birth": null,
>       "additional_data": {},
>       "created_at": 1793164858,
>       "updated_at": 1793165040
>     },
>     "stakeholders": {},
>     "addresses": [],
>     "metadata": {}
>   },
>   "bank_accounts": {
>     "settlements_primary": {
>       "type": "settlements_primary",
>       "account_number": "000000000003",
>       "routing_code": "HDFC0123456",
>       "routing_code_type": "IFSC",
>       "supporting_document": null,
>       "verification": {
>         "status": "verified",
>         "error_code": null,
>         "error_description": null,
>         "verified_at": 1793164940,
>         "metadata": {},
>         "created_at": 1793164938
>       }
>     }
>   },
>   "products": {
>     "payment_gateway": {
>       "type": "payment_gateway",
>       "status": "needs_clarification",
>       "status_reason": null,
>       "created_at": 1793164800,
>       "updated_at": 1793165106,
>       "requirements": [
>         {
>           "id": "req_4Z9yuuKZQXabvX",
>           "requirement_code": "bank_account",
>           "requirement_level": "mandatory",
>           "requirement_type": "composite",
>           "description": "A reviewer couldn't confirm that the payout account is held in your name. Share an account in your name, pay ₹1 from it, or reply.",
>           "requirement_reason": "A reviewer couldn't confirm that the payout account is held in your name. Share an account in your name, pay ₹1 from it, or reply.",
>           "fulfillment_criteria": "one_of",
>           "sub_requirements": [
>             {
>               "id": "req_VgRHb7QJNtMyj2",
>               "requirement_code": "settlement_bank_account",
>               "requirement_level": "conditional",
>               "requirement_type": "composite",
>               "description": "The bank account that receives settlements, in the name on your PAN.",
>               "fulfillment_criteria": "all_of",
>               "sub_requirements": [
>                 {
>                   "id": "req_4rY5OIDnOHtA2z",
>                   "requirement_code": "bank_account_number",
>                   "requirement_level": "mandatory",
>                   "requirement_type": "input",
>                   "description": "The account number.",
>                   "field_path": "bank_accounts.settlements_primary.account_number",
>                   "value_type": "text",
>                   "status": "created"
>                 },
>                 {
>                   "id": "req_mOTextgE1uJfFK",
>                   "requirement_code": "bank_routing_code",
>                   "requirement_level": "mandatory",
>                   "requirement_type": "input",
>                   "description": "The bank's IFSC.",
>                   "field_path": "bank_accounts.settlements_primary.routing_code",
>                   "value_type": "text",
>                   "status": "created"
>                 },
>                 {
>                   "id": "req_GNDdQcckulAU4g",
>                   "requirement_code": "bank_routing_code_type",
>                   "requirement_level": "mandatory",
>                   "requirement_type": "input",
>                   "description": "The kind of routing code.",
>                   "field_path": "bank_accounts.settlements_primary.routing_code_type",
>                   "value_type": "enum",
>                   "options": [
>                     {
>                       "label": "IFSC",
>                       "value": "IFSC"
>                     }
>                   ],
>                   "status": "created"
>                 }
>               ],
>               "status": "created"
>             },
>             {
>               "id": "req_8mFTjW5RY4heOw",
>               "requirement_code": "create_upi_link",
>               "requirement_level": "conditional",
>               "requirement_type": "action",
>               "description": "Or verify the account with a ₹1 UPI payment from it, refunded at once.",
>               "status": "created"
>             },
>             {
>               "id": "req_tRydtFXps2ERyP",
>               "requirement_code": "clarify_bank_account",
>               "requirement_level": "conditional",
>               "requirement_type": "input",
>               "description": "Or reply with a comment if the account is yours.",
>               "field_path": "products.payment_gateway.clarification_responses.bank_accounts.settlements_primary",
>               "value_type": "text",
>               "status": "created"
>             }
>           ],
>           "status": "created"
>         }
>       ],
>       "terms_of_service_acceptance": {
>         "ip": "203.0.113.42",
>         "device_fingerprint_id": "df_9Hq4Lt2Vb5Ks8Zp",
>         "metadata": {},
>         "accepted_at": 1793165100
>       },
>       "payment_channels": {
>         "website": {
>           "primary": "https://curlec.com",
>           "additional": [],
>           "verification": {
>             "status": "verified",
>             "error_code": null,
>             "error_description": null,
>             "verified_at": 1793164935,
>             "metadata": {},
>             "created_at": 1793164930
>           }
>         },
>         "app_android": null,
>         "app_ios": null
>       }
>     }
>   },
>   "notes": {
>     "shop_id": "60291847"
>   },
>   "created_at": 1793164800,
>   "updated_at": 1793165106
> }
> ```

### Answer and Resubmit

Answer each point in an update, as for any requirement. Each call returns the account, as [Update an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/update-account.md) 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:

```bash Curl theme={null}
curl -X PATCH https://api.razorpay.com/v1/accounts/acc_TcdGEzmfKQzEl1 \
-u rzp_test_partner_[CLIENT_ID]:[CLIENT_SECRET] \
-H "Content-Type: application/json" \
-H "X-Idempotency-Key: [UNIQUE_KEY]" \
-d '{
  "products": {
    "payment_gateway": {
      "clarification_responses": {
        "bank_accounts.settlements_primary": "The account is a joint account held with my spouse; my name is the first holder on the passbook."
      }
    }
  }
}'
```

Once every point is answered, `submit_clarification` is the only requirement left. Resubmit in a second call:

```bash Curl theme={null}
curl -X PATCH https://api.razorpay.com/v1/accounts/acc_TcdGEzmfKQzEl1 \
-u rzp_test_partner_[CLIENT_ID]:[CLIENT_SECRET] \
-H "Content-Type: application/json" \
-H "X-Idempotency-Key: [UNIQUE_KEY]" \
-d '{
  "products": {
    "payment_gateway": {
      "submit_clarification": true
    }
  }
}'
```

Know more about the [request parameters](https://razorpay.com/docs/api/partners/accounts/update.md).

## 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:

<table>
  <colgroup>
    <col width="6%" />

    <col width="22%" />

    <col width="24%" />

    <col width="48%" />
  </colgroup>

  <thead><tr><th>#</th><th>Scenario</th><th>Trigger</th><th>What to confirm</th></tr></thead>

  <tbody>
    <tr><td>1</td><td>Read the flagged points Coming soon</td><td>Settlement account `000000000003`, submitted</td><td>Fetch 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.</td></tr>
    <tr><td>2</td><td>Answer with a corrected value Coming soon</td><td>A new bank account, such as `1234567890`</td><td>Send `bank_accounts.settlements_primary`. Confirm `bank_account` clears.</td></tr>
    <tr><td>3</td><td>Answer with a ₹1 UPI payment Coming soon</td><td>`create_upi_link`, then **Pay ₹1** on the hosted test page</td><td>Run the action and open the link. Pick **Pay ₹1**. Confirm `bank_account` clears.</td></tr>
    <tr><td>4</td><td>Answer with a text reply Coming soon</td><td>50 to 300 characters</td><td>Send 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`.</td></tr>
    <tr><td>5</td><td>A reply too short or too long Coming soon</td><td>20 characters, or 400 characters</td><td>Confirm `400 invalid_format`.</td></tr>
    <tr><td>6</td><td>A reply to a point that does not offer one Coming soon</td><td>A reply keyed to `business_profile.business_category`</td><td>Confirm `400 step_not_due`.</td></tr>
    <tr><td>7</td><td>Change something not flagged Coming soon</td><td>A new PAN</td><td>Confirm `409 field_locked`.</td></tr>
    <tr><td>8</td><td>Resubmit with points still open Coming soon</td><td>`submit_clarification: true` too early</td><td>Confirm `400 step_not_due` with `metadata.due`.</td></tr>
    <tr><td>9</td><td>Resubmit Coming soon</td><td>`submit_clarification: true`</td><td>Send it once every point is answered. Confirm `under_review`, then `activated` about 5 sec later.</td></tr>
    <tr><td>10</td><td>The status event Coming soon</td><td>`account.product.needs_clarification`</td><td>Handle the event. Fetch the account and show the points.</td></tr>
  </tbody>
</table>

### 3.2 Scenario Details

The details below expand the scenarios that need more than one step:

> [accordion] 1. Read the Flagged Points
>
> **Before you begin:** Submit an account with settlement account `000000000003`, as in scenario 10 on [Terms and Submission](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/terms-and-submission.md).
>
> **How to test:** Fetch the account, as in [Read the Flagged Points](#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](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/error-index.md#3-review-reasons) list what a reviewer can flag.

> [accordion] 4. Answer With a Text Reply
>
> **How to test:** Send the `clarification_responses` request in [Answer and Resubmit](#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:
>
> ```json theme={null}
> {
>   "products": {
>     "payment_gateway": {
>       "clarification_responses": {
>         "bank_accounts.settlements_primary": "The account is a joint account held with my spouse; my name is the first holder on the passbook."
>       }
>     }
>   }
> }
> ```
>
> **Your integration should:** Count characters in your form: 50 to 300.

> [accordion] 5. A Reply Too Short or Too Long
>
> **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`.

> [accordion] 7. Change Something Not Flagged
>
> **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.

> [accordion] 9. Resubmit
>
> **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](#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](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration) lists the errors every operation shares.

The table below lists the errors a clarification returns:

| Trigger | HTTP | `error.reason` | `error.field` |
| - | - | - | - |
| A reply under 50 or over 300 characters | 400 | `invalid_format` | `products.payment_gateway.clarification_responses.<field>` |
| A reply to a point that does not offer one | 400 | `step_not_due` | `products.payment_gateway.clarification_responses.<field>` |
| `submit_clarification` with points open | 400 | `step_not_due` | `products.payment_gateway.submit_clarification` |
| A change to anything not flagged | 409 | `field_locked` | The key, with `metadata.status: needs_clarification` |

## 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:

| Gap | What goes wrong in production | What to do | Test with |
| - | - | - | - |
| Showing the full form again | The sub-merchant edits other fields, and every change fails with HTTP 409. | Show only the flagged points. | #1, #7 |
| Forgetting to resubmit | Every point is answered, but the product never returns to review. | Send `submit_clarification` when it is the last requirement. | #9 |
| Only offering a new value | A sub-merchant who can explain has to change their bank account. | Offer every sub-requirement, including the reply. | #4 |

## 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:

| Topic | What to know | On this page | Test it | Read more |
| - | - | - | - | - |
| One composite requirement per point | Each flagged point with alternatives is a `one_of` composite with the reviewer's comment. Answering any sub-requirement clears it. | The bank point offers 3 answers. | #2 to #4 | [Collect Requirements](https://razorpay.com/docs/partners/aggregators/onboarding-api/collect-requirements.md) |
| Review reasons | The description is the reviewer's wording. The error index lists the reasons a reviewer can give. | Show it as written. | #1 | [Review Reasons](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/error-index.md#3-review-reasons) |

### Related Information

* [Test Your Integration](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration)
* [Create an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/create-account.md)
* [Fetch an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/fetch-account.md)
* [Update an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/update-account.md)
* [Actions](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/actions.md)
* [Documents](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/documents.md)
* [Terms and Submission](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/terms-and-submission.md)
* [Webhooks](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/webhooks.md)
* [Test Values](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/test-values.md)
* [Error Index](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/error-index.md)
