Xpress Onboarding

How it Works

Razorpay partially activates the account after verifying the KYC submitted.

The sub-merchant needs to submit the following minimum KYC details along with the other business details :

Business Type | Minimal KYC Details
Individuals | - Personal PAN
Bank Account Details (IFSC Code, A/C No., Beneficiary Name)
Proprietorship | - Personal PAN
Bank Account Details (IFSC Code, A/C No., Beneficiary Name)
Business PAN (Optional)
Other Registered Business | - Personal PAN
Bank Account Details (IFSC Code, A/C No., Beneficiary Name)
Business PAN
Signatory PAN
Razorpay verifies the KYC details and partially activates the sub-merchant account. The account moves to activated_kyc_pending state. The sub-merchant can start accepting payments up to GMV (Gross Merchandise Value) limit of â‚¹50,000 (or â‚¹5,00,000 if GST verified) using Payment Links and QR Codes.
The sub-merchant can submit the rest of the KYC documents while the account is in activated_kyc_pending state.
Razorpay team reviews the submitted details. Based on the evaluation, the account can move to either of these states:
- needs_clarification and under_review: Your sub-merchant can accept payments and receive settlements, upto the GMV limit. If limits are breached, the payments and settlements are put on hold.
- activated: If account is successfully activated, the breach limits are removed for payments and settlements.
- suspended: Payments and settlements are put on hold. Please reach out to Razorpay support for the next steps.

Watch Out!

If the documents are not submitted and the limit is breached, the account moves to needs_clarification state, with the requirements array showing the documents that need to be submitted. The settlements and payments are put on hold.
In some scenarios, the sub-merchant’s account is not partially activated. The sub-merchant should submit all the other KYC documents and go through the standard onboarding flow:
Duplicate Primary Details: If the sub-merchant’s primary details, such as phone number, PAN (business PAN or company PAN) already exist in the system, Razorpay provides one retry to update the field value and changes the status to needs_clarification.
Verification Failure: Given below are two types of verification failure situations: If the PAN or Bank Account verification fails, the account moves to needs_clarification state. The sub-merchant cannot proceed with Xpress Onboarding. Razorpay provides one retry to update the field value before the merchant is moved to the standard onboarding flow.
If the GSTIN exists for a sub-merchant and the verification fails, then the status changes to needs_clarification.

Given below is a diagram which explains the different states the account moves to during its lifecycle:

Example

ABC Inc. is an ERP software company, that wants to onboard their customer Acme Corp (an ecommerce business that sells books) as a sub-merchant to accept payments. ABC Inc. should sign up as a Razorpay partner and then use our onboarding APIs to create Acme Corp’s sub-merchant account by providing the relevant details and documents. Our team will review the submitted details and change the account state as applicable.

Prerequisites

Sign up as Partner and complete KYC to activate your account.
Generate client_id and client_secret to authenticate APIs calls for both test mode or live mode.

Watch this video to see how to generate the API keys.

Workflow

Given below is a diagram that illustrates the various steps in the workflow. The document requirements are visible in the array.

Watch Out!

Currently, we do not support making concurrent requests to the following Onboarding APIs including their combination on the same account_id:
Update Account API
Update Stakeholder API
Update Product Configuration API

Please wait for the response of these APIs before making subsequent requests.

1. Create an Account

Create an account for the sub-merchant using the Create an Account API by passing the no_doc_onboarding=true parameter. This triggers the Xpress Onboarding flow.

Available Account APIs

API | Description

Create an account | API to create a sub-merchant account.

Fetch an account | API to view sub-merchant account details.

Update an account | API to update the sub-merchant account details.

Delete an account | API to delete a sub-merchant account.

2. Create a Stakeholder

Use the Create a Stakeholder API to add a stakeholder for an account. Each stakeholder needs to update the KYC.

Available Stakeholder APIs

API | Description

Create a stakeholder | API to create a stakeholder.

Fetch a stakeholder | API to retrieve and view the stakeholder account details.

Fetch all stakeholders | API to retrieve all stakeholders for a given account.

Update a Stakeholder | API to update the stakeholder account details.

3. View and Accept Terms and Conditions

Before activating the sub-merchant and requesting for relevant product configurations, the sub-merchant needs to view and accept the Terms and Conditions. You can fetch these Terms and Conditions links using the Fetch Terms and Conditions API to share them with the sub-merchant. You can also accept Terms and Conditions for the sub-merchant using the Request a Product Configuration API.

Available Terms and Conditions APIs

API | Description

Accept Terms and Conditions | API to accept terms and conditions.

Fetch Terms and Conditions | API to retrieve terms and conditions.

4. Configure Products to Accept Payments

You can use the Product Configuration APIs to configure and activate Razorpay products for a sub-merchant account according to their requirements.

Available Product Configuration APIs

API | Description

Request a Product Configuration | API to request a product configuration.

Update a product configuration | API to update a configured product.

Fetch a Product | API to fetch a configured product.

5. Upload Supporting Documents

You can submit the required documents for sub-merchant onboarding using the Documents APIs listed in the table below.

Available Documents APIs

API | Description

Upload account documents | API to upload sub-merchant’s business documents.

Upload stakeholder documents | API to upload stakeholder’s signatory documents.

Fetch account documents | API to fetch account documents.

Fetch stakeholder documents | API to fetch stakeholder documents. Subscribe to relevant webhook events to receive notifications (in the form of a webhook payload) when these events occur. There are 2 types of events:

Transaction Events: These are events related to payment transactions performed by the sub-merchants. You can configure these events at a sub-merchant level. View webhook events and payload details.
Sub-Merchant Onboarding Events: These events are related to the onboarding status of the sub-merchant. You should configure these at your end. Subscribing to these events will enable you to get the onboarding status of all sub-merchants.

Available Webhook Events and Descriptions

Event Name | Description

product.payment_link.under_review | Triggered when the status for a Payment Link product is `under_review`.

product.payment_link.needs_clarification | Triggered when the status for a Payment Link product is `needs_clarification`.

product.payment_link.activated | Triggered when the status for a Payment Link product is `activated`.

product.payment_link.rejected | Triggered when the status for a Payment Link product is rejected. View payload details. Watch this video to see how you can subscribe to Partner Webhooks.

Log in to the Dashboard.
Navigate to Partner’s Dashboard â†’ Settings â†’ Webhooks to subscribe to any of the events mentioned in the following section.
Click Manage.
In the Webhook Setup pop-up page:
1. Enter the URL where you want to receive the webhook payload when an event is triggered. We recommended using an HTTPS URL.
2. Enter a Secret for the webhook endpoint. The secret is used to validate that the webhook is from Razorpay.
3. In the Alert Email field, enter the email address to which the notifications should be sent in case of webhook failure.
4. Select the required events from the list of Active Events.
Click Create Webhook.

Alerts

Razorpay sends alerts once the sub-merchant GMV is breached. The first webhook event will be triggered when 90% of the GMV is breached. After that, at an increment of 1% a webhook event will be triggered. Given below is the event name and description:

Event Name | Description

account.no_doc_onboarding_gmv_limit_warning | Triggered when the sub-merchant breaches the GMV.

Sample Payload

{
  "acc_id": "xxxx",
  "gmv_limit": "500000",
  "current_gmv": "xxxx",
  "message": "You can accept payments upto INR X (remaining GMV limit). In order to remove this limit, kindly submit the KYC documents."
}

Webhooks APIs

You can use the Webhooks APIs to receive event notifications or subscribe to events happening in a sub-merchant’s account, such as payments, orders, invoices and so on.

​How it Works

​Business Type | Minimal KYC Details

​Example

​Prerequisites

​Workflow

​1. Create an Account

​Available Account APIs

​API | Description

​Create an account | API to create a sub-merchant account.

​Fetch an account | API to view sub-merchant account details.

​Update an account | API to update the sub-merchant account details.

​2. Create a Stakeholder

​Available Stakeholder APIs

​API | Description

​Create a stakeholder | API to create a stakeholder.

​Fetch a stakeholder | API to retrieve and view the stakeholder account details.

​Fetch all stakeholders | API to retrieve all stakeholders for a given account.

​3. View and Accept Terms and Conditions

​Available Terms and Conditions APIs

​API | Description

​Accept Terms and Conditions | API to accept terms and conditions.

​4. Configure Products to Accept Payments

​Available Product Configuration APIs

​API | Description

​Request a Product Configuration | API to request a product configuration.

​Update a product configuration | API to update a configured product.

​5. Upload Supporting Documents

​Available Documents APIs

​API | Description

​Upload account documents | API to upload sub-merchant’s business documents.

​Upload stakeholder documents | API to upload stakeholder’s signatory documents.

​Fetch account documents | API to fetch account documents.

​6. Subscribe to Webhooks

​Available Webhook Events and Descriptions

​Event Name | Description

​product.payment_link.under_review | Triggered when the status for a Payment Link product is under_review.

​product.payment_link.needs_clarification | Triggered when the status for a Payment Link product is needs_clarification.

​product.payment_link.activated | Triggered when the status for a Payment Link product is activated.

​To subscribe to webhook events:

​Alerts

​Event Name | Description

​Webhooks APIs

​Available Webhooks APIs

​API | Description

​Create a Webhook | API to create a webhook.

​Fetch a Webhook | API to retrieve and view the webhook details.

​Fetch all Webhooks | API to retrieve all webhooks.

​Update a Webhook | API to update the webhook details.

How it Works

Business Type | Minimal KYC Details

Example

Prerequisites

Workflow

1. Create an Account

Available Account APIs

API | Description

Create an account | API to create a sub-merchant account.

Fetch an account | API to view sub-merchant account details.

Update an account | API to update the sub-merchant account details.

2. Create a Stakeholder

Available Stakeholder APIs

API | Description

Create a stakeholder | API to create a stakeholder.

Fetch a stakeholder | API to retrieve and view the stakeholder account details.

Fetch all stakeholders | API to retrieve all stakeholders for a given account.

3. View and Accept Terms and Conditions

Available Terms and Conditions APIs

API | Description

Accept Terms and Conditions | API to accept terms and conditions.

4. Configure Products to Accept Payments

Available Product Configuration APIs

API | Description

Request a Product Configuration | API to request a product configuration.

Update a product configuration | API to update a configured product.

5. Upload Supporting Documents

Available Documents APIs

API | Description

Upload account documents | API to upload sub-merchant’s business documents.

Upload stakeholder documents | API to upload stakeholder’s signatory documents.

Fetch account documents | API to fetch account documents.

6. Subscribe to Webhooks

Available Webhook Events and Descriptions

Event Name | Description

product.payment_link.under_review | Triggered when the status for a Payment Link product is `under_review`.

product.payment_link.needs_clarification | Triggered when the status for a Payment Link product is `needs_clarification`.

product.payment_link.activated | Triggered when the status for a Payment Link product is `activated`.

To subscribe to webhook events:

Alerts

Event Name | Description

Webhooks APIs

Available Webhooks APIs

API | Description

Create a Webhook | API to create a webhook.

Fetch a Webhook | API to retrieve and view the webhook details.

Fetch all Webhooks | API to retrieve all webhooks.

Update a Webhook | API to update the webhook details.