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-Keyfor 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 iscountry and user. Every value is checked as if it were sent in an update. The response comes back within 5 sec.
Curl
Sample Response
The website check is still running when the API answers, so the website isin_progress. The PAN and the bank account come back verified.
Response: HTTP 201
Response: HTTP 201
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:| # | Scenario | Trigger | What to confirm |
|---|---|---|---|
| 1 | Create with the user and the product Coming soon | An 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. |
| 2 | Create everything at once (one-shot) Coming soon | Individual A in one call | Send the sample request. Confirm each value’s verification. Confirm requirements holds only ckyc_fetch and accept_terms_of_service. |
| 3 | Retry account creation after a timeout Coming soon | The same X-Idempotency-Key twice | Create the account. Send it again with the same key and body. Confirm the same id, and only 1 account in GET /v1/accounts. |
| 4 | Reuse a key for a different request Coming soon | The same key with a different body | Confirm 400 idempotency_key_reused. |
| 5 | Required fields missing Coming soon | No user, or no country | Confirm 400 invalid_request with field. Confirm no account was created. |
| 6 | A key account creation does not take Coming soon | "bussiness_profile", or a read-only verification | Confirm 400 invalid_request naming the key. |
| 7 | A value in the wrong format Coming soon | PAN ABC123, phone 9876543210 (no +91) or Indian Financial System Code (IFSC) HDFC123 | Send each. Confirm 400 invalid_format with field and metadata.pattern. Confirm nothing was created. |
| 8 | A value that is not an option Coming soon | business_type: "company", country: "US" or a products key "loans" | Confirm 400 invalid_option with metadata.allowed_values. |
| 9 | A well-formed value that fails its check Coming soon | PAN ABCPD1234K in the one-shot | 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. |
| 10 | A document link Razorpay cannot fetch Coming soon | url: https://10.0.0.1/a.pdf, or any http:// link | Send it as business_profile.authorized_person.documents.individual_pan_document. Confirm 400 invalid_document_url. |
| 11 | LLPs, partnerships, trusts and other types Coming soon | business_type: "llp" with the Limited Liability Partnership (LLP) test business | Create 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:1. Create With the User and the Product
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.2. Create Everything at Once (One-Shot)
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.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.3. Retry Account Creation After a Timeout
3. Retry Account Creation After a Timeout
How to test:
- Create the account with
X-Idempotency-Key: 3b9f0c2e-7d41-4a6e-9c15-2f8e1a6d4b70. - Send the same request with the same key.
- Send the same key with a different
user.email(#4).
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.7. A Value in the Wrong Format
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:9. A Well-Formed Value That Fails Its Check
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.3.3 Errors to Handle
Every error returns the same object. Branch onerror.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: