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

# Test Your Integration

> Test your Onboarding APIs integration in Test Mode before you onboard sub-merchants.

Available in
🇮🇳 India

Run the whole onboarding journey in test mode, from account creation to activation, before you onboard a real sub-merchant.

Test mode simulates the registries, banks and reviewers behind each check. Call the same endpoints with the same request bodies. Responses, errors and webhooks have the same shape as in live mode. Only the credentials change.

> [!NOTE]
>
> **Handy Tips**
>
> Every API and behaviour in the [API reference](https://razorpay.com/docs/api/partners/accounts) has test cases in this guide. Force each outcome with a test value or a hosted test page. 2 behaviours depend on live traffic and are marked **Live only**: a server error and your app's overall request limit.

This guide is in 4 parts. Test them in this order:

1. This overview: credentials, headers and how simulation works.
2. Each API, from [Create an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/create-account.md) to [Webhooks](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/webhooks.md). Each page shows its complete request and response once, then its scenarios.
3. The page for each business type you onboard. Every business-type page follows the same structure.
4. The [Test Values](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/test-values.md) and the [Error Index](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/error-index.md).

## Build Your Test Plan

Pick the business types you onboard, then read the matching pages in order. Scenarios are numbered on each page. Quote the page and the scenario number when you raise a support ticket.

Every plan starts with the API pages, in this order:

1. This overview, including [Test Credentials and Headers](#9-test-credentials-and-headers).
2. [Create an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/create-account.md).
3. [Fetch an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/fetch-account.md).
4. [Update an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/update-account.md).
5. [Actions](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/actions.md).
6. [Documents](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/documents.md).
7. [Terms and Submission](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/terms-and-submission.md).
8. [Needs Clarification](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/needs-clarification.md).
9. [Webhooks](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/webhooks.md).

The table below lists the business-type pages to read next for common setups:

| Common setup | Business-type pages to read, in order | Then |
| - | - | - |
| Individuals and proprietorships | [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) | [Test Values](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/test-values.md) and [Error Index](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/error-index.md) |
| Companies only | [Private Limited](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/private-limited.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) for a Section 8 company | [Test Values](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/test-values.md) and [Error Index](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/error-index.md) |
| Every business type | Every page under [Business Type Testing](#business-type-testing) | [Test Values](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/test-values.md) and [Error Index](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/error-index.md) |

The [Other Business Types](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/other-business-types.md) page covers the Section 8 company, Limited Liability Partnership (LLP), partnership, trust, society and Hindu Undivided Family (HUF). It also covers the government, judicial person and local authority types.

## 1. Before You Begin

Set up test mode once, before you run any scenario:

1. On the Partner Dashboard, generate your app's **test** key and secret pair. The test key starts with `rzp_test_partner_`.
2. Send every call to `https://api.razorpay.com` with Basic auth `rzp_test_partner_[CLIENT_ID]:[CLIENT_SECRET]`. The test pair puts every call in test mode.
3. Send `X-Idempotency-Key` on every write (`POST`, `PATCH` and `DELETE`). Use a new Universally Unique Identifier (UUID) per request.
4. Subscribe a test-mode webhook URL and secret on the Partner Dashboard. Test-mode accounts send their events there, with `mode: test`.
5. Add addresses to your app's test-mode Internet Protocol (IP) allowlist only to test the allowlist ([scenario 5](#9-2-test-scenarios)). Test mode checks the allowlist only once it has an entry. Live mode always checks it.

> [!WARNING]
>
> **Watch Out!**
>
> Accounts you create in test mode exist only in test mode. The live key cannot reach a test account. A test account never goes live and never gets live API keys. Re-create the sub-merchant in live mode.

In test mode, nothing reaches a bank, registry or reviewer, and no real money moves. Razorpay sends the sub-merchant no SMS, email or WhatsApp message.

### Credentials and Headers

Every call carries the test pair as Basic auth. `GET /v1/accounts` needs no account yet, so use it to check your setup.

The table below lists the headers to send in test mode:

| Header | Value in test mode | Sent on |
| - | - | - |
| `Authorization` | Basic `rzp_test_partner_[CLIENT_ID]:[CLIENT_SECRET]` | Every call |
| `X-Idempotency-Key` | A new UUID per request, and the same one on a retry | `POST`, `PATCH` and `DELETE` |
| `Content-Type` | `application/json`, or `multipart/form-data` for an upload | Calls with a body |

Call [Fetch Accounts](https://razorpay.com/docs/api/partners/accounts/fetch.md) with the test pair. Replace `[CLIENT_ID]` with your test client ID and `[CLIENT_SECRET]` with its secret.

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

A new app has no accounts yet, so the response is an empty collection with HTTP 200:

```json Response theme={null}
{
  "entity": "collection",
  "count": 0,
  "items": []
}
```

## 2. The Onboarding Flow

Every sub-merchant follows the same steps. Only the values due at step 3 depend on the business type. Each step has tests on one of the pages below.

**1. Create the account**

Your server calls `POST /v1/accounts` with the user, the product and as much KYC as you already hold. Test a valid account creation, every request error and a retry with the same idempotency key. See [Create an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/create-account.md).

**2. Read requirements**

Each product's `requirements` lists what is still needed, in order. Build forms from `requirements`, never from a fixed list. See scenarios 1 and 2 on [Fetch an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/fetch-account.md).

**3. Send what is due**

Call `PATCH /v1/accounts/{account_id}` with the values. Each value comes back with its `verification`. Test verified and rejected checks, a value sent before it is due and read-only keys. See [Update an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/update-account.md).

**4. Run actions**

Run the actions that send the phone, email and Central KYC Records Registry (CKYC) codes. Run the actions that create the video KYC, DigiLocker and ₹1 UPI links. Test codes, links and rate limits. See [Actions](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/actions.md).

**5. Upload documents**

Call `POST /v1/accounts/{account_id}/documents`, then attach the `id` in an update. Test the file checks and the outcomes by file name. See [Documents](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/documents.md).

**6. Accept the terms and submit**

The sub-merchant reads Razorpay's terms of service and accepts in your UI. Send their `ip` and `device_fingerprint_id`. Test a valid acceptance, a missing field and an early submission. See scenarios 1 to 3 on [Terms and Submission](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/terms-and-submission.md).

**7. Read the final status**

Most products are `activated` in the submission response. A review, a deferred check or video KYC decides others a little later. Test `activated`, `edd_pending`, `under_review` and `rejected`. See scenarios 4 to 14 on [Terms and Submission](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/terms-and-submission.md).

**8. Complete video KYC, if due**

Without a CKYC record, the product stays `edd_pending` until a video call. Test the link and the outcome of the call. See scenario 5 on [Terms and Submission](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/terms-and-submission.md) and the [Individual](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/individual.md) page.

**9. Answer a clarification, if asked**

A reviewer flags points. Answer them and resubmit. Test each kind of answer and the locks. See [Needs Clarification](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/needs-clarification.md).

**10. Handle webhooks**

Razorpay sends each move to `under_review`, `edd_pending`, `needs_clarification`, `activated`, `rejected` or `suspended` to your webhook URL. It also sends each requirements change that you did not make. Test the signature, repeats and a missed event. See [Webhooks](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/webhooks.md).

After activation, manage the sub-merchant's payment methods. Know more about [payment methods](https://razorpay.com/docs/partners/aggregators/onboarding-api/product-status.md#7-5-manage-payment-methods).

## 3. How Simulation Works

No real registry, bank or reviewer sits on the other end, so you pick each outcome through the value you send. Names are matched for real. Each test business uses values that belong together: the PAN's name, the bank account holder, the business name, the Goods and Services Tax Identification Number (GSTIN) and the Udyam number.

The table below lists how to pick the outcome of each check:

| Check | Pick the outcome with | Success | A specific failure | Any other value |
| - | - | - | - | - |
| PAN | The PAN | `ABCPD1234A` | `ABCPD1234K` (invalid), `ABCPD1234C` (no record) | Fails like a registry error |
| CKYC code | The PAN decides whether a record exists. Then run `send_ckyc_otp`. | Any 6 digits other than `000000` as `individual_ckyc.otp`, with the `request_id` the action returned as `individual_ckyc.request_id` | `000000` (wrong code), `ABCPD1234X` (record unavailable), `AICPD1234U` (code expired) | Any other 6 digits verify |
| Phone and email codes | The code you send after `send_phone_otp` or `send_email_otp` | `000007` | Any other 6 digits: HTTP 200, and the code stays due | Not applicable |
| Bank account | The account number. The Indian Financial System Code (IFSC) only needs the right format. | `1234567890` with `HDFC0123456` | `2100000011` (name mismatch), `1234567892` (closed) | Fails like a bank error |
| GSTIN, Udyam, Corporate Identification Number (CIN) | The number | The number in the test business | See [Test Values](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/test-values.md) | Fails like a registry error |
| Documents | The file name, without the extension. The content is not read. | `PERSONALPANFRONT.jpg` | `PERSONALPANMISMATCHFRONT.jpg` | Fails |
| Website and category | The website. Its Merchant Category Code (MCC) must match. | `https://curlec.com` with MCC `5732` | `https://www.kc-not-found.com` | Fails a few seconds later |
| Review after submission | The settlement account number (every type), or a business-name suffix (registered types) | Anything else: `activated` in the submission response, or `edd_pending` without a CKYC record | `000000000002` or `_REJECT`: `rejected`. `000000000004` or `_EDD`: `edd_pending`. `000000000003`: `needs_clarification`. | Not applicable |
| Video KYC, DigiLocker, ₹1 UPI | A button on the hosted test page at the link in the action response's `metadata` | **Approved**, **Share Aadhaar**, **Pay ₹1** | **Rejected**, **Unable to verify**, **Decline**, **Pay from another person's account**, **Expire the link** | Not applicable |

> [!WARNING]
>
> **Watch Out!**
>
> Test values are case-sensitive. `PERSONALPANFRONT.jpg` works, but `personalpanfront.jpg` fails as an unknown value. An unlisted PAN, account number or file fails the check as if the registry or bank were down. A typo looks like an outage.

## 4. Read the Error Object

Every API error returns the same fields. Build your handling on `reason` and `field`. Do not match on `description`. It is text for the sub-merchant and can change.

The table below lists the fields of the error object:

| Field | What it tells you | Example |
| - | - | - |
| `error.code` | Error class | `BAD_REQUEST_ERROR`, `SERVER_ERROR` |
| `error.reason` | The specific cause. Branch on this. | `step_not_due` |
| `error.field` | The request key that caused it, as a path | `bank_accounts.settlements_primary` |
| `error.source` | Who has to act | `business` (your request), `verification_provider`, `internal` |
| `error.step` | Where it failed | `validation`, `authentication`, `document_upload` |
| `error.metadata` | What would have worked | `{ "due": ["business_profile.business_type"] }` |
| `error.description` | A sentence to show the sub-merchant | `This detail isn't needed yet.` |

The table below lists what to do for each `error.source`:

| `error.source` | What to do |
| - | - |
| `business` | Your request is wrong. Fix it in code. Retrying the same request fails again. |
| `verification_provider` | A registry, bank or SMS provider did not answer (503). Nothing ran. Retry after `Retry-After`. |
| `internal` | A problem at Razorpay (500). Retry with the same `X-Idempotency-Key`. The request does not act twice. |

Know more about [error codes](https://razorpay.com/docs/api/partners/accounts/errors.md).

## 5. Read a Requirement

A requirement carries only the keys its `requirement_type` uses. A composite requirement holds the ways to answer one point in `sub_requirements`. Combine them as its `fulfillment_criteria` says. Build your form from requirements, never from a fixed list.

The table below lists the fields of a requirement:

| Field | What it tells you | Example |
| - | - | - |
| `id` | The unique ID of this requirement, prefixed `req_`. | `req_4Z9yuuKZQXabvX` |
| `requirement_code` | The requirement's code, from a closed list. For an action, the action's name. | `individual_pan`, `ckyc_fetch`, `send_ckyc_otp` |
| `requirement_level` | `mandatory`: needed to submit. `optional`: not needed. `conditional`: needed only in the case its description states, or one of the choices under a `one_of`. | `mandatory` |
| `requirement_type` | `input`: send a value at `field_path`. `action`: run the action named in `requirement_code`. `composite`: answer its `sub_requirements` as its `fulfillment_criteria` says. | `composite` |
| `description` | A sentence to show the sub-merchant. Do not branch on it. | `The person's PAN: the number, or the PAN card.` |
| `requirement_reason` | Why the requirement was raised, when a failed check or a review raised it. | `The name on the bank account does not match the business name.` |
| `field_path` | An input only. Where to send the value in an update. | `business_profile.authorized_person.identity_numbers.individual_pan` |
| `value_type` | An input only. `text`, `enum` (one of `options`), `multi_select` (any of `options`), `boolean` or `document`. | `document` |
| `response` | What was submitted for the requirement: `text` for a text input, or `documents` for a document input. | `{ "text": "Acme Corp" }` |
| `options` | An `enum` or `multi_select` input only. The choices, each a `label` and a `value`. | `[{ "label": "Individual (unregistered)", "value": "individual" }]` |
| `fulfillment_criteria` | A composite only. `one_of`: answer any one sub-requirement. `any_of`: answer at least one. `all_of`: answer every one. | `one_of` |
| `sub_requirements` | A composite only. Its sub-requirements, each a requirement with these same keys. | `[{ "requirement_code": "individual_pan_number" }]` |
| `status` | Where the requirement stands, such as `created` once raised or `resolved` once satisfied. Know more about [requirement status](https://razorpay.com/docs/api/partners/accounts/requirement-entity.md). | `created` |
| `due_at` | The deadline to fulfil the requirement, as a Unix timestamp in seconds. Present only when the requirement has a deadline. | `1796063399` |
| `metadata` | Optional, on any requirement. Free-form key-value pairs that carry more context or configuration, such as what an action needs on an action requirement. The link an action mints is in the action's own response. | None in these samples |

A sub-requirement of a `one_of` is `conditional`, one choice among several. A sub-requirement of an `all_of` is `mandatory`, or `optional`, such as the second line of an address. A requirement drops out of the list once it is met. A composite drops out once it is complete. A composite left with 1 sub-requirement is shown as that sub-requirement, at the composite's level.

Know more about [requirements](https://razorpay.com/docs/partners/aggregators/onboarding-api/collect-requirements.md).

## 6. API Errors and Failed Checks

A request fails in one of 2 ways. The table below lists how API errors and failed checks differ:

| | API errors | Failed checks |
| - | - | - |
| When | The request itself is wrong: a bad format, a missing header or a value that is not due | The request was fine, but the registry or bank said no |
| You see | HTTP 4xx or 5xx with an error object. Nothing is saved, except that a `step_not_due` keeps the values before it in the body (scenario 11 on [Update an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/update-account.md)). | HTTP 200. The element's `verification.status` is `rejected` with an `error_code`, and its requirement is due again. |
| What to do | Fix your code | Ask the sub-merchant for a corrected value. Show the requirement's `description`. |
| How to trigger | Send a bad request. See [Error Index](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/error-index.md). | Send a failure value. See [Test Values](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/test-values.md). |

A check can also end `deferred`. It could not conclude, so a reviewer decides after submission. Its requirement clears and `error_code` is `null`. Submission then holds the product in `under_review` until the review ends. Test it with settlement account `000000000005` (scenario 11 on [Terms and Submission](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/terms-and-submission.md)).

## 7. Status Changes and Webhooks

Status changes and webhooks behave as follows:

* **Webhooks:** Razorpay sends them in test mode to your test-mode subscription, with `mode: test`, signed with your test-mode webhook secret. See [Webhooks](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/webhooks.md) for the test cases.
* **Checks that run later:** A check that runs after the response, such as the website check, is `in_progress` in the response. It settles a few seconds later.
* **Outcomes after submission:** Most products are `activated` in the submission response. A test value that asks for a review returns `under_review`, and the outcome follows about 5 sec later. A product that needs video KYC returns `edd_pending`.
* **Polling:** Poll with a timeout instead of asserting straight after the call. Otherwise, automated tests turn flaky.
* **Live mode:** A review can take days. Handle the webhook, and fetch when it is late.
* **Source of truth:** When your records and the API disagree, the API is the source of truth.

## 8. Where Each Scenario Runs

Every scenario carries a label. The API and its contract are the same in both modes. The label says where to run the scenario.

The table below lists the labels:

| Label | Meaning | What you do |
| - | - | - |
| Available | Runs in test mode, with a test value or a hosted test page | Test it here |
| Live only | Depends on live traffic, so test mode cannot produce it. This applies to a server error and your app's overall request limit. | Build the handling from the scenario, and watch for it in live traffic |

## 9. Test Credentials and Headers

Every call carries the test pair, and every write carries an idempotency key. Test these once, on any endpoint.

### 9.1 Test Mode Coverage

Test these with the test pair. No special credentials exist. The outcome depends on the values you send, from the [Test Values](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/test-values.md). Start from the request in [Credentials and Headers](#credentials-and-headers), then change one field at a time.

The table below lists what test mode covers for credentials and headers:

| Area | What to test | In test mode | How it works in test mode |
| - | - | - | - |
| Credentials | The pair, and a wrong or revoked secret | Available | The same check as live mode, against your app's test pair. |
| Account mapping | An account your app did not create | Available | Accounts map to the app that created them, in each mode separately. The live pair never sees a test account. |
| IP allowlist | A call from an address that is not listed | Available | Checked once your app's test-mode allowlist has an entry. In live mode, every call from an address outside the allowlist is refused. |
| Your app's request limit | `429 rate_limited` on any call | Live only | Depends on your live traffic, so test mode does not produce it. Test the per-action code limit with scenario 8 on [Actions](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/actions.md). |
| Server errors | `500 internal_error` | Live only | Test mode cannot produce a real server error. Build the retry from the scenario. |

### 9.2 Test Scenarios

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

The table below lists 7 scenarios, all 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>Call with the test pair Coming soon</td><td>The test key and secret</td><td>Call `GET /v1/accounts` with the test pair. Confirm HTTP 200 and a list, empty at first.</td></tr>
    <tr><td>2</td><td>Wrong or revoked secret Coming soon</td><td>Any other secret</td><td>Call with the wrong secret. Confirm `401 invalid_credentials` and that nothing ran.</td></tr>
    <tr><td>3</td><td>Write without an idempotency key Coming soon</td><td>`PATCH` with no `X-Idempotency-Key`</td><td>Send an update without the header. Confirm `400 missing_header` with `metadata.header: X-Idempotency-Key`.</td></tr>
    <tr><td>4</td><td>An account that is not yours Coming soon</td><td>An account ID another app created, or a made-up one</td><td>Call `GET /v1/accounts/{account_id}`. Confirm `404 not_found`. Both cases look the same.</td></tr>
    <tr><td>5</td><td>A call from an address not on the allowlist Coming soon</td><td>Your app's test-mode allowlist, and a server outside it</td><td>Add 1 range to your app's test-mode allowlist on the Partner Dashboard. Call with the test pair from a server outside it. Confirm `403 ip_not_allowed` and that nothing ran.</td></tr>
    <tr><td>6</td><td>Your app's overall request limit (Live only) Coming soon</td><td>Live traffic only</td><td>Back off for `Retry-After` on `429 rate_limited`.</td></tr>
    <tr><td>7</td><td>Server error and retry (Live only) Coming soon</td><td>Live traffic only</td><td>On HTTP 500, retry with exponential backoff and the same `X-Idempotency-Key`.</td></tr>
  </tbody>
</table>

### 9.3 Scenario Details

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

> [accordion] 1. Call With the Test Pair
>
> **Before you begin:** Keep the test key and secret ready.
>
> **How to test:** Send the request in [Credentials and Headers](#credentials-and-headers).
>
> **Expected result:** HTTP 200 with `entity: collection`, `count` and `items`. A new app has none.
>
> **Your integration should:** Store the pair in your secrets manager and keep the test and live pairs apart. Send the mode that matches the key.

> [accordion] 2. Wrong or Revoked Secret
>
> **How to test:** Call with any other secret.
>
> **Expected result:** HTTP 401 with `reason: invalid_credentials`. Nothing ran.
>
> **Your integration should:** Alert on HTTP 401. It is a setup problem, not something to retry.

> [accordion] 4. An Account That Is Not Yours
>
> **How to test:** Fetch `acc_DoesNotExist01`, or an account another platform created.
>
> **Expected result:** HTTP 404 with `reason: not_found` and `field: account_id`, the same for both.
>
> **Your integration should:** Treat a 404 on an account you stored as a mapping problem. Check that you are in the right mode.

> [accordion] 5. A Call From an Address Not on the Allowlist
>
> **Before you begin:** Open your app's test-mode allowlist on the Partner Dashboard: **your app → IP allowlist → Test mode**. Test mode checks the allowlist only once it has an entry. Live mode always checks it.
>
> **How to test:**
>
> 1. Add your test server's range, and call `GET /v1/accounts` from it. Confirm HTTP 200.
> 2. Call it from a server outside the range, such as a laptop. Confirm `403 ip_not_allowed`.
> 3. Remove the range when you are done, or keep it to mirror live mode.
>
> **Your integration should:** Allowlist every egress IP your live servers use, including Network Address Translation (NAT) gateways and failover regions. Update the allowlist before you move servers. Treat `403 ip_not_allowed` as a setup alert, not a retry.

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

The table below lists the credential and allowlist gaps:

| Gap | What goes wrong in production | What to do | Test with |
| - | - | - | - |
| Live servers missing from the allowlist | A new server or a changed egress IP gets HTTP 403 on every live call. | Update the allowlist before you change servers or NAT. | #5 |
| A new idempotency key on a retry | An account creation times out. The retry, with a new key, creates a second account. | Keep the key with the request and reuse it on a retry. | #3, and #3 on [Create an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/create-account.md) |
| Retrying 4xx | The same bad request fails forever and fills your logs. | Fix 4xx errors. Retry only 429, 500 and 503, with backoff. | #2, #7 |

### 9.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 credentials and headers:

| Topic | What to know | On this page | Test it | Read more |
| - | - | - | - | - |
| Idempotency | Every write takes `X-Idempotency-Key`. The same key within 24 h returns the first response. The same key with a different body returns `400 idempotency_key_reused`. | Send it on every `POST`, `PATCH` and `DELETE`. | #3 and #4 on [Create an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/create-account.md) | [Create an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/create-account.md) |
| Secrets | Rotate the secret from the Partner Dashboard. The old secret keeps working for its rotation window. | Rotate the test secret once to prove the flow. | #2 | Not applicable |
| One host | Live and test share `https://api.razorpay.com`. The pair decides the mode. | Do not switch hosts per mode. | #1 | [Before You Begin](#1-before-you-begin) |

### 9.6 Errors Any Endpoint Returns

Any operation can return these errors. Every error returns the same object, described in [Read the Error Object](#4-read-the-error-object). The [Error Index](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/error-index.md) lists every reason.

The table below lists the errors shared by every operation:

| Trigger | HTTP | `error.reason` | `error.field` | In test mode |
| - | - | - | - | - |
| Wrong secret, or no Basic auth | 401 | `invalid_credentials` | Not applicable | Available |
| `X-Idempotency-Key` missing on a write | 400 | `missing_header` | Not applicable | Available |
| A test pair from an app whose Onboarding APIs are switched off for test mode on the Partner Dashboard | 403 | `onboarding_not_enabled` | Not applicable | Available |
| A call from an IP outside the app's allowlist | 403 | `ip_not_allowed` | Not applicable | Available |
| Any call after the sub-merchant withdrew your access (scenario 10 on [Webhooks](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/webhooks.md)) | 403 | `consent_withdrawn` | Not applicable | Available |
| An account the app did not create | 404 | `not_found` | `account_id` | Available |
| The same key with a different body | 400 | `idempotency_key_reused` | Not applicable | Available |
| The same key while the first request is still running | 409 | `idempotency_in_progress` | Not applicable | Available |
| More requests than your app's overall limit | 429 | `rate_limited` | Not applicable | Live only |
| A problem at Razorpay | 500 | `internal_error` | Not applicable | Live only |

## 10. Go-Live Checklist

Work through this checklist before you onboard live sub-merchants.

**Every integration**

* Every scenario in your test plan passes. This covers the API pages and every scenario group on each business-type page.
* Live credentials (`rzp_live_partner_`) are in place, and the IPs of your live servers are on the app's allowlist.
* Every write sends a new `X-Idempotency-Key` per request, and the same key on a retry.
* Forms come from `requirements`, not from a fixed list per business type.
* Failures are handled by `error.reason` and the element's `verification.error_code`, not by description text.
* The sub-requirements of a `one_of` composite are offered as one choice.
* Actions run only when a requirement names one. The link an action returns is shown to the sub-merchant and left to clear by itself.
* The webhook endpoint verifies `X-Razorpay-Signature` and processes each event once. A fetch catches up when a webhook is late.
* Identity numbers, bank account numbers and document links come back in full. You show them only to the sub-merchant.
* You delete what you collected once Razorpay has it, as your agreement sets. A fetch shows those values again.

**Terms and submission**

* The sub-merchant sees Razorpay's terms of service, unchanged, before accepting.
* You send the acceptance only after the sub-merchant accepts in your UI, with their own `ip` and `device_fingerprint_id`.
* You keep the `accepted_at` time Razorpay returns as the record of the acceptance.

**After submission**

* The KYC details are read-only in your UI while a product is `under_review` or `edd_pending`, and after activation.
* After activation, only the details in [Account Management](https://razorpay.com/docs/partners/aggregators/onboarding-api/account-management.md) can change, each after a manual review.
* The video KYC link shows inside your product when `create_video_kyc_link` is due.
* The action runs again for a fresh link when the last link expired or the call did not verify.
* `rejected` is handled: no further changes are offered.
* `suspended` is handled: payments stop, and the sub-merchant answers what its requirements list.

## API Testing

> [card] [Create an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/create-account.md)
>
> Test account creation, the one-shot request, idempotency and validation.

> [card] [Fetch an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/fetch-account.md)
>
> Test reading requirements, polling for status and listing accounts.

> [card] [Update an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/update-account.md)
>
> Test sending what is due, failed checks, ordering and locks.

> [card] [Actions](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/actions.md)
>
> Test codes, video KYC, DigiLocker and ₹1 UPI links.

> [card] [Documents](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/documents.md)
>
> Test uploads, attachments, file checks and document outcomes.

> [card] [Terms and Submission](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/terms-and-submission.md)
>
> Test the terms acceptance and every outcome after submission.

> [card] [Needs Clarification](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/needs-clarification.md)
>
> Test answering a reviewer's flagged points and resubmitting.

> [card] [Webhooks](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/webhooks.md)
>
> Test signatures, repeats, missed events and every status event.

## Business Type Testing

> [card] [Individual](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/individual.md)
>
> Test onboarding an individual without a registered business.

> [card] [Proprietorship](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/proprietorship.md)
>
> Test onboarding a sole proprietorship.

> [card] [Private Limited](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/private-limited.md)
>
> Test onboarding a private limited company.

> [card] [Public Limited](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/public-limited.md)
>
> Test onboarding a public limited company.

> [card] [Other Business Types](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/other-business-types.md)
>
> Test the Section 8 company, LLP, partnership, trust and the other types.

## Reference

> [card] [Test Values](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/test-values.md)
>
> Every test value and the outcome it forces.

> [card] [Error Index](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/error-index.md)
>
> Every error reason and verification error code.

### Related Information

* [Onboarding APIs](https://razorpay.com/docs/partners/aggregators/onboarding-api)
* [Accounts API Reference](https://razorpay.com/docs/api/partners/accounts)
* [Onboarding APIs Webhook Events](https://razorpay.com/docs/webhooks/partners/onboarding-apis.md)
* [Error Codes](https://razorpay.com/docs/partners/aggregators/onboarding-api/error-codes.md)
