Available in🇮🇳 India
A private limited company onboards with its business PAN and its Corporate Identification Number (CIN) or certificate of incorporation. It also needs an authorised person, its beneficial owners and its addresses. The bank account must be in the company name. The authorised person’s Central KYC Records Registry (CKYC) record decides whether video KYC is due.
Before you start, check that your test credentials and headers work. See Test Your Integration. Every request and response body is on the API test pages, starting with Create an Account.
1. Test Mode Coverage
Test Mode Differences
The table below compares live mode and test mode for this business type:What You Can Test
The table below lists what this page tests:Endpoint Coverage in Test Mode
The table below lists the endpoints this business type uses:Webhooks
An onboarding fires the events below. Test mode accounts send them to your test mode webhook URL. The table below lists each webhook and what to do when it arrives:Webhooks Each Scenario Fires
The table below lists the webhooks that key scenarios fire:Before You Trust a Webhook
Follow these rules before you act on any webhook:- Verify the signature on the raw body with your webhook secret before you parse it. Reject anything that fails.
- Expect repeats. An event can arrive more than once. Use
X-Razorpay-Event-Idto process each event once. - Expect events out of order. Compare
payload.account.updated_at, or fetch the account and act on its current status. - Do not wait on webhooks. The payload carries only what changed: the complete product, with its status and requirements. Fetch the account for the rest, and fetch when an event is late.
Product Statuses
Take payments only while the product isactivated. Every status is reachable in test mode.
The table below lists the product statuses:
2. Before You Begin
Set up the following before you start:- Generate your app’s test key and secret pair on the Partner Dashboard. The test pair sends every request to test mode. Its key starts with
rzp_test_partner_. - Use the same endpoints and request bodies as in live mode. Only the key changes. Every write carries an
X-Idempotency-Keyheader. - Send each input’s value at its
field_path, in the order thatrequirementslists them. - Subscribe a test mode webhook URL on the Partner Dashboard to receive each scenario’s webhooks.
MERCM3412F verifies with the name Meridian Foods Private Limited. Business PAN ABCCD1234B fails with pan_not_found.
Keep these rules in mind when you pick values:
- To succeed, use the test business below.
- To fail a check, send one of the values in 3.3 Error Scenarios.
- You need no real details. Nothing reaches a registry, a bank or the sub-merchant. Skip the real PAN, bank account, phone and video call.
- Any other value fails as if the registry or bank were down.
Test Business
The test business uses the Indian Financial System Code (IFSC)HDFC0123456 for its bank account.
The table below lists the private limited test business:
3. Test Scenarios
This section lists every scenario to run against your integration for this business type before you go live. We group the scenarios by what each one proves. Work down the page in order to cover the integration end to end. The scenarios fall into 4 groups:- Must-build: The successful path and the outcomes you are almost certain to meet once live. Run these first.
- Other common scenarios: Scenarios shared with the other business types, so the same handling must work on every one.
- Error scenarios: Failed checks you trigger with a test value, so you check your handling without waiting for a real failure.
- Review, links and after activation: Outcomes that a reviewer, a hosted link or a later change decides. Test values and the hosted test pages force each one.
3.1 Must-Build Scenarios
Live scenarios work in test mode today. Coming soon scenarios are not available in test mode yet. The table below lists the must-build scenarios:| # | Scenario | Trigger | What to confirm |
|---|---|---|---|
| 1 | Activated end to end Coming soon | The test business, step by step |
|
| 2 | Create everything at once Coming soon | The values above in one account creation call |
|
| 3 | Beneficial owners Coming soon | Everyone who owns over 10% |
|
3.2 Other Common Scenarios
The table below lists the other common scenarios:| # | Scenario | Trigger | What to confirm |
|---|---|---|---|
| 4 | Signatory with a CKYC record Coming soon | Ananya Iyer |
|
| 5 | The documents instead of the numbers Coming soon | BUSINESS_PAN_MERCM3412F.pdf, COI_MERCM3412F.pdf |
|
| 6 | The CIN clears the business identity Coming soon | CIN U15400KA2017PTC104652 |
|
| 7 | Rejected (also on proprietorships) Coming soon | business_name Meridian Foods Private Limited_REJECT, or settlement account 000000000002 |
|
| 8 | Video KYC by value (also on proprietorships) Coming soon | business_name Meridian Foods Private Limited_EDD, or settlement account 000000000004 |
|
| 9 | Fetch to follow the status (also on every business type) Coming soon | Settlement account 000000000002 |
|
3.3 Error Scenarios
We group the error scenarios by the check or request that fails. In the error object,…authorized_person stands for business_profile.authorized_person. …website.primary stands for products.payment_gateway.payment_channels.website.primary.
PAN Registry
The PAN registry said no, or did not answer. Most failures bring back individual_pan or business_pan, meaning the number or the card.
The table below lists the PAN registry scenarios:
| # | Scenario | Trigger | Error object | What to confirm |
|---|---|---|---|---|
| 10 | Business PAN: the business PAN is invalid Coming soon | ABCCD1234B | verification.status: rejectedverification.error_code: pan_not_foundAt: business_profile.identity_numbers.business_panDue again: business_profile.identity_numbers.business_pan, business_profile.documents.business_panComposite requirement: business_pan |
|
| 11 | Business PAN: no record exists for the business PAN Coming soon | ABCCD1234C | verification.status: rejectedverification.error_code: pan_not_foundAt: business_profile.identity_numbers.business_panDue again: business_profile.identity_numbers.business_pan, business_profile.documents.business_panComposite requirement: business_pan |
|
| 12 | Business PAN: the registry errored, but the PAN is fine Coming soon | ABCCD1234D | verification.status: rejectedverification.error_code: pan_check_unavailableAt: business_profile.identity_numbers.business_panDue again: business_profile.identity_numbers.business_pan, business_profile.documents.business_panComposite requirement: business_pan |
|
| 13 | Signatory: the PAN holder is not the named signatory Coming soon | Name Rohan Kulkarni with PAN AANPI2846K | verification.status: rejectedverification.error_code: pan_name_mismatchAt: …authorized_person.identity_numbers.individual_panDue again: …authorized_person.name, …authorized_person.identity_numbers.individual_pan, …authorized_person.documents.individual_pan_documentComposite requirement: authorized_person |
|
| # | Scenario | Trigger | Error object | What to confirm |
|---|---|---|---|---|
| 14 | Proof of address: the Aadhaar is in another name Coming soon | AADHARMISMATCHFRONT.jpg | verification.status: rejectedverification.error_code: poa_name_mismatchAt: …authorized_person.documents.aadhaar_frontDue again: create_aadhaar_digilocker_link, …authorized_person.documents.aadhaar_front, …authorized_person.documents.aadhaar_back, …authorized_person.documents.passport_front, …authorized_person.documents.passport_back, …authorized_person.documents.voter_id_front, …authorized_person.documents.voter_id_backComposite requirement: proof_of_address_for_individual |
|
| 15 | Proof of address: the Aadhaar is unreadable Coming soon | AADHAARUNREADABLEFRONT.jpg | verification.status: rejectedverification.error_code: poa_unreadableAt: …authorized_person.documents.aadhaar_frontDue again: create_aadhaar_digilocker_link, …authorized_person.documents.aadhaar_front, …authorized_person.documents.aadhaar_back, …authorized_person.documents.passport_front, …authorized_person.documents.passport_back, …authorized_person.documents.voter_id_front, …authorized_person.documents.voter_id_backComposite requirement: proof_of_address_for_individual |
|
bank_account comes back as one_of: the same or another account (settlement_bank_account), or the ₹1 UPI link (create_upi_link). Show them as one choice.
The table below lists the bank scenarios:
| # | Scenario | Trigger | Error object | What to confirm |
|---|---|---|---|---|
| 16 | Bank account: the holder name does not match Coming soon | 2100000011 | verification.status: rejectedverification.error_code: bank_name_mismatchAt: bank_accounts.settlements_primaryDue again: bank_accounts.settlements_primary, create_upi_linkComposite requirement: bank_account |
|
| 17 | Bank account: the holder name is close but under the match threshold Coming soon | 2100000012 | verification.status: rejectedverification.error_code: bank_name_mismatchAt: bank_accounts.settlements_primaryDue again: bank_accounts.settlements_primary, create_upi_linkComposite requirement: bank_account |
|
| 18 | Bank account: the IFSC is invalid Coming soon | 2100000040 | verification.status: rejectedverification.error_code: bank_details_incorrectAt: bank_accounts.settlements_primaryDue again: bank_accounts.settlements_primary, create_upi_linkComposite requirement: bank_account |
|
| 19 | Bank account: the account is closed Coming soon | 1234567892 | verification.status: rejectedverification.error_code: bank_account_unusableAt: bank_accounts.settlements_primaryDue again: bank_accounts.settlements_primary, create_upi_linkComposite requirement: bank_account |
|
| 20 | Bank account: the account is frozen Coming soon | 2100000005 | verification.status: rejectedverification.error_code: bank_account_unusableAt: bank_accounts.settlements_primaryDue again: bank_accounts.settlements_primary, create_upi_linkComposite requirement: bank_account |
|
| 21 | Bank account: a Non-Resident External (NRE) account cannot receive settlements Coming soon | 2100000006 | verification.status: rejectedverification.error_code: bank_account_unusableAt: bank_accounts.settlements_primaryDue again: bank_accounts.settlements_primary, create_upi_linkComposite requirement: bank_account |
|
| 22 | Bank account: the bank was unreachable, but the account is fine Coming soon | 2100000039 | verification.status: rejectedverification.error_code: bank_check_unavailableAt: bank_accounts.settlements_primaryDue again: bank_accounts.settlements_primary, create_upi_linkComposite requirement: bank_account |
|
| 23 | Bank account: the bank declined without a reason Coming soon | 2100000031 | verification.status: rejectedverification.error_code: bank_not_verifiedAt: bank_accounts.settlements_primaryDue again: bank_accounts.settlements_primary, create_upi_linkComposite requirement: bank_account |
|
| # | Scenario | Trigger | Error object | What to confirm |
|---|---|---|---|---|
| 24 | Website: the check fails a few seconds after the response Coming soon | https://www.kc-not-found.com | verification.status: rejectedverification.error_code: website_unreachableAt: …website.primaryDue again: …website.primary |
|
| # | Scenario | Trigger | Error object | What to confirm |
|---|---|---|---|---|
| 25 | Video KYC not approved (also on every business type) Coming soon | The hosted page’s Unable to verify, or Rejected | Still due: create_video_kyc_linkrequirement_type: action |
|
| # | Scenario | Trigger | Error object | What to confirm |
|---|---|---|---|---|
| 26 | An ownership over 100 Coming soon | percentage_ownership: 120 | HTTP 400error.reason: invalid_formaterror.field: business_profile.stakeholders.<id>.percentage_ownership |
|
3.4 Review, Links and After Activation
A reviewer, a hosted link or a later change decides these outcomes. A test value or a hosted test page forces each one. The table below lists the scenarios that a review, a link or a later change decides:| # | Scenario | Trigger | What to confirm |
|---|---|---|---|
| 27 | Needs clarification (also on every business type) Coming soon | Settlement account 000000000003 |
|
| 28 | Held in review (also on every business type) Coming soon | Settlement account 000000000005 |
|
| 29 | Suspended after activation (also on every business type) Coming soon | Settlement account 000000000006 |
|
| 30 | A link expires before the sub-merchant finishes it (also on every business type) Coming soon | The hosted page’s Expire the link |
|
| 31 | DigiLocker for the proof of address Coming soon | The hosted page’s Share Aadhaar, then Decline |
|
| 32 | ₹1 UPI check of the bank account (also on every business type) Coming soon | The hosted page’s Pay ₹1, then Pay from another person’s account |
|
| 33 | Access withdrawn (also on every business type) Coming soon | Settlement account 000000000007 |
|
4. Common Integration Gaps
These mistakes most often stall an onboarding or leave an account in the wrong state after go-live. Test with points to the scenario that proves you handled each one. Requirements and Values The table below lists gaps in handling requirements and values:
Status and Webhooks
The table below lists gaps in handling status and webhooks:
Error Handling and Messaging
The table below lists gaps in error handling and messaging: