Available in🇮🇳 India
Use the Onboarding APIs to run the sign-up and KYC flow for your sub-merchants inside your own product. You build every screen and collect the information Razorpay needs to verify each sub-merchant. Razorpay’s terms of service name Razorpay as the payment aggregator the sub-merchant contracts with. Razorpay also holds the sub-merchant’s data.
We decide what each sub-merchant must submit, and we verify it. You design the screens and submit through the APIs. You cannot skip or change requirements.
The table below lists the terms this guide uses:
Your Responsibilities
As the partner platform, you take on these duties:- Show the terms unchanged: Show Razorpay’s terms of service as they are, and send the sub-merchant’s acceptance. That update submits the product.
- Delete collected KYC: Delete the KYC you collected once Razorpay has it. Know more about data protection.
- Keep forms in step: Build your forms from the
requirementsin each response instead of hard-coding them. Requirements can change.
Onboarding Flow
The create request carries everything you already hold. What is left comes back asrequirements, which you answer until only the terms of service remain. The sub-merchant accepts Razorpay’s terms in your UI, and the update that sends the acceptance submits the product.
Step 1: Authenticate
Step 1: Authenticate
Send the key and secret of your test pair or live pair as HTTP Basic credentials on every request. Know more about authentication.
Step 2: Create the Account
Step 2: Create the Account
Call Create an Account with everything you hold about the sub-merchant. The response lists the requirements still due.
POST /v1/accountsStep 3: Answer the Requirements
Step 3: Answer the Requirements
Check whether
accept_terms_of_service is the only requirement left. If it is not, collect what is still due: a code, a document or a value that did not verify. Then update the account or run an action. Repeat until only the terms remain. PATCH /v1/accounts/{account_id} and POST /v1/accounts/{account_id}/actions/{action}Step 4: Accept the Terms and Submit
Step 4: Accept the Terms and Submit
The sub-merchant accepts Razorpay’s terms in your UI. Sending the acceptance in an update submits the product.
PATCH /v1/accounts/{account_id}Step 5: Track Status
Step 5: Track Status
Fetch the account to track the product’s status, and answer any pending clarifications. Review ends in one of 2 outcomes:
activated when no requirements or clarifications are due, or rejected. GET /v1/accounts/{account_id} and webhooksChoose How to Onboard
A platform that already holds the sub-merchant’s details sends them all when it creates the account. For example, a store may have verified the owner’s phone and email, and know the PAN, website and bank account. A platform that collects details as it goes sends each one as Razorpay asks for it. Both ways use the same APIs and end in the same states.One-Shot
Send everything in Create an Account, then answer what is left. Suits platforms that already have the details on file.
Step by Step
Create the account with the user, then update the account for each requirement. Suits platforms with their own step-by-step forms.
Whichever way you onboard, you cannot send some things up front:
- A One-Time Password (OTP) code, which exists only once the code is sent
- A business-model question you cannot know in advance
- The sub-merchant’s acceptance of the terms
- The outcome of a review
Understand Requirements
What you collect from a sub-merchant, and send in Create or Update requests, depends on:- The product: The product the sub-merchant is onboarding to, for example
payment_gateway. - The business type: The sub-merchant’s
business_type, for exampleindividualorprivate_limited. - What is verified so far: A Central KYC Records Registry (CKYC) record fills the proof of address, which removes the address-proof requirement. Skipping CKYC, or a PAN with no CKYC record, makes the proof of address due instead.
requirements still due for each product, computed on every call. Each requirement is one of 3 types:
Input
Send a value or a document at the requirement’s
field_path in an update.Action
Run the action named in
requirement_code, such as send_phone_otp. Its response lists what is due next.Composite
Answer several requirements that make up one point, as its
fulfillment_criteria says.Authenticate Your Platform
Generate 2 key and secret pairs for your app once, on the Razorpay Partner Dashboard: one for test mode and one for live mode. The Partner Dashboard shows the secret only once. Also allowlist the IP ranges of your servers for each mode. In test mode, the allowlist is optional. Razorpay checks it once the test-mode allowlist has an entry. Send the pair as HTTP Basic credentials on every request:- Key: The key of the pair for the mode. A test key starts with
rzp_test_partner_and a live key withrzp_live_partner_. - Secret: The secret of the same pair.
Curl
- The pair: The secret is current for the key. Otherwise, the call returns
401 invalid_credentials. - The source IP: The request comes from an IP range in your app’s allowlist for the mode. Otherwise, the call returns
403 ip_not_allowed. In test mode, this applies once the test-mode allowlist has an entry. - The account: The account in the path is mapped to your app. Otherwise, the call returns
404, so an ID cannot reveal who banks with Razorpay. - The consent: Once the product is submitted, the sub-merchant’s consent is on record. After the sub-merchant withdraws it, every call returns
403 consent_withdrawn.
Rotate the Secret
Rotate the secret on the Partner Dashboard. The old secret keeps working for up to 24 h, or until you end that window. Revoking a secret stops it at once.Request Headers
The table below lists the headers your requests carry:
A product is never a header. Create and Update key the product’s values by its type in
products, such as products.payment_gateway. Reads return every product.
A test account cannot be used in live mode, and test calls never reach banks or registries. Requests about one account carry its ID in the path, such as /v1/accounts/acc_TcdGEzmfKQzEl1.
Protect Sub-Merchant Data
Razorpay is the data fiduciary for the sub-merchant’s KYC. We decide what to collect and why. You collect it on our behalf, as our processor. This sets 4 rules:- What is returned: Responses and events return identifiers in full, such as the PAN and the bank account number, each with its
verification. A document comes back with its verification and itsurl, the link to the stored file. The CKYC record returns the mobile number on the record in itsmetadata. Responses leave out addresses that Razorpay fills from a registry, such as a CKYC record’s. They also leave out the bank’s name for the account holder. Their requirement clears and the element shows its verification. The name on the PAN comes back asbusiness_name. Documents Razorpay fetches, such as from CKYC or DigiLocker, come back as documents. Errors never repeat a value you sent. - Razorpay keeps its own copy: Razorpay stores every document under its own
file_ID, whether sent as a link or an upload. This includes Aadhaar. Razorpay does not keep your link. - You delete what you collected: Delete it once Razorpay has it, within the period your agreement with Razorpay sets. Do not keep copies for other purposes.
- Sub-merchant rights go through Razorpay: Razorpay’s terms of service name Razorpay Software Private Limited (RSPL), with its privacy policy and grievance route. A sub-merchant who withdraws consent, or asks Razorpay to delete its data, cuts your platform off. The
account.consent.withdrawnwebhook fires, and every later call on the account returns403 consent_withdrawn.
Product States
Onboarding status lives on each product of the account. Activation needs the business’s KYC verified and the product’s own checks passed. These include the subcategory, and the website when one is sent. Razorpay checks the website again every year. An account takes payments once the product’s status isactivated.
- Before Submission
- After Submission
The table below lists the product states before submission:
Integration Steps
To integrate the Onboarding APIs, follow these steps:- Create an Account: Find or create the sub-merchant’s account, with the one-shot or step-by-step approach.
- Collect Requirements: Read requirements, composite requirements and failed checks to build your forms.
- Submit Information: Update the account, send payment channels, change the bank account and upload documents.
- Run Verification Actions: Send OTPs, fetch KYC from CKYC and mint links for DigiLocker, UPI and video KYC.
- Accept Terms and Submit: Show Razorpay’s terms and send the sub-merchant’s acceptance.
- Handle Needs Clarification: Answer a reviewer’s questions and resubmit.
- Track Product Status: Fetch the account, read status reasons and manage payment methods.
- Account Management: Change the details that stay editable after activation, after a manual review.
- Error Codes: Handle errors by class and reason.