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

# Create Account Tests

> Test account creation on Onboarding APIs in Test Mode, including one-shot, idempotency and validation scenarios.

Available in
🇮🇳 India

Create a sub-merchant's account and its products in test mode, and check every validation and idempotency path before you go live.

`POST /v1/accounts` creates the sub-merchant's account. With `products`, it also requests each product listed. Send `country` and the `user` at minimum, and any KYC you already hold. Values that fail a check are still saved. The response shows their `verification`, and `requirements` lists what is left.

Start with the [overview](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration) for test credentials and headers.

## 1. Test Mode Coverage

### Test Mode Differences

The table below lists how account creation behaves in each mode:

| Behaviour | Live mode | Test mode |
| - | - | - |
| The account | Razorpay creates the sub-merchant's account, which goes live once its product is activated. | Razorpay creates a test account that exists only in test mode and can never go live. |
| Checks at creation | Registries and banks check each value. | The value decides each outcome, from the [Test Values](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/test-values.md). Names are matched for real. |
| Codes for the user's contacts | The user receives real codes after `send_phone_otp` and `send_email_otp`. | No SMS or email is sent. The code `000007` verifies. |
| Request validation and idempotency | Razorpay validates every request and remembers an idempotency key for 24 h. | The same as live mode. |
| Document links | Razorpay downloads the link once and keeps its own copy. | The same as live mode. |

### What You Can Test

The table below lists the areas to test on this endpoint:

| Area | What to test | In test mode |
| - | - | - |
| Create with the user | The account, the product and the first requirements | Available |
| Create with KYC (one-shot) | Every value checked in one call | Available |
| Codes for the user's contacts | `send_phone_otp` and `send_email_otp` due at creation | Available |
| Request validation | Every `invalid_request`, `invalid_format` and `invalid_option` | Available |
| Idempotency | A retry with the same key, and a key reused with a different body | Available |
| Document links at account creation | `url` documents, and links that cannot be fetched | Available |
| Business types | All 13, each end to end, with the test businesses on its page | Available |

### Endpoint Coverage in Test Mode

The table below lists the endpoints this page uses:

| API | Endpoint | Available in test mode |
| - | - | - |
| [Create an Account](https://razorpay.com/docs/api/partners/accounts/create.md) | `POST /v1/accounts` | Available |
| [Fetch Accounts](https://razorpay.com/docs/api/partners/accounts/fetch.md) | `GET /v1/accounts` | Available |

## 2. Before You Begin

Prepare the following before you run the scenarios:

* Pass the credential and header scenarios on the [overview](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration).
* Pick 1 test business per account. Values from different test businesses fail the name match.
* Generate a new `X-Idempotency-Key` for each new request, and reuse it on a retry.

### Sample Request

The request below sends everything test business Individual A can send at creation, as a one-shot. The least it takes is `country` and `user`. Every value is checked as if it were sent in an update. The response comes back within 5 sec.

```bash Curl theme={null}
curl -X POST https://api.razorpay.com/v1/accounts \
-u rzp_test_partner_[CLIENT_ID]:[CLIENT_SECRET] \
-H "Content-Type: application/json" \
-H "X-Idempotency-Key: [UNIQUE_KEY]" \
-d '{
  "user": {
    "email": "test.owner@example.com",
    "phone": "+919876543210",
    "name": "Rzp Test QA Merchant"
  },
  "country": "IN",
  "is_mfa_enabled": false,
  "statement_descriptor": {
    "value": "Rzp Test Store"
  },
  "business_profile": {
    "business_type": "individual",
    "authorized_person": {
      "identity_numbers": {
        "individual_pan": {
          "value": "ABCPD1234A"
        }
      },
      "documents": {}
    },
    "business_category": {
      "category": "ecommerce",
      "subcategory": "computers_peripheral_equipment_software",
      "mcc": "5732",
      "business_description": "Payment and billing software, sold online"
    }
  },
  "bank_accounts": {
    "settlements_primary": {
      "account_number": "1234567890",
      "routing_code": "HDFC0123456",
      "routing_code_type": "IFSC"
    }
  },
  "products": {
    "payment_gateway": {
      "payment_channels": {
        "website": {
          "primary": "https://curlec.com"
        }
      }
    }
  },
  "notes": {
    "shop_id": "60291847"
  }
}'
```

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

### Sample Response

The website check is still running when the API answers, so the website is `in_progress`. The PAN and the bank account come back verified.

> [accordion] Response: HTTP 201
>
> ```json Response theme={null}
> {
>   "id": "acc_TcdGEzmfKQzEl1",
>   "country": "IN",
>   "statement_descriptor": {
>     "value": "Rzp Test Store",
>     "verification": {
>       "status": "verified",
>       "verified_at": 1793164800
>     }
>   },
>   "is_mfa_enabled": false,
>   "user": {
>     "role": "owner",
>     "email": "test.owner@example.com",
>     "phone": "+919876543210",
>     "name": "Rzp Test QA Merchant",
>     "is_email_verified": true,
>     "is_phone_verified": true
>   },
>   "business_profile": {
>     "business_type": "individual",
>     "business_name": "Rzp Test QA Merchant",
>     "date_of_establishment": null,
>     "identity_numbers": {},
>     "documents": {},
>     "business_category": {
>       "category": "ecommerce",
>       "subcategory": "computers_peripheral_equipment_software",
>       "mcc": "5732",
>       "business_description": "Payment and billing software, sold online"
>     },
>     "authorized_person": {
>       "name": "Rzp Test QA Merchant",
>       "identity_numbers": {
>         "individual_pan": {
>           "type": "individual_pan",
>           "value": "ABCPD1234A",
>           "verification": {
>             "status": "verified",
>             "error_code": null,
>             "error_description": null,
>             "verified_at": 1793164802,
>             "metadata": {},
>             "created_at": 1793164800
>           },
>           "metadata": {},
>           "is_skipped": false,
>           "created_at": 1793164800,
>           "updated_at": 1793164802
>         }
>       },
>       "documents": {},
>       "address": null,
>       "date_of_birth": null,
>       "additional_data": {},
>       "created_at": 1793164800,
>       "updated_at": 1793164802
>     },
>     "stakeholders": {},
>     "addresses": [],
>     "metadata": {}
>   },
>   "bank_accounts": {
>     "settlements_primary": {
>       "type": "settlements_primary",
>       "account_number": "1234567890",
>       "routing_code": "HDFC0123456",
>       "routing_code_type": "IFSC",
>       "supporting_document": null,
>       "verification": {
>         "status": "verified",
>         "error_code": null,
>         "error_description": null,
>         "verified_at": 1793164803,
>         "metadata": {},
>         "created_at": 1793164801
>       }
>     }
>   },
>   "products": {
>     "payment_gateway": {
>       "type": "payment_gateway",
>       "status": "in_progress",
>       "status_reason": null,
>       "created_at": 1793164800,
>       "updated_at": 1793164803,
>       "requirements": [
>         {
>           "id": "req_hocykxcAkjCdtB",
>           "requirement_code": "ckyc_fetch",
>           "requirement_level": "mandatory",
>           "requirement_type": "composite",
>           "description": "The person's CKYC record, fetched with a code or skipped.",
>           "fulfillment_criteria": "one_of",
>           "sub_requirements": [
>             {
>               "id": "req_2KRiIGIhuAPNW6",
>               "requirement_code": "skip_ckyc",
>               "requirement_level": "conditional",
>               "requirement_type": "input",
>               "description": "Skip CKYC.",
>               "field_path": "business_profile.authorized_person.identity_numbers.individual_ckyc.is_skipped",
>               "value_type": "boolean",
>               "status": "created"
>             },
>             {
>               "id": "req_L3rskP8gX6YVHh",
>               "requirement_code": "send_ckyc_otp",
>               "requirement_level": "conditional",
>               "requirement_type": "action",
>               "description": "A Central KYC record was found for your PAN. Get a code on the mobile on your CKYC record to fetch it.",
>               "status": "created"
>             }
>           ],
>           "status": "created"
>         },
>         {
>           "id": "req_0HAQYzBrDRNnEM",
>           "requirement_code": "accept_terms_of_service",
>           "requirement_level": "mandatory",
>           "requirement_type": "composite",
>           "description": "Show the sub-merchant Razorpay's terms of service and record their acceptance.",
>           "fulfillment_criteria": "all_of",
>           "sub_requirements": [
>             {
>               "id": "req_CTW6xxsQmygIDU",
>               "requirement_code": "acceptance_ip",
>               "requirement_level": "mandatory",
>               "requirement_type": "input",
>               "description": "The IP address the terms were accepted from.",
>               "field_path": "products.payment_gateway.terms_of_service_acceptance.ip",
>               "value_type": "text",
>               "status": "created"
>             },
>             {
>               "id": "req_gXg6igx2STKrZA",
>               "requirement_code": "acceptance_device_fingerprint_id",
>               "requirement_level": "mandatory",
>               "requirement_type": "input",
>               "description": "The device fingerprint of the device the terms were accepted on.",
>               "field_path": "products.payment_gateway.terms_of_service_acceptance.device_fingerprint_id",
>               "value_type": "text",
>               "status": "created"
>             }
>           ],
>           "status": "created"
>         }
>       ],
>       "terms_of_service_acceptance": null,
>       "payment_channels": {
>         "website": {
>           "primary": "https://curlec.com",
>           "additional": [],
>           "verification": {
>             "status": "in_progress",
>             "error_code": null,
>             "error_description": null,
>             "verified_at": null,
>             "metadata": {},
>             "created_at": 1793164803
>           }
>         },
>         "app_android": null,
>         "app_ios": null
>       }
>     }
>   },
>   "notes": {
>     "shop_id": "60291847"
>   },
>   "created_at": 1793164800,
>   "updated_at": 1793164803
> }
> ```

## 3. Test Scenarios

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

### 3.1 Scenarios

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

The table below lists 11 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>Create with the user and the product Coming soon</td><td>An email, phone and name, with `products: { "payment_gateway": { "payment_channels": {} } }`</td><td>Call `POST /v1/accounts`. Confirm HTTP 201, an `id` (`acc_…`) and the product created in `in_progress`. Confirm `business_type`, `send_phone_otp` and `send_email_otp` in `requirements`. Store the `id` against your shop.</td></tr>
    <tr><td>2</td><td>Create everything at once (one-shot) Coming soon</td><td>Individual A in one call</td><td>Send the [sample request](#sample-request). Confirm each value's `verification`. Confirm `requirements` holds only `ckyc_fetch` and `accept_terms_of_service`.</td></tr>
    <tr><td>3</td><td>Retry account creation after a timeout Coming soon</td><td>The same `X-Idempotency-Key` twice</td><td>Create the account. Send it again with the same key and body. Confirm the same `id`, and only 1 account in `GET /v1/accounts`.</td></tr>
    <tr><td>4</td><td>Reuse a key for a different request Coming soon</td><td>The same key with a different body</td><td>Confirm `400 idempotency_key_reused`.</td></tr>
    <tr><td>5</td><td>Required fields missing Coming soon</td><td>No `user`, or no `country`</td><td>Confirm `400 invalid_request` with `field`. Confirm no account was created.</td></tr>
    <tr><td>6</td><td>A key account creation does not take Coming soon</td><td>`"bussiness_profile"`, or a read-only `verification`</td><td>Confirm `400 invalid_request` naming the key.</td></tr>
    <tr><td>7</td><td>A value in the wrong format Coming soon</td><td>PAN `ABC123`, phone `9876543210` (no `+91`) or Indian Financial System Code (IFSC) `HDFC123`</td><td>Send each. Confirm `400 invalid_format` with `field` and `metadata.pattern`. Confirm nothing was created.</td></tr>
    <tr><td>8</td><td>A value that is not an option Coming soon</td><td>`business_type: "company"`, `country: "US"` or a `products` key `"loans"`</td><td>Confirm `400 invalid_option` with `metadata.allowed_values`.</td></tr>
    <tr><td>9</td><td>A well-formed value that fails its check Coming soon</td><td>PAN `ABCPD1234K` in the one-shot</td><td>Create the account. Confirm HTTP 201 and the PAN's `verification.status: rejected` with `error_code: pan_not_found`. Confirm `individual_pan` is due again.</td></tr>
    <tr><td>10</td><td>A document link Razorpay cannot fetch Coming soon</td><td>`url: https://10.0.0.1/a.pdf`, or any `http://` link</td><td>Send it as `business_profile.authorized_person.documents.individual_pan_document`. Confirm `400 invalid_document_url`.</td></tr>
    <tr><td>11</td><td>LLPs, partnerships, trusts and other types Coming soon</td><td>`business_type: "llp"` with the Limited Liability Partnership (LLP) test business</td><td>Create with the type and send what `requirements` lists. Run the journey on [Other Business Types](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/other-business-types.md).</td></tr>
  </tbody>
</table>

### 3.2 Scenario Details

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

> [accordion] 1. Create With the User and the Product
>
> **Before you begin:** Keep the test credentials ready.
>
> **How to test:** Send `country`, `user` (`email`, `phone`, `name`) and `products: { "payment_gateway": { "payment_channels": {} } }` only.
>
> **Expected result:** HTTP 201 with the account. The product is created in `in_progress`. `requirements` lists `business_profile.business_type` with its options, then `send_phone_otp` and `send_email_otp` as actions.
>
> **Your integration should:** Store the `id` with your shop ID. Put your own reference in `notes`, so support finds the account from either side.

> [accordion] 2. Create Everything at Once (One-Shot)
>
> **Before you begin:** Pick 1 test business. Values from different test businesses fail the name match.
>
> **How to test:** Send the [sample request](#sample-request).
>
> **Expected result:** HTTP 201, as in the sample response. The PAN and the bank account come back verified. The website is `in_progress` and settles a few seconds later. `requirements` holds what the request could not send at creation: `ckyc_fetch` and `accept_terms_of_service`, last. The test category asks no business-model questions.
>
> **Your integration should:** Send only what you hold. Then read `requirements` and ask the sub-merchant for the rest, in that order.

> [accordion] 3. Retry Account Creation After a Timeout
>
> **How to test:**
>
> 1. Create the account with `X-Idempotency-Key: 3b9f0c2e-7d41-4a6e-9c15-2f8e1a6d4b70`.
> 2. Send the same request with the same key.
> 3. Send the same key with a different `user.email` (#4).
>
> **Expected result:** The second call returns the first response, with the same `id` and status. The third call returns `400 idempotency_key_reused`.
>
> **Your integration should:** Generate the key once per logical request and keep it with the request. A retry after a timeout then reuses it. Razorpay remembers a key for 24 h.

> [accordion] 7. A Value in the Wrong Format
>
> **How to test:** Send the one-shot with PAN `ABC123`.
>
> **Expected result:** HTTP 400. Nothing is created, because a format error rejects the whole request.
>
> **Your integration should:** Validate formats in your form before calling the API. Map `field` back to the input, so the sub-merchant sees which one is wrong.
>
> **Errors to test:** The table below lists the errors this scenario covers:
>
> | Trigger | HTTP | `error.reason` | `error.field` | `error.description` |
> | - | - | - | - | - |
> | PAN `ABC123` | 400 | `invalid_format` | `business_profile.authorized_person.identity_numbers.individual_pan` | `The PAN must be 10 characters: 5 letters, 4 digits and a letter.` |
> | Phone `9876543210` | 400 | `invalid_format` | `user.phone` | `The phone must be +91 followed by 10 digits.` |
> | IFSC `HDFC123` | 400 | `invalid_format` | `bank_accounts.settlements_primary.routing_code` | `The value isn't in the right format.` |
> | `business_type: "company"` | 400 | `invalid_option` | `business_profile.business_type` | `Choose one of the allowed values.` |
> | No `user` | 400 | `invalid_request` | `user` | `The request is missing a required field.` |

> [accordion] 9. A Well-Formed Value That Fails Its Check
>
> **How to test:** Send the one-shot with PAN `ABCPD1234K`.
>
> **Expected result:** HTTP 201, and the account is created. The PAN's `verification.status` is `rejected` with `error_code: pan_not_found`. The `individual_pan` composite, the number or the PAN card, is due again.
>
> **Your integration should:** Treat a failed check as a 201 or 200. Branch on the element's `verification.error_code` and show the requirement's `description`. Offer every sub-requirement of its `one_of`. See every code in the [Error Index](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/error-index.md).

### 3.3 Errors to Handle

Every error returns the same object. Branch on `error.reason` and `error.field`, because the description can change. The [overview](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration) lists the errors every operation shares.

The table below lists the errors this endpoint returns:

| Trigger | HTTP | `error.reason` | `error.field` |
| - | - | - | - |
| No `user` or no `country`, or a key account creation does not take | 400 | `invalid_request` | The key |
| PAN `ABC123`, phone without `+91` or IFSC `HDFC123` | 400 | `invalid_format` | The path of the value |
| `business_type: "company"` or `country: "US"` | 400 | `invalid_option` | The path of the value |
| A document `url` that is `http://`, private or unreachable | 400 | `invalid_document_url` | The path of the document |
| The same key with a different body | 400 | `idempotency_key_reused` | Not applicable |

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

**Creating accounts**

The table below lists the gaps when creating accounts:

| Gap | What goes wrong in production | What to do | Test with |
| - | - | - | - |
| Duplicate accounts after a timeout | Account creation times out. You retry with a new key, and the shop ends up with 2 accounts. | Reuse the idempotency key, or list by email before creating again. | #3, and #5 on [Fetch an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/fetch-account.md) |
| A fixed form per business type | A requirement that appears after a failed check never reaches the sub-merchant. | Render `requirements` as returned. | #2, #9 |
| Values from different test businesses | The holder of the bank account does not match the PAN's name, and the check fails. | Use 1 test business per account. | #2 |

**Errors and messaging**

The table below lists the gaps in error handling and messaging:

| Gap | What goes wrong in production | What to do | Test with |
| - | - | - | - |
| Format errors shown as a failure of the sub-merchant's KYC | The sub-merchant sees a raw validation message and gives up. | Validate before calling. Map `field` to your input. | #7 |
| Treating a failed check as an error | You discard a 201 because a check failed, and lose the account. | Treat a failed check as data in a successful response. | #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 account creation:

| Topic | What to know | On this page | Test it | Read more |
| - | - | - | - | - |
| Requirements drive the form | Each product's `requirements` is recomputed on every response. Send what is listed. Anything else returns `step_not_due`. | Create returns the first `requirements`. | #2, and #11 on [Update an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/update-account.md) | [Collect Requirements](https://razorpay.com/docs/partners/aggregators/onboarding-api/collect-requirements.md) |
| Identifiers in full | Identity numbers and account numbers come back in full. Registry data such as the account holder's name is not returned. | The sample response has the full PAN and account number. | #8 on [Fetch an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/fetch-account.md) | [Fetch an Account](https://razorpay.com/docs/partners/aggregators/onboarding-api/test-integration/fetch-account.md) |

### Related Information

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