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

# Private Limited Tests

> Test private limited company onboarding on Onboarding APIs in Test Mode, including CIN and stakeholder scenarios.

Available in
🇮🇳 India

A private limited company onboards with its business PAN and its Corporate Identification Number (CIN) or certificate of incorporation. It also needs an authorised person, its beneficial owners and its addresses. The bank account must be in the company name. The authorised person's Central KYC Records Registry (CKYC) record decides whether video KYC is due.

Before you start, check that your test credentials and headers work. See [Test Your Integration](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration). Every request and response body is on the API test pages, starting with [Create an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/create-account.md).

## 1. Test Mode Coverage

### Test Mode Differences

The table below compares live mode and test mode for this business type:

| Behaviour | Live mode | Test mode |
| - | - | - |
| Business PAN, CIN and signatories | The PAN registry and the Registrar of Companies confirm the company and list its directors. | The number decides the outcome, from the [Test Values](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/test-values.md). The directors on record are the test business directors. |
| Company documents | We read each document and check it against the company. | The file name decides the outcome, and we do not read the content. |
| Phone and email codes | We send a 6-digit code by SMS and email when you run `send_phone_otp` or `send_email_otp`. The sub-merchant types it into your form. | We send no SMS or email. The action responds as in live mode. The code `000007` verifies. Any other 6 digits is a wrong code. Test mode cannot show whether your sub-merchants receive the messages. |
| The CKYC code | If the person's PAN has a CKYC record, `send_ckyc_otp` sends a code to that record's mobile number. The code fetches the record. | The PAN in the test business decides whether a record exists. We do not send the code. Any 6 digits other than `000000` verifies it. |
| Review after submission | We activate most products at submission. Some go to a Razorpay reviewer, which can take hours or days. The product can stay `under_review` the whole time. | No reviewer is involved. The settlement account or a business name suffix picks the outcome. A review outcome lands about 5 sec after submission. A test value that holds the review takes 5 min. One that acts after activation takes 60 sec. Do not size your timeouts or sub-merchant messaging from these timings. |
| Video KYC | The sub-merchant joins a short video call with a Razorpay agent at the link that `create_video_kyc_link` returns. | The link opens a hosted test page where you pick the call outcome: **Approved**, **Rejected** or **Unable to verify**. No camera or agent is involved. |
| DigiLocker and the ₹1 UPI link | The sub-merchant shares their Aadhaar in DigiLocker at the link the action returns. For the UPI link, they pay ₹1 from the bank account. | The link opens a hosted test page where you pick the outcome. No sign-in or payment is involved. |
| Status webhooks | We send an event when a product moves to `under_review`, `edd_pending`, `needs_clarification`, `activated`, `rejected` or `suspended`. We also send one when requirements change without a call from you, such as an `in_progress` check that settles later. | The same events go to your test mode webhook URL with `mode: test`, a few seconds after each change. |

### What You Can Test

The table below lists what this page tests:

| Area | What to test |
| - | - |
| Activation | Account creation to `activated`: scenario 1. |
| Signatory and owners | Scenarios 3 and 4. |
| Video KYC | By value: scenario 8. |
| Failed checks | Business PAN, signatory, proof of address, bank and website, in [3.3 Error Scenarios](#3-3-error-scenarios). |
| Clarification, review and links | Scenarios 27, 28, 31 and 32. |

### Endpoint Coverage in Test Mode

The table below lists the endpoints this business type uses:

| API | Endpoint | Available in test mode |
| - | - | - |
| Create an account | [`POST /v1/accounts`](https://razorpay.com/docs/api/partners/accounts/create) | Available |
| Fetch one account | [`GET /v1/accounts/{account_id}`](https://razorpay.com/docs/api/partners/accounts/fetch) | Available |
| Update an account | [`PATCH /v1/accounts/{account_id}`](https://razorpay.com/docs/api/partners/accounts/update) | Available |
| Send the phone and email codes | [`POST /v1/accounts/{account_id}/actions/send_phone_otp`](https://razorpay.com/docs/api/partners/accounts/run-action) and `…/send_email_otp` | Available |
| Send the CKYC code | [`POST /v1/accounts/{account_id}/actions/send_ckyc_otp`](https://razorpay.com/docs/api/partners/accounts/run-action) | Available |
| Create the video KYC link | [`POST /v1/accounts/{account_id}/actions/create_video_kyc_link`](https://razorpay.com/docs/api/partners/accounts/run-action) | Available |
| Create a DigiLocker link | [`POST /v1/accounts/{account_id}/actions/create_aadhaar_digilocker_link`](https://razorpay.com/docs/api/partners/accounts/run-action) | Available |
| Create a ₹1 UPI link | [`POST /v1/accounts/{account_id}/actions/create_upi_link`](https://razorpay.com/docs/api/partners/accounts/run-action) | Available |
| Upload a document | [`POST /v1/accounts/{account_id}/documents`](https://razorpay.com/docs/api/partners/accounts/upload-document) | Available |
| Accept the terms and submit | [`PATCH /v1/accounts/{account_id}`](https://razorpay.com/docs/api/partners/accounts/update) with `products.payment_gateway.terms_of_service_acceptance` | Available |

### Webhooks

An onboarding fires the events below. Test mode accounts send them to your test mode webhook URL.

The table below lists each webhook and what to do when it arrives:

| Webhook | Fires when and what to do | In test mode |
| - | - | - |
| `account.product.under_review` | A product was submitted, its video KYC call finished or it was resubmitted after a clarification. Lock the KYC details in your app. | Available |
| `account.product.edd_pending` | The product needs video KYC before review continues. Show the video KYC link. | Available |
| `account.product.needs_clarification` | A reviewer flagged points. Fetch the account and show only those points. | Available |
| `account.product.activated` | The product is live. Turn on payments for the shop. | Available |
| `account.product.rejected` | The application was not approved. Stop offering changes. | Available |
| `account.product.suspended` | An activated product was suspended, and `status_reason` says why. Stop payments and ask for what `requirements` lists. | Available |
| `account.requirements.updated` | Requirements changed without a call from you. A check finished after the response, or the sub-merchant completed a step at a link. Fetch the account and render the requirements again. | Available |
| `account.consent.withdrawn` | The sub-merchant withdrew your access through Razorpay. Stop calling the API for the account. | Available |

### Webhooks Each Scenario Fires

The table below lists the webhooks that key scenarios fire:

| Scenario | Webhooks | In test mode |
| - | - | - |
| 1: Activated | `account.requirements.updated` (as the website check settles), `account.product.activated` | Available |
| 8: Video KYC | `account.requirements.updated` (as the website check settles), `account.product.edd_pending`, `account.requirements.updated`, `account.product.under_review`, `account.product.activated` | Available |
| 7: Rejected | `account.requirements.updated` (as the website check settles), `account.product.under_review`, `account.product.rejected` | Available |

### Before You Trust a Webhook

Follow these rules before you act on any webhook:

* **Verify the signature** on the raw body with your webhook secret before you parse it. Reject anything that fails.
* **Expect repeats.** An event can arrive more than once. Use `X-Razorpay-Event-Id` to process each event once.
* **Expect events out of order.** Compare `payload.account.updated_at`, or fetch the account and act on its current status.
* **Do not wait on webhooks.** The payload carries only what changed: the complete product, with its status and requirements. Fetch the account for the rest, and fetch when an event is late.

### Product Statuses

Take payments only while the product is `activated`. Every status is reachable in test mode.

The table below lists the product statuses:

| Status | Means | Accepts payments | Webhook | Available in test mode |
| - | - | - | - | - |
| `created` | The product is on the account | No | None | Available |
| `in_progress` | Values are coming in. `requirements` lists what is left | No | None | Available |
| `under_review` | Submitted for Razorpay review | No | `account.product.under_review` | Available |
| `edd_pending` | Submitted with video KYC due | No | `account.product.edd_pending` | Available |
| `needs_clarification` | A reviewer flagged points to answer | No | `account.product.needs_clarification` | Available |
| `activated` | Live | Yes, in live mode | `account.product.activated` | Available |
| `rejected` | Not approved, with no further changes | No | `account.product.rejected` | Available |
| `suspended` | Stopped after being live | No | `account.product.suspended` | Available |

## 2. Before You Begin

Set up the following before you start:

* Generate your app's **test** key and secret pair on the Partner Dashboard. The test pair sends every request to test mode. Its key starts with `rzp_test_partner_`.
* Use the same endpoints and request bodies as in live mode. Only the key changes. Every write carries an `X-Idempotency-Key` header.
* Send each input's value at its `field_path`, in the order that `requirements` lists them.
* Subscribe a test mode webhook URL on the Partner Dashboard to receive each scenario's webhooks.

The value you send decides each check. As for an individual, the signatory's CKYC record decides whether video KYC is due.

For example, business PAN `MERCM3412F` verifies with the name `Meridian Foods Private Limited`. Business PAN `ABCCD1234B` fails with `pan_not_found`.

Keep these rules in mind when you pick values:

* **To succeed**, use the test business below.
* **To fail a check**, send one of the values in [3.3 Error Scenarios](#3-3-error-scenarios).
* **You need no real details.** Nothing reaches a registry, a bank or the sub-merchant. Skip the real PAN, bank account, phone and video call.
* **Any other value** fails as if the registry or bank were down.

### Test Business

The test business uses the Indian Financial System Code (IFSC) `HDFC0123456` for its bank account.

The table below lists the private limited test business:

| Field | Value |
| - | - |
| `business_name` | `Meridian Foods Private Limited` |
| Business PAN | `MERCM3412F` |
| CIN | `U15400KA2017PTC104652` |
| `date_of_establishment` | `2017-06-21` |
| Authorised person | `Ananya Iyer`, PAN `AANPI2846K` (with a CKYC record) |
| Goods and Services Tax Identification Number (GSTIN) | `29MERCM3412F1ZD` |
| Second director | `Rohan Kulkarni`, PAN `ROHPK5163M` |
| Signatory's Aadhaar, if `skip_ckyc` is sent | `AADHARFRONT_AANPI2846K.jpg`, `AADHARBACK_AANPI2846K.jpg` |
| Bank account | `5566770003`, holder `Meridian Foods Private Limited` |
| `business_pan` (file) | `BUSINESS_PAN_MERCM3412F.pdf` |
| `certificate_of_incorporation` (file) | `COI_MERCM3412F.pdf` |

## 3. Test Scenarios

This section lists every scenario to run against your integration for this business type before you go live. We group the scenarios by what each one proves. Work down the page in order to cover the integration end to end.

The scenarios fall into 4 groups:

* **Must-build**: The successful path and the outcomes you are almost certain to meet once live. Run these first.
* **Other common scenarios**: Scenarios shared with the other business types, so the same handling must work on every one.
* **Error scenarios**: Failed checks you trigger with a test value, so you check your handling without waiting for a real failure.
* **Review, links and after activation**: Outcomes that a reviewer, a hosted link or a later change decides. Test values and the hosted test pages force each one.

Each scenario's steps end with the webhooks it fires and the status it leaves. In test mode, the webhooks go to your test mode webhook URL.

### 3.1 Must-Build Scenarios

**Live** scenarios work in test mode today. **Coming soon** scenarios are not available in test mode yet.

The table below lists the must-build scenarios:

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

    <col width="20%" />

    <col width="20%" />

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

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

  <tbody>
    <tr>
      <td>1</td>
      <td>Activated end to end Coming soon</td>
      <td>The test business, step by step</td>

      <td>
        <ol>
          <li>Create the account with `country`, the user and `products: { "payment_gateway": { "payment_channels": {} } }`. See [Create an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/create-account.md). Confirm `business_type`, `send_phone_otp` and `send_email_otp` are due.</li>
          <li>Run `send_phone_otp` and `send_email_otp`, then send `000007` as `phone_otp` and `email_otp`.</li>
          <li>Send `business_type: private_limited`, the business PAN `MERCM3412F` at `business_profile.identity_numbers.business_pan` and the CIN `U15400KA2017PTC104652` at `business_profile.identity_numbers.cin`.</li>
          <li>Confirm both are `verified` and the PAN record's name `Meridian Foods Private Limited` comes back as `business_name`. Confirm `business_pan` and `business_identity` clear.</li>
          <li>Send the authorised person `Ananya Iyer` with PAN `AANPI2846K` at `business_profile.authorized_person`. This person has a CKYC record, so `ckyc_fetch` is due.</li>
          <li>Run `send_ckyc_otp` with `metadata.ckyc_mobile` `+919845098450`, or without it to use the mobile number on the CKYC record.</li>
          <li>Send any 6 digits other than `000000` as `individual_ckyc.otp`, with its request ID as `individual_ckyc.request_id`. Confirm `verified`.</li>
          <li>Send `date_of_establishment` `2017-06-21`.</li>
          <li>Send GSTIN `29MERCM3412F1ZD`. The `gstin` requirement is `conditional`, needed if the turnover is over ₹40,00,000 or the business sells across states.</li>
          <li>Send `stakeholders` with the name, PAN and `percentage_ownership` of everyone who owns over 10%.</li>
          <li>Send `registered_address` and `operational_address` under `business_profile.addresses`. Each is `all_of` its lines, city, state, postal code and country. `line2` is optional.</li>
          <li>Send bank account `5566770003` with IFSC `HDFC0123456`. Confirm it is `verified` with the holder `Meridian Foods Private Limited`.</li>
          <li>Send the category `ecommerce` with the subcategory `computers_peripheral_equipment_software` (MCC `5732`) and a description.</li>
          <li>Send the website `https://curlec.com` and a statement descriptor at `statement_descriptor.value`.</li>
          <li>The test category, `computers_peripheral_equipment_software`, asks no business-model questions. To test them, see scenario 8 on [Update an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/update-account.md).</li>
          <li>Show Razorpay's terms of service to the sub-merchant. Then send the sub-merchant's `ip` and `device_fingerprint_id` in `products.payment_gateway.terms_of_service_acceptance`. See [Terms and Submission](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/terms-and-submission.md).</li>
          <li>Confirm the response is `activated`.</li>
          <li>Webhooks received: `account.requirements.updated` (as the website check settles), `account.product.activated`.</li>
          <li>Status changes: `in_progress` → `activated`.</li>
        </ol>
      </td>
    </tr>

    <tr>
      <td>2</td>
      <td>Create everything at once Coming soon</td>
      <td>The values above in one account creation call</td>

      <td>
        <ol>
          <li>Send the values in the shape of the one-shot request on [Create an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/create-account.md).</li>
          <li>Confirm `201`. Answer what is left (the CKYC code, the questions and the terms) and submit.</li>
          <li>Webhooks received: `account.requirements.updated` (as the website check settles), `account.product.activated`.</li>
          <li>Status changes: `in_progress` → `activated`.</li>
        </ol>
      </td>
    </tr>

    <tr>
      <td>3</td>
      <td>Beneficial owners Coming soon</td>
      <td>Everyone who owns over 10%</td>

      <td>
        <ol>
          <li>Send `stakeholders` keyed by any new key. Each entry has `name`, `identity_numbers.individual_pan` and `percentage_ownership`.</li>
          <li>Confirm Razorpay returns each beneficial owner under a `per_` stakeholder ID.</li>
          <li>Webhooks received: none.</li>
          <li>Status changes: none.</li>
        </ol>
      </td>
    </tr>
  </tbody>
</table>

### 3.2 Other Common Scenarios

The table below lists the other common scenarios:

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

    <col width="20%" />

    <col width="20%" />

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

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

  <tbody>
    <tr>
      <td>4</td>
      <td>Signatory with a CKYC record Coming soon</td>
      <td>`Ananya Iyer`</td>

      <td>
        <ol>
          <li>Send the signatory's name and PAN. Fetch the CKYC record with `send_ckyc_otp` and the code.</li>
          <li>Confirm no proof of address is due for the signatory, unless `skip_ckyc` is sent.</li>
          <li>Webhooks received: none.</li>
          <li>Status changes: none.</li>
        </ol>
      </td>
    </tr>

    <tr>
      <td>5</td>
      <td>The documents instead of the numbers Coming soon</td>
      <td>`BUSINESS_PAN_MERCM3412F.pdf`, `COI_MERCM3412F.pdf`</td>

      <td>
        <ol>
          <li>Upload `BUSINESS_PAN_MERCM3412F.pdf` (`type: business_pan`) and `COI_MERCM3412F.pdf` (`type: certificate_of_incorporation`).</li>
          <li>Attach the PAN card at `business_profile.documents.business_pan` in place of the business PAN.</li>
          <li>Attach the certificate at `business_profile.documents.certificate_of_incorporation` in place of the CIN.</li>
          <li>Confirm each is `verified`.</li>
          <li>Confirm `business_pan` and `business_identity` cleared.</li>
          <li>Webhooks received: none.</li>
          <li>Status changes: none.</li>
        </ol>
      </td>
    </tr>

    <tr>
      <td>6</td>
      <td>The CIN clears the business identity Coming soon</td>
      <td>CIN `U15400KA2017PTC104652`</td>

      <td>
        <ol>
          <li>Send the CIN.</li>
          <li>Confirm `business_identity` cleared, so no certificate of incorporation is due.</li>
          <li>Webhooks received: none.</li>
          <li>Status changes: none.</li>
        </ol>
      </td>
    </tr>

    <tr>
      <td>7</td>
      <td>Rejected (also on proprietorships) Coming soon</td>
      <td>`business_name` `Meridian Foods Private Limited_REJECT`, or settlement account `000000000002`</td>

      <td>
        <ol>
          <li>Submit the account.</li>
          <li>Confirm the response is `under_review`, then fetch the account after 5 sec. Confirm `rejected`.</li>
          <li>Webhooks received: `account.requirements.updated` (as the website check settles), `account.product.under_review`, `account.product.rejected`.</li>
          <li>Status changes: `under_review` → `rejected`.</li>
        </ol>
      </td>
    </tr>

    <tr>
      <td>8</td>
      <td>Video KYC by value (also on proprietorships) Coming soon</td>
      <td>`business_name` `Meridian Foods Private Limited_EDD`, or settlement account `000000000004`</td>

      <td>
        <ol>
          <li>Submit the account. Confirm the response is `edd_pending`, with `create_video_kyc_link` due.</li>
          <li>Run the action, open the link and pick **Approved**.</li>
          <li>Fetch the account after 5 sec. Confirm `activated`.</li>
          <li>Webhooks received: `account.requirements.updated` (as the website check settles), `account.product.edd_pending`, `account.requirements.updated`, `account.product.under_review`, `account.product.activated`.</li>
          <li>Status changes: `edd_pending` → `under_review` → `activated`.</li>
        </ol>
      </td>
    </tr>

    <tr>
      <td>9</td>
      <td>Fetch to follow the status (also on every business type) Coming soon</td>
      <td>Settlement account `000000000002`</td>

      <td>
        <ol>
          <li>Submit the account. Confirm the response is `under_review`.</li>
          <li>Poll the account with a timeout.</li>
          <li>Confirm `rejected` arrives about 5 sec later, and that your code never treats `under_review` as final.</li>
          <li>Webhooks received: `account.requirements.updated` (as the website check settles), `account.product.under_review`, `account.product.rejected`.</li>
          <li>Status changes: `under_review` → `rejected`.</li>
        </ol>
      </td>
    </tr>
  </tbody>
</table>

### 3.3 Error Scenarios

We group the error scenarios by the check or request that fails. In the error object, `…authorized_person` stands for `business_profile.authorized_person`. `…website.primary` stands for `products.payment_gateway.payment_channels.website.primary`.

**PAN Registry**

The PAN registry said no, or did not answer. Most failures bring back `individual_pan` or `business_pan`, meaning the number or the card.

The table below lists the PAN registry scenarios:

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

    <col width="17%" />

    <col width="16%" />

    <col width="25%" />

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

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

  <tbody>
    <tr>
      <td>10</td>
      <td>Business PAN: the business PAN is invalid Coming soon</td>
      <td>`ABCCD1234B`</td>
      <td>`verification.status`: `rejected`\
      `verification.error_code`: `pan_not_found`\
      At: `business_profile.identity_numbers.business_pan`\
      Due again: `business_profile.identity_numbers.business_pan`, `business_profile.documents.business_pan`\
      Composite requirement: `business_pan`</td>

      <td>
        <ol>
          <li>Send the value where it is due. Confirm the response is a `200`.</li>
          <li>Webhooks received: none, because the response carries the failure.</li>
          <li>Status changes: none. The product stays `in_progress`.</li>
        </ol>
      </td>
    </tr>

    <tr>
      <td>11</td>
      <td>Business PAN: no record exists for the business PAN Coming soon</td>
      <td>`ABCCD1234C`</td>
      <td>`verification.status`: `rejected`\
      `verification.error_code`: `pan_not_found`\
      At: `business_profile.identity_numbers.business_pan`\
      Due again: `business_profile.identity_numbers.business_pan`, `business_profile.documents.business_pan`\
      Composite requirement: `business_pan`</td>

      <td>
        <ol>
          <li>Send the value where it is due. Confirm the response is a `200`.</li>
          <li>Webhooks received: none, because the response carries the failure.</li>
          <li>Status changes: none. The product stays `in_progress`.</li>
        </ol>
      </td>
    </tr>

    <tr>
      <td>12</td>
      <td>Business PAN: the registry errored, but the PAN is fine Coming soon</td>
      <td>`ABCCD1234D`</td>
      <td>`verification.status`: `rejected`\
      `verification.error_code`: `pan_check_unavailable`\
      At: `business_profile.identity_numbers.business_pan`\
      Due again: `business_profile.identity_numbers.business_pan`, `business_profile.documents.business_pan`\
      Composite requirement: `business_pan`</td>

      <td>
        <ol>
          <li>Send the value where it is due. Confirm the response is a `200`.</li>
          <li>Webhooks received: none, because the response carries the failure.</li>
          <li>Status changes: none. The product stays `in_progress`.</li>
        </ol>
      </td>
    </tr>

    <tr>
      <td>13</td>
      <td>Signatory: the PAN holder is not the named signatory Coming soon</td>
      <td>Name `Rohan Kulkarni` with PAN `AANPI2846K`</td>
      <td>`verification.status`: `rejected`\
      `verification.error_code`: `pan_name_mismatch`\
      At: `…authorized_person.identity_numbers.individual_pan`\
      Due again: `…authorized_person.name`, `…authorized_person.identity_numbers.individual_pan`, `…authorized_person.documents.individual_pan_document`\
      Composite requirement: `authorized_person`</td>

      <td>
        <ol>
          <li>Send the value where it is due. Confirm the response is a `200`.</li>
          <li>Webhooks received: none, because the response carries the failure.</li>
          <li>Status changes: none. The product stays `in_progress`.</li>
        </ol>
      </td>
    </tr>
  </tbody>
</table>

**Documents**

The file was unreadable, or did not match what was sent. Ask for the right file.

The table below lists the document scenarios:

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

    <col width="17%" />

    <col width="16%" />

    <col width="25%" />

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

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

  <tbody>
    <tr>
      <td>14</td>
      <td>Proof of address: the Aadhaar is in another name Coming soon</td>
      <td>`AADHARMISMATCHFRONT.jpg`</td>
      <td>`verification.status`: `rejected`\
      `verification.error_code`: `poa_name_mismatch`\
      At: `…authorized_person.documents.aadhaar_front`\
      Due again: `create_aadhaar_digilocker_link`, `…authorized_person.documents.aadhaar_front`, `…authorized_person.documents.aadhaar_back`, `…authorized_person.documents.passport_front`, `…authorized_person.documents.passport_back`, `…authorized_person.documents.voter_id_front`, `…authorized_person.documents.voter_id_back`\
      Composite requirement: `proof_of_address_for_individual`</td>

      <td>
        <ol>
          <li>Upload the file with its type and attach its `id` where it is due.</li>
          <li>Confirm the response is a `200`.</li>
          <li>Webhooks received: none, because the response carries the failure.</li>
          <li>Status changes: none. The product stays `in_progress`.</li>
        </ol>
      </td>
    </tr>

    <tr>
      <td>15</td>
      <td>Proof of address: the Aadhaar is unreadable Coming soon</td>
      <td>`AADHAARUNREADABLEFRONT.jpg`</td>
      <td>`verification.status`: `rejected`\
      `verification.error_code`: `poa_unreadable`\
      At: `…authorized_person.documents.aadhaar_front`\
      Due again: `create_aadhaar_digilocker_link`, `…authorized_person.documents.aadhaar_front`, `…authorized_person.documents.aadhaar_back`, `…authorized_person.documents.passport_front`, `…authorized_person.documents.passport_back`, `…authorized_person.documents.voter_id_front`, `…authorized_person.documents.voter_id_back`\
      Composite requirement: `proof_of_address_for_individual`</td>

      <td>
        <ol>
          <li>Upload the file with its type and attach its `id` where it is due.</li>
          <li>Confirm the response is a `200`.</li>
          <li>Webhooks received: none, because the response carries the failure.</li>
          <li>Status changes: none. The product stays `in_progress`.</li>
        </ol>
      </td>
    </tr>
  </tbody>
</table>

**Bank**

The bank check failed. `bank_account` comes back as `one_of`: the same or another account (`settlement_bank_account`), or the ₹1 UPI link (`create_upi_link`). Show them as one choice.

The table below lists the bank scenarios:

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

    <col width="17%" />

    <col width="16%" />

    <col width="25%" />

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

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

  <tbody>
    <tr>
      <td>16</td>
      <td>Bank account: the holder name does not match Coming soon</td>
      <td>`2100000011`</td>
      <td>`verification.status`: `rejected`\
      `verification.error_code`: `bank_name_mismatch`\
      At: `bank_accounts.settlements_primary`\
      Due again: `bank_accounts.settlements_primary`, `create_upi_link`\
      Composite requirement: `bank_account`</td>

      <td>
        <ol>
          <li>Send the value where it is due. Confirm the response is a `200`.</li>
          <li>Webhooks received: none, because the response carries the failure.</li>
          <li>Status changes: none. The product stays `in_progress`.</li>
        </ol>
      </td>
    </tr>

    <tr>
      <td>17</td>
      <td>Bank account: the holder name is close but under the match threshold Coming soon</td>
      <td>`2100000012`</td>
      <td>`verification.status`: `rejected`\
      `verification.error_code`: `bank_name_mismatch`\
      At: `bank_accounts.settlements_primary`\
      Due again: `bank_accounts.settlements_primary`, `create_upi_link`\
      Composite requirement: `bank_account`</td>

      <td>
        <ol>
          <li>Send the value where it is due. Confirm the response is a `200`.</li>
          <li>Webhooks received: none, because the response carries the failure.</li>
          <li>Status changes: none. The product stays `in_progress`.</li>
        </ol>
      </td>
    </tr>

    <tr>
      <td>18</td>
      <td>Bank account: the IFSC is invalid Coming soon</td>
      <td>`2100000040`</td>
      <td>`verification.status`: `rejected`\
      `verification.error_code`: `bank_details_incorrect`\
      At: `bank_accounts.settlements_primary`\
      Due again: `bank_accounts.settlements_primary`, `create_upi_link`\
      Composite requirement: `bank_account`</td>

      <td>
        <ol>
          <li>Send the value where it is due. Confirm the response is a `200`.</li>
          <li>Webhooks received: none, because the response carries the failure.</li>
          <li>Status changes: none. The product stays `in_progress`.</li>
        </ol>
      </td>
    </tr>

    <tr>
      <td>19</td>
      <td>Bank account: the account is closed Coming soon</td>
      <td>`1234567892`</td>
      <td>`verification.status`: `rejected`\
      `verification.error_code`: `bank_account_unusable`\
      At: `bank_accounts.settlements_primary`\
      Due again: `bank_accounts.settlements_primary`, `create_upi_link`\
      Composite requirement: `bank_account`</td>

      <td>
        <ol>
          <li>Send the value where it is due. Confirm the response is a `200`.</li>
          <li>Webhooks received: none, because the response carries the failure.</li>
          <li>Status changes: none. The product stays `in_progress`.</li>
        </ol>
      </td>
    </tr>

    <tr>
      <td>20</td>
      <td>Bank account: the account is frozen Coming soon</td>
      <td>`2100000005`</td>
      <td>`verification.status`: `rejected`\
      `verification.error_code`: `bank_account_unusable`\
      At: `bank_accounts.settlements_primary`\
      Due again: `bank_accounts.settlements_primary`, `create_upi_link`\
      Composite requirement: `bank_account`</td>

      <td>
        <ol>
          <li>Send the value where it is due. Confirm the response is a `200`.</li>
          <li>Webhooks received: none, because the response carries the failure.</li>
          <li>Status changes: none. The product stays `in_progress`.</li>
        </ol>
      </td>
    </tr>

    <tr>
      <td>21</td>
      <td>Bank account: a Non-Resident External (NRE) account cannot receive settlements Coming soon</td>
      <td>`2100000006`</td>
      <td>`verification.status`: `rejected`\
      `verification.error_code`: `bank_account_unusable`\
      At: `bank_accounts.settlements_primary`\
      Due again: `bank_accounts.settlements_primary`, `create_upi_link`\
      Composite requirement: `bank_account`</td>

      <td>
        <ol>
          <li>Send the value where it is due. Confirm the response is a `200`.</li>
          <li>Webhooks received: none, because the response carries the failure.</li>
          <li>Status changes: none. The product stays `in_progress`.</li>
        </ol>
      </td>
    </tr>

    <tr>
      <td>22</td>
      <td>Bank account: the bank was unreachable, but the account is fine Coming soon</td>
      <td>`2100000039`</td>
      <td>`verification.status`: `rejected`\
      `verification.error_code`: `bank_check_unavailable`\
      At: `bank_accounts.settlements_primary`\
      Due again: `bank_accounts.settlements_primary`, `create_upi_link`\
      Composite requirement: `bank_account`</td>

      <td>
        <ol>
          <li>Send the value where it is due. Confirm the response is a `200`.</li>
          <li>Webhooks received: none, because the response carries the failure.</li>
          <li>Status changes: none. The product stays `in_progress`.</li>
        </ol>
      </td>
    </tr>

    <tr>
      <td>23</td>
      <td>Bank account: the bank declined without a reason Coming soon</td>
      <td>`2100000031`</td>
      <td>`verification.status`: `rejected`\
      `verification.error_code`: `bank_not_verified`\
      At: `bank_accounts.settlements_primary`\
      Due again: `bank_accounts.settlements_primary`, `create_upi_link`\
      Composite requirement: `bank_account`</td>

      <td>
        <ol>
          <li>Send the value where it is due. Confirm the response is a `200`.</li>
          <li>Webhooks received: none, because the response carries the failure.</li>
          <li>Status changes: none. The product stays `in_progress`.</li>
        </ol>
      </td>
    </tr>
  </tbody>
</table>

**Website**

The website check runs after the response, so the failure shows on the next fetch. Send the website again, or another one.

The table below lists the website scenario:

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

    <col width="17%" />

    <col width="16%" />

    <col width="25%" />

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

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

  <tbody>
    <tr>
      <td>24</td>
      <td>Website: the check fails a few seconds after the response Coming soon</td>
      <td>`https://www.kc-not-found.com`</td>
      <td>`verification.status`: `rejected`\
      `verification.error_code`: `website_unreachable`\
      At: `…website.primary`\
      Due again: `…website.primary`</td>

      <td>
        <ol>
          <li>Send the website where it is due, and fetch the account after 5 sec.</li>
          <li>Webhooks received: `account.requirements.updated`.</li>
          <li>Status changes: none. The product stays `in_progress`.</li>
        </ol>
      </td>
    </tr>
  </tbody>
</table>

**Video KYC**

The call did not verify the person. The action is due again, so let the sub-merchant start a new call.

The table below lists the video KYC scenario:

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

    <col width="17%" />

    <col width="16%" />

    <col width="25%" />

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

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

  <tbody>
    <tr>
      <td>25</td>
      <td>Video KYC not approved (also on every business type) Coming soon</td>
      <td>The hosted page's **Unable to verify**, or **Rejected**</td>
      <td>Still due: `create_video_kyc_link`\
      `requirement_type`: `action`</td>

      <td>
        <ol>
          <li>Submit a test business without a CKYC record, run `create_video_kyc_link` and open the `url`.</li>
          <li>Pick **Unable to verify**.</li>
          <li>Fetch the account. Confirm `create_video_kyc_link` is still due, and run it again for a new call.</li>
          <li>Pick **Rejected** on a new link instead. Confirm the product ends `rejected`.</li>
          <li>Webhooks received: none for **Unable to verify**, because the requirements do not change. For **Rejected**, `account.product.under_review` then `account.product.rejected`.</li>
          <li>Status changes: the product stays `edd_pending`, or moves `under_review` → `rejected`.</li>
        </ol>
      </td>
    </tr>
  </tbody>
</table>

**Request Errors**

The request itself was wrong, so nothing was saved and no webhook fires. Fix it in code, because retrying it unchanged fails again.

The table below lists the request error scenarios:

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

    <col width="17%" />

    <col width="16%" />

    <col width="25%" />

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

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

  <tbody>
    <tr>
      <td>26</td>
      <td>An ownership over 100 Coming soon</td>
      <td>`percentage_ownership: 120`</td>
      <td>HTTP `400`\
      `error.reason`: `invalid_format`\
      `error.field`: `business_profile.stakeholders.<id>.percentage_ownership`</td>

      <td>
        <ol>
          <li>Send the update.</li>
          <li>Confirm `400`, and that nothing was saved.</li>
          <li>Webhooks received: none.</li>
          <li>Status changes: none.</li>
        </ol>
      </td>
    </tr>
  </tbody>
</table>

Every failure code, with its test value, is in the [Error Index](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/error-index.md).

### 3.4 Review, Links and After Activation

A reviewer, a hosted link or a later change decides these outcomes. A test value or a hosted test page forces each one.

The table below lists the scenarios that a review, a link or a later change decides:

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

    <col width="20%" />

    <col width="20%" />

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

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

  <tbody>
    <tr>
      <td>27</td>
      <td>Needs clarification (also on every business type) Coming soon</td>
      <td>Settlement account `000000000003`</td>

      <td>
        <ol>
          <li>Run scenario 1 with this settlement account, and submit.</li>
          <li>Fetch the account after 5 sec. Confirm `needs_clarification`, with only `bank_account` due.</li>
          <li>Answer the point. When `submit_clarification` is due, send `submit_clarification: true` in its own call. See [Needs Clarification](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/needs-clarification.md).</li>
          <li>Webhooks received: `account.requirements.updated` (as the website check settles), `account.product.under_review`, `account.product.needs_clarification`, `account.product.under_review`, `account.product.activated`.</li>
          <li>Status changes: `under_review` → `needs_clarification` → `under_review` → `activated`.</li>
        </ol>
      </td>
    </tr>

    <tr>
      <td>28</td>
      <td>Held in review (also on every business type) Coming soon</td>
      <td>Settlement account `000000000005`</td>

      <td>
        <ol>
          <li>Send the account. Confirm its `verification` is `deferred` and `bank_account` clears.</li>
          <li>Submit. Confirm the response is `under_review`.</li>
          <li>Confirm it stays `under_review` for 5 min, then becomes `activated`.</li>
          <li>Assert that no timeout in your code moves the sub-merchant to a failure state.</li>
          <li>Webhooks received: `account.requirements.updated` (as the website check settles), `account.product.under_review`, `account.product.activated`.</li>
          <li>Status changes: `under_review` → `activated`.</li>
        </ol>
      </td>
    </tr>

    <tr>
      <td>29</td>
      <td>Suspended after activation (also on every business type) Coming soon</td>
      <td>Settlement account `000000000006`</td>

      <td>
        <ol>
          <li>Run scenario 1 with this settlement account. Confirm the response is `activated`.</li>
          <li>About 60 sec later, confirm `suspended`, with `status_reason.code: website_review_failed` and the website due again.</li>
          <li>Stop payments, show the reason and ask for what is listed.</li>
          <li>Send `https://curlec.com`. Confirm the product is `activated` again.</li>
          <li>Webhooks received: `account.requirements.updated` (as the website check settles), `account.product.activated`, `account.product.suspended`. After the website, `account.requirements.updated` and `account.product.activated`.</li>
          <li>Status changes: `activated` → `suspended` → `activated`.</li>
        </ol>
      </td>
    </tr>

    <tr>
      <td>30</td>
      <td>A link expires before the sub-merchant finishes it (also on every business type) Coming soon</td>
      <td>The hosted page's **Expire the link**</td>

      <td>
        <ol>
          <li>Run any link action (video KYC, DigiLocker or ₹1 UPI) and open its `url`.</li>
          <li>Pick **Expire the link**.</li>
          <li>Fetch the account. Confirm the action is still due.</li>
          <li>Show a fresh **Start again** that runs the action again for a new link. Never reuse an expired `url`.</li>
          <li>Webhooks received: none, because the requirements do not change.</li>
          <li>Status changes: none.</li>
        </ol>
      </td>
    </tr>

    <tr>
      <td>31</td>
      <td>DigiLocker for the proof of address Coming soon</td>
      <td>The hosted page's **Share Aadhaar**, then **Decline**</td>

      <td>
        <ol>
          <li>With `proof_of_address_for_individual` due, run `create_aadhaar_digilocker_link` with your `return_url`. Open the `url` in its response.</li>
          <li>Pick **Share Aadhaar**. Confirm `proof_of_address_for_individual` clears and the page returns to your `return_url`.</li>
          <li>On another account, pick **Decline**. Confirm `proof_of_address_for_individual` stays due, with the action and the document uploads.</li>
          <li>Run the action again, or upload a document.</li>
          <li>Webhooks received: `account.requirements.updated` when the Aadhaar is shared. None after **Decline**.</li>
          <li>Status changes: none.</li>
        </ol>
      </td>
    </tr>

    <tr>
      <td>32</td>
      <td>₹1 UPI check of the bank account (also on every business type) Coming soon</td>
      <td>The hosted page's **Pay ₹1**, then **Pay from another person's account**</td>

      <td>
        <ol>
          <li>With `bank_account` due after a failed bank check, run `create_upi_link`. Open the `url` in its response.</li>
          <li>Pick **Pay ₹1**. Confirm `bank_account` clears and the account is `verified`.</li>
          <li>On another account, pick **Pay from another person's account**. Confirm `bank_account` stays due.</li>
          <li>Run the action again, or send the account.</li>
          <li>Webhooks received: `account.requirements.updated` when the payment verifies the account. None after a failed payment.</li>
          <li>Status changes: none.</li>
        </ol>
      </td>
    </tr>

    <tr>
      <td>33</td>
      <td>Access withdrawn (also on every business type) Coming soon</td>
      <td>Settlement account `000000000007`</td>

      <td>
        <ol>
          <li>Run scenario 1 with this settlement account.</li>
          <li>About 60 sec after activation, confirm `account.consent.withdrawn` arrives.</li>
          <li>Stop calling the API for the account. Confirm later calls return `403 consent_withdrawn`.</li>
          <li>Webhooks received: `account.requirements.updated` (as the website check settles), `account.product.activated`, `account.consent.withdrawn`.</li>
          <li>Status changes: none after `activated`.</li>
        </ol>
      </td>
    </tr>
  </tbody>
</table>

## 4. Common Integration Gaps

These mistakes most often stall an onboarding or leave an account in the wrong state after go-live. **Test with** points to the scenario that proves you handled each one.

**Requirements and Values**

The table below lists gaps in handling requirements and values:

| Gap | What goes wrong in production | What to do | Test with |
| - | - | - | - |
| Mixing test businesses | The bank or GSTIN name match fails. It looks like a bug. | Use one test business per account. | Scenario 1 |
| A fixed form per business type | A requirement added after a failed check or review never reaches the sub-merchant. | Render `requirements` as returned, after every response. | Scenario 2 |
| Alternatives shown as separate questions | The sub-merchant pays ₹1 and also re-enters the account, or gives up. | Show the sub-requirements of a `one_of` composite as one choice. | Scenario 16 |

**Status and Webhooks**

The table below lists gaps in handling status and webhooks:

| Gap | What goes wrong in production | What to do | Test with |
| - | - | - | - |
| No path for video KYC | Sub-merchants without a CKYC record never activate. | Show the link when `create_video_kyc_link` is due, and keep it one tap away until it clears. | Scenario 8 |
| Treating `under_review` as final | You tell the sub-merchant they are live, or stuck, before the outcome arrives. | Act on the product `status` from the webhook or a fetch. | Scenario 28 |

**Error Handling and Messaging**

The table below lists gaps in error handling and messaging:

| Gap | What goes wrong in production | What to do | Test with |
| - | - | - | - |
| A failed check treated as an error | You discard a `200`, and the sub-merchant sees a generic failure. | Treat a failed check as data. Branch on the element's `verification.error_code` and show the requirement's `description`. | Scenario 16 |
| Matching on description text | A wording change breaks your handling. | Branch on `verification.error_code` and `error.reason`. | Scenario 18 |

## 5. Best Integration Practices

These practices apply to every onboarding integration. **On this page** says what each one means here. **Test it** points to the scenario that tests it.

The table below lists the best integration practices:

| Topic | What to know | On this page | Test it | Read more |
| - | - | - | - | - |
| Requirements per business type | The business type decides every other requirement, and it locks once the PAN verifies. | Send a signatory with a CKYC record and fetch the record. No proof of address is then due for the signatory, unless `skip_ckyc` is sent. | Scenario 1 | [Fetch an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/fetch-account.md) |
| Actions, then values | A requirement with `requirement_type: action` names an action to run. Its response lists what is due next, such as a code to send or a link the sub-merchant completes. | The CKYC code, video KYC and the ₹1 UPI link all come as actions. | Scenario 1 | [Actions](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/actions.md) |
| Composite requirements | A `composite` requirement answers one point with its `sub_requirements`, combined as its `fulfillment_criteria` says. Under `one_of`, any one clears it. Under `any_of`, at least one clears it. Under `all_of`, you need every one. Its `requirement_code` is a documented point, such as `bank_account`. | PAN, CKYC, bank and proof of address are `one_of`. The terms, the bank account details, an address and a 2-sided document are `all_of`. A proprietorship's proof of business is `all_of` a document and a number. | Scenario 16 | [Requirement Entity](https://razorpay.com/docs/api/partners/accounts/requirement-entity.md) |
| Fetch as a fallback | Webhooks can be late or out of order. Fetch the account before anything irreversible. | Poll with a timeout in tests. | Scenario 9 | [Webhooks](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/webhooks.md) |

### Related Information

* [Test Your Integration](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration)
* [Individual](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/individual.md)
* [Proprietorship](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/proprietorship.md)
* [Public Limited](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/public-limited.md)
* [Other Business Types](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/other-business-types.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)
* [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)
* [Terms and Submission](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/terms-and-submission.md)
