Skip to main content
Available in🇮🇳 India
A public 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-Id to 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 is activated. 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-Key header.
  • Send each input’s value at its field_path, in the order that requirements lists them.
  • Subscribe a test mode webhook URL on the Partner Dashboard to receive each scenario’s webhooks.
The value you send decides each check. As for an individual, the signatory’s CKYC record decides whether video KYC is due. For example, business PAN ABCCD1246M verifies with the name NEXGEN VENTURES PUBLIC 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 public 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.
Each scenario’s steps end with the webhooks it fires and the status it leaves. In test mode, the webhooks go to your test mode webhook URL.

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:
#ScenarioTriggerWhat to confirm
1Activated end to end Coming soonThe test business, step by step
  1. Create the account with country, the user and products: { "payment_gateway": { "payment_channels": {} } }. See Create an Account. Confirm business_type, send_phone_otp and send_email_otp are due.
  2. Run send_phone_otp and send_email_otp, then send 000007 as phone_otp and email_otp.
  3. Send business_type: public_limited, the business PAN ABCCD1246M at business_profile.identity_numbers.business_pan and the CIN U67190TN2014PLC096989 at business_profile.identity_numbers.cin.
  4. Confirm both are verified and the PAN record’s name NEXGEN VENTURES PUBLIC LIMITED comes back as business_name. Confirm business_pan and business_identity clear.
  5. Send the authorised person Rzp Test QA Merchant with PAN ABCPD1234A at business_profile.authorized_person. This person has a CKYC record, so ckyc_fetch is due.
  6. Run send_ckyc_otp with metadata.ckyc_mobile +919845098450, or without it to use the mobile number on the CKYC record.
  7. Send any 6 digits other than 000000 as individual_ckyc.otp, with its request ID as individual_ckyc.request_id. Confirm verified.
  8. Send date_of_establishment 2018-07-03.
  9. Send stakeholders with the name, PAN and percentage_ownership of everyone who owns over 10%.
  10. Send registered_address and operational_address under business_profile.addresses. Each is all_of its lines, city, state, postal code and country. line2 is optional.
  11. Send bank account 210045678907 with IFSC HDFC0123456. Confirm it is verified with the holder NEXGEN VENTURES PUBLIC LIMITED.
  12. Send the category ecommerce with the subcategory computers_peripheral_equipment_software (MCC 5732) and a description.
  13. Send the website https://curlec.com and a statement descriptor at statement_descriptor.value.
  14. The test category, computers_peripheral_equipment_software, asks no business-model questions. To test them, see scenario 8 on Update an Account.
  15. Show Razorpay’s terms of service to the sub-merchant. Then send the sub-merchant’s ip and device_fingerprint_id in products.payment_gateway.terms_of_service_acceptance. See Terms and Submission.
  16. Confirm the response is activated.
  17. Webhooks received: account.requirements.updated (as the website check settles), account.product.activated.
  18. Status changes: in_progress → activated.
2Create everything at once Coming soonThe values above in one account creation call
  1. Send the values in the shape of the one-shot request on Create an Account.
  2. Confirm 201. Answer what is left (the CKYC code, the questions and the terms) and submit.
  3. Webhooks received: account.requirements.updated (as the website check settles), account.product.activated.
  4. Status changes: in_progress → activated.
3Beneficial owners Coming soonEveryone who owns over 10%
  1. Send stakeholders keyed by any new key. Each entry has name, identity_numbers.individual_pan and percentage_ownership.
  2. Confirm Razorpay returns each beneficial owner under a per_ stakeholder ID.
  3. Webhooks received: none.
  4. Status changes: none.

3.2 Other Common Scenarios

The table below lists the other common scenarios:
#ScenarioTriggerWhat to confirm
4Signatory with a CKYC record Coming soonRzp Test QA Merchant
  1. Send the signatory’s name and PAN. Fetch the CKYC record with send_ckyc_otp and the code.
  2. Confirm no proof of address is due for the signatory, unless skip_ckyc is sent.
  3. Webhooks received: none.
  4. Status changes: none.
5The documents instead of the numbers Coming soonBUSINESS_PAN_ABCCD1246M.pdf, COI_ABCCD1246M.pdf
  1. Upload BUSINESS_PAN_ABCCD1246M.pdf (type: business_pan) and COI_ABCCD1246M.pdf (type: certificate_of_incorporation).
  2. Attach the PAN card at business_profile.documents.business_pan in place of the business PAN.
  3. Attach the certificate at business_profile.documents.certificate_of_incorporation in place of the CIN.
  4. Confirm each is verified.
  5. Confirm business_pan and business_identity cleared.
  6. Webhooks received: none.
  7. Status changes: none.
6The CIN clears the business identity Coming soonCIN U67190TN2014PLC096989
  1. Send the CIN.
  2. Confirm business_identity cleared, so no certificate of incorporation is due.
  3. Webhooks received: none.
  4. Status changes: none.
7Rejected (also on proprietorships) Coming soonbusiness_name NEXGEN VENTURES PUBLIC LIMITED_REJECT, or settlement account 000000000002
  1. Submit the account.
  2. Confirm the response is under_review, then fetch the account after 5 sec. Confirm rejected.
  3. Webhooks received: account.requirements.updated (as the website check settles), account.product.under_review, account.product.rejected.
  4. Status changes: under_review → rejected.
8Video KYC by value (also on proprietorships) Coming soonbusiness_name NEXGEN VENTURES PUBLIC LIMITED_EDD, or settlement account 000000000004
  1. Submit the account. Confirm the response is edd_pending, with create_video_kyc_link due.
  2. Run the action, open the link and pick Approved.
  3. Fetch the account after 5 sec. Confirm activated.
  4. Webhooks received: account.requirements.updated (as the website check settles), account.product.edd_pending, account.requirements.updated, account.product.under_review, account.product.activated.
  5. Status changes: edd_pending → under_review → activated.
9Fetch to follow the status (also on every business type) Coming soonSettlement account 000000000002
  1. Submit the account. Confirm the response is under_review.
  2. Poll the account with a timeout.
  3. Confirm rejected arrives about 5 sec later, and that your code never treats under_review as final.
  4. Webhooks received: account.requirements.updated (as the website check settles), account.product.under_review, account.product.rejected.
  5. Status changes: under_review → rejected.

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:
#ScenarioTriggerError objectWhat to confirm
10Business PAN: the business PAN is invalid Coming soonABCCD1234Bverification.status: rejected
verification.error_code: pan_not_found
At: business_profile.identity_numbers.business_pan
Due again: business_profile.identity_numbers.business_pan, business_profile.documents.business_pan
Composite requirement: business_pan
  1. Send the value where it is due. Confirm the response is a 200.
  2. Webhooks received: none, because the response carries the failure.
  3. Status changes: none. The product stays in_progress.
11Business PAN: no record exists for the business PAN Coming soonABCCD1234Cverification.status: rejected
verification.error_code: pan_not_found
At: business_profile.identity_numbers.business_pan
Due again: business_profile.identity_numbers.business_pan, business_profile.documents.business_pan
Composite requirement: business_pan
  1. Send the value where it is due. Confirm the response is a 200.
  2. Webhooks received: none, because the response carries the failure.
  3. Status changes: none. The product stays in_progress.
12Business PAN: the registry errored, but the PAN is fine Coming soonABCCD1234Dverification.status: rejected
verification.error_code: pan_check_unavailable
At: business_profile.identity_numbers.business_pan
Due again: business_profile.identity_numbers.business_pan, business_profile.documents.business_pan
Composite requirement: business_pan
  1. Send the value where it is due. Confirm the response is a 200.
  2. Webhooks received: none, because the response carries the failure.
  3. Status changes: none. The product stays in_progress.
13Signatory: the PAN holder is not the named signatory Coming soonName Rohan Kulkarni with PAN AANPI2846Kverification.status: rejected
verification.error_code: pan_name_mismatch
At: …authorized_person.identity_numbers.individual_pan
Due again: …authorized_person.name, …authorized_person.identity_numbers.individual_pan, …authorized_person.documents.individual_pan_document
Composite requirement: authorized_person
  1. Send the value where it is due. Confirm the response is a 200.
  2. Webhooks received: none, because the response carries the failure.
  3. Status changes: none. The product stays in_progress.
Documents The file was unreadable, or did not match what was sent. Ask for the right file. The table below lists the document scenarios:
#ScenarioTriggerError objectWhat to confirm
14Proof of address: the Aadhaar is in another name Coming soonAADHARMISMATCHFRONT.jpgverification.status: rejected
verification.error_code: poa_name_mismatch
At: …authorized_person.documents.aadhaar_front
Due 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_back
Composite requirement: proof_of_address_for_individual
  1. Upload the file with its type and attach its id where it is due.
  2. Confirm the response is a 200.
  3. Webhooks received: none, because the response carries the failure.
  4. Status changes: none. The product stays in_progress.
15Proof of address: the Aadhaar is unreadable Coming soonAADHAARUNREADABLEFRONT.jpgverification.status: rejected
verification.error_code: poa_unreadable
At: …authorized_person.documents.aadhaar_front
Due 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_back
Composite requirement: proof_of_address_for_individual
  1. Upload the file with its type and attach its id where it is due.
  2. Confirm the response is a 200.
  3. Webhooks received: none, because the response carries the failure.
  4. Status changes: none. The product stays in_progress.
Bank The bank check failed. 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:
#ScenarioTriggerError objectWhat to confirm
16Bank account: the holder name does not match Coming soon2100000011verification.status: rejected
verification.error_code: bank_name_mismatch
At: bank_accounts.settlements_primary
Due again: bank_accounts.settlements_primary, create_upi_link
Composite requirement: bank_account
  1. Send the value where it is due. Confirm the response is a 200.
  2. Webhooks received: none, because the response carries the failure.
  3. Status changes: none. The product stays in_progress.
17Bank account: the holder name is close but under the match threshold Coming soon2100000012verification.status: rejected
verification.error_code: bank_name_mismatch
At: bank_accounts.settlements_primary
Due again: bank_accounts.settlements_primary, create_upi_link
Composite requirement: bank_account
  1. Send the value where it is due. Confirm the response is a 200.
  2. Webhooks received: none, because the response carries the failure.
  3. Status changes: none. The product stays in_progress.
18Bank account: the IFSC is invalid Coming soon2100000040verification.status: rejected
verification.error_code: bank_details_incorrect
At: bank_accounts.settlements_primary
Due again: bank_accounts.settlements_primary, create_upi_link
Composite requirement: bank_account
  1. Send the value where it is due. Confirm the response is a 200.
  2. Webhooks received: none, because the response carries the failure.
  3. Status changes: none. The product stays in_progress.
19Bank account: the account is closed Coming soon1234567892verification.status: rejected
verification.error_code: bank_account_unusable
At: bank_accounts.settlements_primary
Due again: bank_accounts.settlements_primary, create_upi_link
Composite requirement: bank_account
  1. Send the value where it is due. Confirm the response is a 200.
  2. Webhooks received: none, because the response carries the failure.
  3. Status changes: none. The product stays in_progress.
20Bank account: the account is frozen Coming soon2100000005verification.status: rejected
verification.error_code: bank_account_unusable
At: bank_accounts.settlements_primary
Due again: bank_accounts.settlements_primary, create_upi_link
Composite requirement: bank_account
  1. Send the value where it is due. Confirm the response is a 200.
  2. Webhooks received: none, because the response carries the failure.
  3. Status changes: none. The product stays in_progress.
21Bank account: a Non-Resident External (NRE) account cannot receive settlements Coming soon2100000006verification.status: rejected
verification.error_code: bank_account_unusable
At: bank_accounts.settlements_primary
Due again: bank_accounts.settlements_primary, create_upi_link
Composite requirement: bank_account
  1. Send the value where it is due. Confirm the response is a 200.
  2. Webhooks received: none, because the response carries the failure.
  3. Status changes: none. The product stays in_progress.
22Bank account: the bank was unreachable, but the account is fine Coming soon2100000039verification.status: rejected
verification.error_code: bank_check_unavailable
At: bank_accounts.settlements_primary
Due again: bank_accounts.settlements_primary, create_upi_link
Composite requirement: bank_account
  1. Send the value where it is due. Confirm the response is a 200.
  2. Webhooks received: none, because the response carries the failure.
  3. Status changes: none. The product stays in_progress.
23Bank account: the bank declined without a reason Coming soon2100000031verification.status: rejected
verification.error_code: bank_not_verified
At: bank_accounts.settlements_primary
Due again: bank_accounts.settlements_primary, create_upi_link
Composite requirement: bank_account
  1. Send the value where it is due. Confirm the response is a 200.
  2. Webhooks received: none, because the response carries the failure.
  3. Status changes: none. The product stays in_progress.
Website The website check runs after the response, so the failure shows on the next fetch. Send the website again, or another one. The table below lists the website scenario:
#ScenarioTriggerError objectWhat to confirm
24Website: the check fails a few seconds after the response Coming soonhttps://www.kc-not-found.comverification.status: rejected
verification.error_code: website_unreachable
At: …website.primary
Due again: …website.primary
  1. Send the website where it is due, and fetch the account after 5 sec.
  2. Webhooks received: account.requirements.updated.
  3. Status changes: none. The product stays in_progress.
Video KYC The call did not verify the person. The action is due again, so let the sub-merchant start a new call. The table below lists the video KYC scenario:
#ScenarioTriggerError objectWhat to confirm
25Video KYC not approved (also on every business type) Coming soonThe hosted page’s Unable to verify, or RejectedStill due: create_video_kyc_link
requirement_type: action
  1. Submit a test business without a CKYC record, run create_video_kyc_link and open the url.
  2. Pick Unable to verify.
  3. Fetch the account. Confirm create_video_kyc_link is still due, and run it again for a new call.
  4. Pick Rejected on a new link instead. Confirm the product ends rejected.
  5. Webhooks received: none for Unable to verify, because the requirements do not change. For Rejected, account.product.under_review then account.product.rejected.
  6. Status changes: the product stays edd_pending, or moves under_review → rejected.
Request Errors The request itself was wrong, so nothing was saved and no webhook fires. Fix it in code, because retrying it unchanged fails again. The table below lists the request error scenarios:
#ScenarioTriggerError objectWhat to confirm
26An ownership over 100 Coming soonpercentage_ownership: 120HTTP 400
error.reason: invalid_format
error.field: business_profile.stakeholders.<id>.percentage_ownership
  1. Send the update.
  2. Confirm 400, and that nothing was saved.
  3. Webhooks received: none.
  4. Status changes: none.
Every failure code, with its test value, is in the Error Index. 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:
#ScenarioTriggerWhat to confirm
27Needs clarification (also on every business type) Coming soonSettlement account 000000000003
  1. Run scenario 1 with this settlement account, and submit.
  2. Fetch the account after 5 sec. Confirm needs_clarification, with only bank_account due.
  3. Answer the point. When submit_clarification is due, send submit_clarification: true in its own call. See Needs Clarification.
  4. Webhooks received: account.requirements.updated (as the website check settles), account.product.under_review, account.product.needs_clarification, account.product.under_review, account.product.activated.
  5. Status changes: under_review → needs_clarification → under_review → activated.
28Held in review (also on every business type) Coming soonSettlement account 000000000005
  1. Send the account. Confirm its verification is deferred and bank_account clears.
  2. Submit. Confirm the response is under_review.
  3. Confirm it stays under_review for 5 min, then becomes activated.
  4. Assert that no timeout in your code moves the sub-merchant to a failure state.
  5. Webhooks received: account.requirements.updated (as the website check settles), account.product.under_review, account.product.activated.
  6. Status changes: under_review → activated.
29Suspended after activation (also on every business type) Coming soonSettlement account 000000000006
  1. Run scenario 1 with this settlement account. Confirm the response is activated.
  2. About 60 sec later, confirm suspended, with status_reason.code: website_review_failed and the website due again.
  3. Stop payments, show the reason and ask for what is listed.
  4. Send https://curlec.com. Confirm the product is activated again.
  5. Webhooks received: account.requirements.updated (as the website check settles), account.product.activated, account.product.suspended. After the website, account.requirements.updated and account.product.activated.
  6. Status changes: activated → suspended → activated.
30A link expires before the sub-merchant finishes it (also on every business type) Coming soonThe hosted page’s Expire the link
  1. Run any link action (video KYC, DigiLocker or ₹1 UPI) and open its url.
  2. Pick Expire the link.
  3. Fetch the account. Confirm the action is still due.
  4. Show a fresh Start again that runs the action again for a new link. Never reuse an expired url.
  5. Webhooks received: none, because the requirements do not change.
  6. Status changes: none.
31DigiLocker for the proof of address Coming soonThe hosted page’s Share Aadhaar, then Decline
  1. With proof_of_address_for_individual due, run create_aadhaar_digilocker_link with your return_url. Open the url in its response.
  2. Pick Share Aadhaar. Confirm proof_of_address_for_individual clears and the page returns to your return_url.
  3. On another account, pick Decline. Confirm proof_of_address_for_individual stays due, with the action and the document uploads.
  4. Run the action again, or upload a document.
  5. Webhooks received: account.requirements.updated when the Aadhaar is shared. None after Decline.
  6. Status changes: none.
32₹1 UPI check of the bank account (also on every business type) Coming soonThe hosted page’s Pay ₹1, then Pay from another person’s account
  1. With bank_account due after a failed bank check, run create_upi_link. Open the url in its response.
  2. Pick Pay ₹1. Confirm bank_account clears and the account is verified.
  3. On another account, pick Pay from another person’s account. Confirm bank_account stays due.
  4. Run the action again, or send the account.
  5. Webhooks received: account.requirements.updated when the payment verifies the account. None after a failed payment.
  6. Status changes: none.
33Access withdrawn (also on every business type) Coming soonSettlement account 000000000007
  1. Run scenario 1 with this settlement account.
  2. About 60 sec after activation, confirm account.consent.withdrawn arrives.
  3. Stop calling the API for the account. Confirm later calls return 403 consent_withdrawn.
  4. Webhooks received: account.requirements.updated (as the website check settles), account.product.activated, account.consent.withdrawn.
  5. Status changes: none after activated.

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:

5. Best Integration Practices

These practices apply to every onboarding integration. On this page says what each one means here. Test it points to the scenario that tests it. The table below lists the best integration practices:
Last modified on November 18, 2026