Skip to main content
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 for test credentials and headers.

1. Test Mode Coverage

Test Mode Differences

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

What You Can Test

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

Endpoint Coverage in Test Mode

The table below lists the endpoints this page uses:

2. Before You Begin

Prepare the following before you run the scenarios:
  • Pass the credential and header scenarios on the overview.
  • 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.
Curl
Know more about the request parameters.

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

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:
#ScenarioTriggerWhat to confirm
1Create with the user and the product Coming soonAn email, phone and name, with products: { "payment_gateway": { "payment_channels": {} } }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.
2Create everything at once (one-shot) Coming soonIndividual A in one callSend the sample request. Confirm each value’s verification. Confirm requirements holds only ckyc_fetch and accept_terms_of_service.
3Retry account creation after a timeout Coming soonThe same X-Idempotency-Key twiceCreate the account. Send it again with the same key and body. Confirm the same id, and only 1 account in GET /v1/accounts.
4Reuse a key for a different request Coming soonThe same key with a different bodyConfirm 400 idempotency_key_reused.
5Required fields missing Coming soonNo user, or no countryConfirm 400 invalid_request with field. Confirm no account was created.
6A key account creation does not take Coming soon"bussiness_profile", or a read-only verificationConfirm 400 invalid_request naming the key.
7A value in the wrong format Coming soonPAN ABC123, phone 9876543210 (no +91) or Indian Financial System Code (IFSC) HDFC123Send each. Confirm 400 invalid_format with field and metadata.pattern. Confirm nothing was created.
8A value that is not an option Coming soonbusiness_type: "company", country: "US" or a products key "loans"Confirm 400 invalid_option with metadata.allowed_values.
9A well-formed value that fails its check Coming soonPAN ABCPD1234K in the one-shotCreate the account. Confirm HTTP 201 and the PAN’s verification.status: rejected with error_code: pan_not_found. Confirm individual_pan is due again.
10A document link Razorpay cannot fetch Coming soonurl: https://10.0.0.1/a.pdf, or any http:// linkSend it as business_profile.authorized_person.documents.individual_pan_document. Confirm 400 invalid_document_url.
11LLPs, partnerships, trusts and other types Coming soonbusiness_type: "llp" with the Limited Liability Partnership (LLP) test businessCreate with the type and send what requirements lists. Run the journey on Other Business Types.

3.2 Scenario Details

The details below expand the scenarios that need more than one step:
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.
Before you begin: Pick 1 test business. Values from different test businesses fail the name match.How to test: Send the 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.
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.
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:
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.

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 lists the errors every operation shares. The table below lists the errors this endpoint returns:

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: Errors and messaging The table below lists the gaps in error handling and messaging:

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:
Last modified on November 18, 2026