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

# 6. Handle Needs Clarification

> Answer a reviewer's clarification using Razorpay Onboarding APIs.

Available in
🇮🇳 India

If a reviewer needs more information, the product's `status` becomes `needs_clarification`. Its `requirements` list only the flagged points, with the reviewer's reason in each `requirement_reason`. Know more about [review reasons](https://razorpay.com/docs/partners/aggregators/onboarding-api/collect-requirements.md#2-4-review-reasons).

Each point is usually a `one_of` composite requirement:

* **For the bank account:** A new account (`settlement_bank_account`), a ₹1 UPI payment (`create_upi_link`) or a reply (`clarify_bank_account`).
* **For the website:** A new website (`website_url`) or a reply (`clarify_website`).

```json bank_account theme={null}
{
  "id": "req_4Z9yuuKZQXabvX",
  "requirement_code": "bank_account",
  "requirement_level": "mandatory",
  "requirement_type": "composite",
  "description": "Your settlement bank account.",
  "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"
}
```

## 6.1 Show the Flagged Points

[Fetch the account](https://razorpay.com/docs/api/partners/accounts/fetch.md) and show the sub-merchant each flagged point's `requirement_reason` and `description`. The `account.product.needs_clarification` webhook also carries the product with its complete requirements.

`GET /v1/accounts/{account_id}`

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

```json Response theme={null}
{
  "id": "acc_TcdGEzmfKQzEl1",
  "country": "IN",
  "statement_descriptor": {
    "value": "Acme Corp",
    "verification": {
      "status": "verified",
      "verified_at": 1792433135
    }
  },
  "is_mfa_enabled": false,
  "user": {
    "role": "owner",
    "email": "gaurav.kumar@example.com",
    "phone": "+919611752201",
    "name": "Gaurav Kumar",
    "is_email_verified": true,
    "is_phone_verified": true
  },
  "business_profile": {
    "business_type": "individual",
    "business_name": "GAURAV KUMAR",
    "date_of_establishment": null,
    "identity_numbers": {},
    "documents": {},
    "business_category": {
      "category": "ecommerce",
      "subcategory": "fashion_and_lifestyle",
      "mcc": "5651",
      "business_description": "Clothing and accessories for men, women and children, sold online",
      "business_model_clarifications": {
        "bmc_question_2": {
          "question_id": "bmc_question_2",
          "question": "What is your average delivery time after receiving an order?",
          "options": [
            {
              "label": "0-7 days",
              "value": "bmc_question_2_option_1"
            },
            {
              "label": "8-14 days",
              "value": "bmc_question_2_option_2"
            },
            {
              "label": "15-21 days",
              "value": "bmc_question_2_option_3"
            },
            {
              "label": "22-35 days",
              "value": "bmc_question_2_option_4"
            },
            {
              "label": "35+ days",
              "value": "bmc_question_2_option_5"
            },
            {
              "label": "No shipping required",
              "value": "bmc_question_2_option_6"
            }
          ],
          "bmc_input_type": "single_select",
          "answer": [
            "bmc_question_2_option_1"
          ]
        }
      }
    },
    "authorized_person": {
      "name": "GAURAV KUMAR",
      "identity_numbers": {
        "individual_pan": {
          "type": "individual_pan",
          "value": "ABCPD1234A",
          "verification": {
            "status": "verified",
            "error_code": null,
            "error_description": null,
            "verified_at": 1792433290,
            "metadata": {},
            "created_at": 1792433290
          },
          "metadata": {},
          "is_skipped": false,
          "created_at": 1792433280,
          "updated_at": 1792433290
        },
        "individual_ckyc": {
          "type": "individual_ckyc",
          "value": null,
          "verification": {
            "status": "verified",
            "error_code": null,
            "error_description": null,
            "verified_at": 1792433340,
            "metadata": {},
            "created_at": 1792433340
          },
          "metadata": {
            "ckyc_mobile": "+919845098450"
          },
          "is_skipped": false,
          "created_at": 1792433340,
          "updated_at": 1792433340
        }
      },
      "documents": {
        "aadhaar_front": {
          "id": "file_Hx7Ui2kQe9Zf3A",
          "type": "aadhaar_front",
          "url": "https://files.razorpay.com/documents/file_Hx7Ui2kQe9Zf3A",
          "metadata": {
            "source": "ckyc",
            "file_name": "aadhaar-front.jpg",
            "mime_type": "image/jpeg",
            "size_bytes": 187342
          },
          "verification": {
            "status": "verified",
            "error_code": null,
            "error_description": null,
            "verified_at": 1792433340,
            "metadata": {},
            "created_at": 1792433340
          },
          "created_at": 1792433340
        }
      },
      "address": null,
      "date_of_birth": null,
      "additional_data": {},
      "created_at": 1792433280,
      "updated_at": 1792433340
    },
    "stakeholders": {},
    "addresses": [],
    "metadata": {}
  },
  "bank_accounts": {
    "settlements_primary": {
      "type": "settlements_primary",
      "account_number": "001234567890",
      "routing_code": "ICIC0000009",
      "routing_code_type": "IFSC",
      "supporting_document": null,
      "verification": {
        "status": "verified",
        "error_code": null,
        "error_description": null,
        "verified_at": 1792435025,
        "metadata": {},
        "created_at": 1792435011
      }
    }
  },
  "products": {
    "payment_gateway": {
      "type": "payment_gateway",
      "status": "needs_clarification",
      "status_reason": null,
      "created_at": 1792433135,
      "updated_at": 1792565490,
      "requirements": [
        {
          "id": "req_4Z9yuuKZQXabvX",
          "requirement_code": "bank_account",
          "requirement_level": "mandatory",
          "requirement_type": "composite",
          "description": "Your settlement bank account.",
          "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": 1792435100
      },
      "payment_channels": {
        "website": {
          "primary": "https://www.example.com",
          "additional": [],
          "verification": {
            "status": "verified",
            "error_code": null,
            "error_description": null,
            "verified_at": 1792433250,
            "metadata": {},
            "created_at": 1792433220
          }
        },
        "app_android": null,
        "app_ios": null
      },
      "clarification_responses": {}
    }
  },
  "notes": {
    "shop_id": "60291847"
  },
  "created_at": 1792433135,
  "updated_at": 1792565490
}
```

## 6.2 Answer Each Point

Answer each point with a corrected value, a document or a text reply, in an [update](https://razorpay.com/docs/api/partners/accounts/update.md).

A text reply goes in `products.payment_gateway.clarification_responses` when the point offers a reply input, such as `clarify_bank_account`. Key each reply by the path of what it answers, as one dotted key. For example, `bank_accounts.settlements_primary` answers the bank account. The key is the reply input's `field_path` after `products.payment_gateway.clarification_responses.`. A reply is offered only in `needs_clarification`, never after a failed check.

`PATCH /v1/accounts/{account_id}`

```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 in my name; the bank shows my shop name Acme Corp on statements."
      }
    }
  }
}'
```

The response shows the replies on the product, in `clarification_responses`. Once every flagged point is answered, `submit_clarification` is the only requirement left:

```json products.payment_gateway theme={null}
{
  "type": "payment_gateway",
  "status": "needs_clarification",
  "status_reason": null,
  "created_at": 1792433135,
  "updated_at": 1792573960,
  "requirements": [
    {
      "id": "req_Wq4Zt8Nc2LkV7p",
      "requirement_code": "submit_clarification",
      "requirement_level": "mandatory",
      "requirement_type": "input",
      "description": "Submit your answers for review.",
      "field_path": "products.payment_gateway.submit_clarification",
      "value_type": "boolean",
      "status": "created"
    }
  ],
  "terms_of_service_acceptance": {
    "ip": "203.0.113.42",
    "device_fingerprint_id": "df_9Hq4Lt2Vb5Ks8Zp",
    "metadata": {},
    "accepted_at": 1792435100
  },
  "payment_channels": {
    "website": {
      "primary": "https://www.example.com",
      "additional": [],
      "verification": {
        "status": "verified",
        "error_code": null,
        "error_description": null,
        "verified_at": 1792433250,
        "metadata": {},
        "created_at": 1792433220
      }
    },
    "app_android": null,
    "app_ios": null
  },
  "clarification_responses": {
    "bank_accounts.settlements_primary": "The account is in my name; the bank shows my shop name Acme Corp on statements."
  }
}
```

> [!WARNING]
>
> **Watch Out!**
>
> Only the listed fields can change. Changing anything else returns `409 field_locked`.

> [accordion] Request Parameters
>
> `products.payment_gateway.clarification_responses` *optional*
> : `object` The sub-merchant's text replies to the flagged points. Each key is the path of what the reply answers, such as `bank_accounts.settlements_primary`, and each value is the reply.
>
> `products.payment_gateway.clarification_responses.<path>` *optional*
> : `string` One reply. A reply to `clarify_bank_account` takes 50 to 300 characters.

## 6.3 Resubmit the Product

Once every flagged point is answered, the product's `submit_clarification` is due at `products.payment_gateway.submit_clarification`. Send it in its own update. Never send a reply and `submit_clarification` in the same body. The product returns to `under_review`.

`PATCH /v1/accounts/{account_id}`

```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
    }
  }
}'
```

If the sub-merchant does not answer in time, Razorpay rejects the product with `status_reason.code` `clarification_not_answered`.

## Next Step

[Track Product Status](https://razorpay.com/docs/partners/aggregators/onboarding-api/product-status.md)
