Skip to main content
Available in🇮🇳 India
Fetch and list sub-merchant accounts in test mode, read their requirements and follow each product’s status before you go live. GET /v1/accounts/{account_id} returns the account, the verification of each element and each product’s status and requirements. Fetch to see the account’s current state at any time. Webhooks tell you when it changes. Start with the overview for test credentials and headers.

1. Test Mode Coverage

Test Mode Differences

The table below lists how fetching and listing behave in each mode:

What You Can Test

The table below lists the areas to test on these endpoints:

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:
  • Create an account, as in scenario 1 on Create an Account.
  • Poll with a timeout in automated tests. Checks and reviews settle a few seconds after the call.

Fetch an Account

The response below is test business Individual A part-way through, sent step by step. The PAN is verified, the Central KYC Records Registry (CKYC) code was requested and the bank check failed on the name. The category, the description, the statement name and the terms are still due.
Curl
Response

List Accounts

List your accounts, newest first, filtered by email, phone, product or time. Use the list to continue a sub-merchant’s account instead of creating another. Filtered by the user’s email, it returns the account above.
Curl
Response
Know more about the response parameters.

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 9 scenarios. 1 is live and 8 are coming soon:
#ScenarioTriggerWhat to confirm
1Fetch the account LiveAn account from scenario 1 on Create an AccountCall GET /v1/accounts/{account_id}. Confirm it matches the account-creation response.
2Read requirements Coming soonThe account in the fetch responseFor each item, read requirement_code, requirement_type and requirement_level. Read an input’s field_path, value_type and options. Read a composite’s fulfillment_criteria and sub_requirements. Render 1 form field per input and 1 button per action. Render a composite’s sub-requirements by its criteria: 1 choice for one_of, at least one for any_of and every one for all_of.
3A check that settles later Coming soonWebsite https://curlec.comSend it, as in scenario 9 on Update an Account. Fetch and confirm in_progress. Fetch after 5 sec and confirm verified. Confirm Razorpay sends account.requirements.updated.
4Follow the product after submission Coming soonSettlement account 000000000002Submit, as on Terms and Submission. Confirm the response is under_review. Poll every 2 sec, up to 60 sec. Confirm rejected after about 5 sec.
5Continue an existing account Coming soonThe user’s emailCall GET /v1/accounts?email=test.owner@example.com. Confirm the account. Continue it instead of creating another.
6Filter errors Coming sooncount=0, count=101, from after to or product=loansConfirm 400 invalid_format, invalid_request and invalid_option.
7Unknown account Coming soonacc_DoesNotExist01Confirm 404 not_found with field: account_id.
8Identifiers come back in full Coming soonAn account with a verified PAN and bank accountConfirm individual_pan.value is ABCPD1234A and the API returns the full account number. Confirm no holder name comes back.
9Requirements change with the checks Coming soonPAN ABCPD7891B (no CKYC record)Send the PAN. Confirm ckyc_fetch is not due, unlike for ABCPD1234A. Confirm proof_of_address_for_individual is due.

3.2 Scenario Details

The details below expand the scenarios that need more than one step:
Before you begin: Use test business Individual A with bank account 2100000011, as in scenario 7 on Update an Account.How to test: Fetch the account, as in the fetch request.Expected result: Each requirement is 1 thing to do. requirement_type says whether to send a value (input), run an action (action) or answer a composite. Answer a composite’s sub_requirements as its fulfillment_criteria says. The response also shows the following:
  • The bank account’s verification is rejected with error_code: bank_name_mismatch.
  • bank_account is due again as a one_of: the account (settlement_bank_account) or the ₹1 UPI link (create_upi_link). Its requirement_reason says the name on the account does not match.
  • settlement_bank_account is an all_of of the account number, the Indian Financial System Code (IFSC) and the routing code type.
  • ckyc_otp and ckyc_request_id are due, because send_ckyc_otp ran.
  • The optional payment_channels composite follows, as a one_of of a website, an Android app or an iOS app.
  • business_category, business_description and statement_descriptor follow. statement_descriptor has value_type: text and field_path: statement_descriptor.value.
  • accept_terms_of_service comes last, as an all_of of the ip and the device_fingerprint_id.
Your integration should: Show the sub-requirements of a one_of composite as 1 choice. Show description. Branch on the element’s verification.error_code.
Before you begin: Get an account ready to submit, with settlement account 000000000002.How to test:
  1. Submit, then fetch straight away.
  2. Poll GET /v1/accounts/{account_id} every 2 sec, up to 60 sec.
Expected result: under_review first. About 5 sec later, rejected. Other test values reach activated, edd_pending or needs_clarification the same way. See Terms and Submission.Webhooks: account.product.under_review, then account.product.rejected.Your integration should: Poll with a timeout in tests. In production, act on the webhook and fetch only when it is late.Live mode differs: A review can take hours or days. under_review can stay until a reviewer acts.
Before you begin: Use an account with a verified PAN and bank account.Expected result: The PAN and the account number come back in full, as in the fetch response. The CKYC record shows value: null, with ckyc_mobile in its metadata. The holder’s name from the bank is not returned. Addresses from registries are not returned. The PAN’s name comes back as business_name.Your integration should: Show these values only to the sub-merchant. Delete what you collected once Razorpay has it, as your agreement sets. Fetch the account to show them again.

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 these endpoints return:

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. Status and requirements The table below lists the gaps in reading status and requirements:

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