Sub-Merchant Onboarding APIs

Use various Sub-Merchant Onboarding APIs to seamlessly onboard merchants from your platform.

As a Partner, you can use the Sub-Merchant Onboarding APIs to onboard merchants from your platform. The sub-merchants can complete the KYC process in the Partner's platform itself and need not log in to Razorpay's platform.

  • Razorpay Sub-Merchant Onboarding APIs are RESTful. All our responses are returned in JSON.
  • You can use Razorpay APIs in two modes, Test and Live. The is different for each mode.
  • To complete the onboarding process for the sub-merchant, check the .
  • You can try out our APIs on the Razorpay Postman Public Workspace.

Watch this video to know how you can onboard sub-merchants using the Sub-Merchant Onboarding APIs.

The Razorpay API Gateway URL is You need to include this before each API endpoint to make API calls.

Handy Tips

While sending API requests to Razorpay servers, it is recommended to honor the TTL of the entries and not cache the DNS aggressively at your end. This is applicable when you are not using Razorpay SDKs. However, if you are using Razorpay SDKs, be informed that our SDKs can handle DNS caching and honor the TTLs set in the records.

You can use Partners APIs using either

or .

Watch Out!

Do not share your API Key secret or access token with anyone or on any public platforms. This can pose security threats for your Razorpay account.

Partner Auth uses Basic Auth. Basic auth requires the following:


Basic auth expects an Authorization header for each request in the Basic base64token format. Here, base64token is a base64 encoded string of YOUR_KEY_ID:YOUR_KEY_SECRET.

Watch Out!

The Authorization header value should strictly adhere to the format mentioned above. Invalid formats will result in authentication failures. Few examples of invalid headers are: BASIC base64token, basic base64token, Basic "base64token" and Basic $base64token.

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

Follow these steps to generate API Keys:

  1. Log in to your

    with appropriate credentials.

  2. Select the mode (Test or Live) for which you want to generate the API key.

    Handy Tips

    You have to generate separate Partner Credentials for the test and live modes. No real money is used in test mode.

  3. Navigate to Settings section to generate the key for the selected mode.

OAuth uses Bearer Auth. Know more about


To use OAuth for Partners APIs:

Raise a request with our

to get the cobranded_onboarding feature activated on your account. The cobranded_onboarding feature also enables:

Generate your access token using the below endpoint. You can generate it for test or live mode. Use the client_id and client_secret of the OAuth application for test and live modes.


Request Parameters



string Defines the grant type for the request. Possible value is client_credentials.



string The type of mode. Possible values:

  • test
  • live (default)



string Unique client identifier. Use the client_id of the OAuth application.



string Client secret string. Use the client_secret of the OAuth application.

Response Parmeters


integer Represents the TTL of the access token in seconds. You will have to regenerate the access token after expiry.


string Defines the type of access token. Possible value is Bearer.


string A public key is used only for public routes such as Checkout or Payments.


string Razorpay account id for which the access token is generated.


string A private key used to authenticate for Razorpay APIs.

You can use your OAuth access token to authenticate and use Partners APIs.

Given below is a sample code for the


You can use the Sub-Merchant Onboarding APIs to perform various actions.

Create, view, update and delete sub-merchant accounts.
Create, view and update stakeholders.
Request, view and update a product configuration.
Upload and view account and stakeholder documents.
Create, view, update and delete webhook events.
View and accept terms and conditions.

Given below is the complete end-to-end flow explaining the transition among statuses:

Account Activation Flow

For the following APIs, the updates permitted depend on the product activation status:

Activation StatusUpdate Permitted
requestedYou can update the details for all the fields.
needs_clarificationThe fields you can update depend on the reason_code mentioned in the requirements object in the :
  • document_missing or field_missing: You can update all the fields.
  • needs_clarification: You can update only the specific field for which Razorpay is seeking clarification for.
under_reviewYou cannot update any fields.
activatedYou cannot use this API to update any fields as your account is already active.

You can update the following details for Payment Gateway and Payment Links using the Update a Product Configuration API. However, whether the details can be updated or not depends upon the


  • Settlement Bank Account Details: You can update the settlement object with the new bank account details based on the product activation status.

  • Request Additional Payment Methods: You can request various payment methods and related instruments to be enabled using the payment_methods object. However, you can request for only one payment method at a time. For example, if you want to enable HDFC Netbanking and Rupay Domestic Card payment methods, you should send two separate API requests. You cannot send a consolidated request using this API.

  • Update Notifications Settings: You can update the email, WhatsApp and SMS settings using the notifications object.

  • Configure Checkout Features: You can change the checkout theme colour, add a logo and enable the saving of customer card details using the checkout object.

  • Configure Refund Speed: You can configure the default refund speed using the refund object.

  • Accept of Terms and Conditions: You can accept Razorpay terms and conditions.

Given below is the workflow:

  1. As a partner, it is your responsibility to show respective terms and conditions to the sub-merchants before you start onboarding to a product. The APIs used for it will be .
  2. You should display these web pages to your sub-merchants on your interface.
  3. Record the acceptance of terms and transmit that to Razorpay using either or .

Was this page helpful?