Skip to main content
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.
Handy TipsEvery API and behaviour in the API reference 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 to Webhooks. 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 and the Error Index.

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.
  2. Create an Account.
  3. Fetch an Account.
  4. Update an Account.
  5. Actions.
  6. Documents.
  7. Terms and Submission.
  8. Needs Clarification.
  9. Webhooks.
The table below lists the business-type pages to read next for common setups: The Other Business Types 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). Test mode checks the allowlist only once it has an entry. Live mode always checks it.
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: Call Fetch Accounts with the test pair. Replace [CLIENT_ID] with your test client ID and [CLIENT_SECRET] with its secret.
Curl
A new app has no accounts yet, so the response is an empty collection with HTTP 200:
Response

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.
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.
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.
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.
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.
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.
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.
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 and the Individual 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.
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.
After activation, manage the sub-merchant’s payment methods. Know more about 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:
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: The table below lists what to do for each error.source: Know more about error codes.

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

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: 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).

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 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:

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. Start from the request in Credentials and Headers, then change one field at a time. The table below lists what test mode covers for credentials and headers:

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:
#ScenarioTriggerWhat to confirm
1Call with the test pair Coming soonThe test key and secretCall GET /v1/accounts with the test pair. Confirm HTTP 200 and a list, empty at first.
2Wrong or revoked secret Coming soonAny other secretCall with the wrong secret. Confirm 401 invalid_credentials and that nothing ran.
3Write without an idempotency key Coming soonPATCH with no X-Idempotency-KeySend an update without the header. Confirm 400 missing_header with metadata.header: X-Idempotency-Key.
4An account that is not yours Coming soonAn account ID another app created, or a made-up oneCall GET /v1/accounts/{account_id}. Confirm 404 not_found. Both cases look the same.
5A call from an address not on the allowlist Coming soonYour app’s test-mode allowlist, and a server outside itAdd 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.
6Your app’s overall request limit (Live only) Coming soonLive traffic onlyBack off for Retry-After on 429 rate_limited.
7Server error and retry (Live only) Coming soonLive traffic onlyOn HTTP 500, retry with exponential backoff and the same X-Idempotency-Key.

9.3 Scenario Details

The details below expand the scenarios that need more than one step:
Before you begin: Keep the test key and secret ready.How to test: Send the request in 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.
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.
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.
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:

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:

9.6 Errors Any Endpoint Returns

Any operation can return these errors. Every error returns the same object, described in Read the Error Object. The Error Index lists every reason. The table below lists the errors shared by every operation:

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

Create an Account

Test account creation, the one-shot request, idempotency and validation.

Fetch an Account

Test reading requirements, polling for status and listing accounts.

Update an Account

Test sending what is due, failed checks, ordering and locks.

Actions

Test codes, video KYC, DigiLocker and ₹1 UPI links.

Documents

Test uploads, attachments, file checks and document outcomes.

Terms and Submission

Test the terms acceptance and every outcome after submission.

Needs Clarification

Test answering a reviewer’s flagged points and resubmitting.

Webhooks

Test signatures, repeats, missed events and every status event.

Business Type Testing

Individual

Test onboarding an individual without a registered business.

Proprietorship

Test onboarding a sole proprietorship.

Private Limited

Test onboarding a private limited company.

Public Limited

Test onboarding a public limited company.

Other Business Types

Test the Section 8 company, LLP, partnership, trust and the other types.

Reference

Test Values

Every test value and the outcome it forces.

Error Index

Every error reason and verification error code.
Last modified on November 18, 2026