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 overview: credentials, headers and how simulation works.
- Each API, from Create an Account to Webhooks. Each page shows its complete request and response once, then its scenarios.
- The page for each business type you onboard. Every business-type page follows the same structure.
- 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:- This overview, including Test Credentials and Headers.
- Create an Account.
- Fetch an Account.
- Update an Account.
- Actions.
- Documents.
- Terms and Submission.
- Needs Clarification.
- Webhooks.
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:- On the Partner Dashboard, generate your app’s test key and secret pair. The test key starts with
rzp_test_partner_. - Send every call to
https://api.razorpay.comwith Basic authrzp_test_partner_[CLIENT_ID]:[CLIENT_SECRET]. The test pair puts every call in test mode. - Send
X-Idempotency-Keyon every write (POST,PATCHandDELETE). Use a new Universally Unique Identifier (UUID) per request. - Subscribe a test-mode webhook URL and secret on the Partner Dashboard. Test-mode accounts send their events there, with
mode: test. - 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.
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
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.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:4. Read the Error Object
Every API error returns the same fields. Build your handling onreason 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 itsrequirement_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_progressin the response. It settles a few seconds later. - Outcomes after submission: Most products are
activatedin the submission response. A test value that asks for a review returnsunder_review, and the outcome follows about 5 sec later. A product that needs video KYC returnsedd_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:| # | Scenario | Trigger | What to confirm |
|---|---|---|---|
| 1 | Call with the test pair Coming soon | The test key and secret | Call GET /v1/accounts with the test pair. Confirm HTTP 200 and a list, empty at first. |
| 2 | Wrong or revoked secret Coming soon | Any other secret | Call with the wrong secret. Confirm 401 invalid_credentials and that nothing ran. |
| 3 | Write without an idempotency key Coming soon | PATCH with no X-Idempotency-Key | Send an update without the header. Confirm 400 missing_header with metadata.header: X-Idempotency-Key. |
| 4 | An account that is not yours Coming soon | An account ID another app created, or a made-up one | Call GET /v1/accounts/{account_id}. Confirm 404 not_found. Both cases look the same. |
| 5 | A call from an address not on the allowlist Coming soon | Your app’s test-mode allowlist, and a server outside it | Add 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. |
| 6 | Your app’s overall request limit (Live only) Coming soon | Live traffic only | Back off for Retry-After on 429 rate_limited. |
| 7 | Server error and retry (Live only) Coming soon | Live traffic only | On 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:1. Call With the Test Pair
1. Call With the Test Pair
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.2. Wrong or Revoked Secret
2. Wrong or Revoked Secret
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.4. An Account That Is Not Yours
4. An Account That Is Not Yours
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.5. A Call From an Address Not on the Allowlist
5. A Call From an Address Not on the Allowlist
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:
- Add your test server’s range, and call
GET /v1/accountsfrom it. Confirm HTTP 200. - Call it from a server outside the range, such as a laptop. Confirm
403 ip_not_allowed. - Remove the range when you are done, or keep it to mirror live mode.
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-Keyper 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.reasonand the element’sverification.error_code, not by description text. - The sub-requirements of a
one_ofcomposite 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-Signatureand 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.
- 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
ipanddevice_fingerprint_id. - You keep the
accepted_attime Razorpay returns as the record of the acceptance.
- The KYC details are read-only in your UI while a product is
under_revieworedd_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_linkis due. - The action runs again for a fresh link when the last link expired or the call did not verify.
rejectedis handled: no further changes are offered.suspendedis 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.