Upgraded docs version is here ✨

Your documentation experience is getting an upgrade. Check it out now!

Go To Beta

Docs upgrade is here. Check it out!

Go To Beta
API ReferenceIntegrationsKnowledge Base

Account APIs

You can use the Account APIs to create a sub-merchant account. After an account gets created, an account_id is assigned.

You can create, fetch, and update a sub-merchant account using these APIs.

You can try out our APIs on the Razorpay Postman Public Workspace.

Run in Postman

Changelog
The following changes will take effect from 30 April 2022:

  • The profile.business_model parameter will accept string values, with character limit between 50-255 characters. Earlier, it used to accept only three values b2b, b2c and b2b+b2c.
  • The profile.description parameter will be deprecated as this information will be henceforth captured by the profile.business_model parameter.

Account Entity🔗

The Account entity consists of the following fields. You can find the JSON sample entity on the right side.

id

string The unique identifier of a sub-merchant account generated by Razorpay. The maximum length is 18 characters. For example, acc_GLGeLkU2JUeyDZ.

type

string The account type. Possible value is standard.

status

string The status of the account. Possible values:

  • created
  • suspended
email

string The sub-merchant's business email address.

phone

integer The sub-merchant's business phone number. The minimum length is 8 characters and the maximum length is 15.

legal_business_name

string The name of the sub-merchant's business. For example, Acme Corp. The minimum length is 4 characters and the maximum length is 200.

customer_facing_business_name

string The sub-merchant billing label as it appears on the Razorpay Dashboard. The minimum length is 1 character and the maximum length is 255. Handy Tip
This parameter might be required to complete the KYC process. However, it is optional for this API.

business_type

string The type of business operated by the sub-merchant. List of possible values are available here.

reference_id

string Partner's external account reference id. The minimum length is 1 character and the maximum length is 512.

profile

object The business details of the sub-merchant's account.

category

string The business category of the sub-merchant. Possible values: Business Category

sub-category

string The business sub-category of the sub-merchant. Possible values: Business Sub-Category

description deprecated

string This parameter has been deprecated. Pass the description using the business_model parameter.

business_model

string The business description. The minimum length is 1 character and the maximum length is 250.

addresses

object Details of sub-merchant's address.

operation

object Details of the sub-merchant's operational address. Handy Tip
This parameter might be required to complete the KYC process. However, it is optional for this API.

street1
string Address, line 1. The maximum length is 100 characters.
street2
string Address, line 2. The maximum length is 100 characters.
city
string The city. The maximum length is 100 characters.
state
string The state. The minimum length is 2 and the maximum length is 100.
postal_code
integer The postal code. This should be exactly 6 characters.
country
string The country. The minimum length is 2 and the maximum length is 64.
registered

object Details of the sub-merchant's registered address.

street1
string Address, line 1. The maximum length is 100 characters.
street2
string Address, line 2. The maximum length is 100 characters.
city
string The city. The maximum length is 100 characters.
state
string The state. The minimum length is 2 and the maximum length is 100.
postal_code
integer The postal code. This should be exactly 6 characters.
country
string The country. The minimum length is 2 and the maximum length is 64.
legal_info

object The legal details about the sub-merchant's business.

pan
string Valid PAN number details of the sub-merchant's business.
  • This is a 10-digit alphanumeric code. For example, AVOJB1111K.
  • The 4th digit should be either of 'C', 'H', 'F', 'A', 'T', 'B', 'J', 'G', 'L'.
  • The regex for Company PAN is /^[a-zA-z]{5}\d{4}[a-zA-Z]{1}$/.
    Handy Tip
    This parameter might be required to complete the KYC process. However, it is optional for this API.
gst
string Valid GSTIN number details of the sub-merchant.
  • This is a 15-digit PAN-based unique identification number.
  • The Regex for GSTIN is /^[0123][0-9][a-z]{5}[0-9]{4}[a-z][0-9][a-z0-9][a-z0-9]$/gi.
cin
string CIN is for Private Limited and Public Limited, whereas LLPIN is for LLP business type.
  • This is a 21-digit alpha-numeric number.
  • The Regex for CIN is /^([a-z]{3}-\d{4}|[ul]\d{5}[a-z]{2}\d{4}[a-z]{3}\d{6})$/i.
brand

object The branding details of the sub-merchant's business.

color
string The color code of sub-merchant's business brand. This is a 6-character hex code (Regex: [a-fA-F0-9]{6}).
notes

object Contains user-defined fields stored by the partner for reference purposes.

contact_name

string The name of the contact. The minimum length is 4 and the maximum length is 255 characters.

contact_info

object Options available for contact support.

chargeback

object The type of contact support.

email
string The email id of chargeback POC. The maximum length is:
  • local part (before @): 64 characters.
  • domain part (after @): 68 characters.
    The total character length supported is 132.
phone
integer The phone number of chargeback POC. The maximum length is 10 characters.
policy_url
string The URL of chargeback policy. Regex is (protocol://:port/resource path?querystring#fragementid)
protocol-both http/https allowed. Only domain name is mandatory.
refund

object The type of contact support.

email
string The email id of refund POC. The maximum length is:
  • local part (before @): 64 characters.
  • domain part (after @): 68 characters.
    The total character length supported is 132.
phone
integer The phone number of refund POC. The maximum length is 10 characters.
policy_url
string The URL of refund policy. Regex is (protocol://:port/resource path?querystring#fragementid)
protocol-both http/https allowed.
support

array The type of contact support.

email
string The email id of support POC. The maximum length is:
  • local part (before @): 64 characters.
  • domain part (after @): 68 characters.
    The total character length supported is 132.
phone
integer The phone number of support POC. The maximum length is 10 characters.
policy_url
string The URL of support policy. Regex is (protocol://:port/resource path?querystring#fragementid)
protocol-both http/https allowed.
apps

object The app details of the sub-merchant's business

websites

array The website/app for the sub-merchant's business. A minimum of 1 website is required.

android

array Android app details

url
string The link of the Android app. Regex is (protocol://:port/resource path?querystring#fragementid)
protocol-both http/https allowed.
name
string The name of the Android app.
ios

array iOS app details

url
string The link of the iOS app. Regex is (protocol://:port/resource path?querystring#fragementid)
protocol-both http/https allowed.
name
string The name of the iOS app.

Create an Account🔗

Use the following API endpoint to create an account:

/accounts/

Request Parameters🔗

emailmandatory

string The sub-merchant's business email address.

phonemandatory

integer The sub-merchant's business phone number. The minimum length is 8 characters and the maximum length is 15.

legal_business_name mandatory

string The name of the sub-merchant's business. For example, Acme Corp. The minimum length is 4 characters and the maximum length is 200.

customer_facing_business_name optional

string The sub-merchant billing label as it appears on the Razorpay Dashboard. The minimum length is 1 character and the maximum length is 255.

business_type mandatory

string The type of business operated by the sub-merchant. List of possible values are available here.

reference_id optional

string Partner's external account reference id. The minimum length is 1 character and the maximum length is 512.

profile

object The business details of the sub-merchant's account.

category mandatory

string The business category of the sub-merchant. Possible values:List of Business Categories.

sub-category mandatory

string The business sub-category of the sub-merchant. Possible values: List of Business Sub-Categories.

description deprecated

string This parameter has been deprecated. Pass the description using the business_model parameter.

business_model

string The business description. The character limit between 50-255 characters.

addresses

object Details of sub-merchant's address.

operation optional

object Details of the sub-merchant's operational address.

street1
string Address, line 1. The maximum length is 100 characters.
street2
string Address, line 2. The maximum length is 100 characters.
city
string The city. The maximum length is 100 characters.
state
string The state. The minimum length is 2 and the maximum length is 32.
postal_code
integer The postal code. This should be exactly 6 characters.
country
string The country. The minimum length is 2 and the maximum length is 64.
registered mandatory

object Details of the sub-merchant's registered address.

street1
string Address, line 1. The maximum length is 100 characters.
street2
string Address, line 2. The maximum length is 100 characters.
city
string The city. The maximum length is 100 characters.
state
string The state. The minimum length is 2 and the maximum length is 32.
postal_code
integer The postal code. This should be exactly 6 characters.
country
string The country. The minimum length is 2 and the maximum length is 64.
legal_info optional

object The legal details about the sub-merchant's business.

pan optional
string Valid PAN number details of the sub-merchant's business.
  • This is a 10-digit alphanumeric code. For example, AVOJB1111K.
  • The 4th digit should be either of 'C', 'H', 'F', 'A', 'T', 'B', 'J', 'G', 'L'.
  • The regex for Company PAN is /^[a-zA-z]{5}\d{4}[a-zA-Z]{1}$/.
gst optional
string Valid GSTIN number details of the sub-merchant.
  • This is a 15-digit PAN-based unique identification number.
  • The Regex for GSTIN is /^[0123][0-9][a-z]{5}[0-9]{4}[a-z][0-9][a-z0-9][a-z0-9]$/gi.
cin optional
string CIN is for Private Limited and Public Limited, whereas LLPIN is for LLP business type.
  • This is a 21-digit alpha-numeric number.
  • The Regex for CIN is /^([a-z]{3}-\d{4}|[ul]\d{5}[a-z]{2}\d{4}[a-z]{3}\d{6})$/i.
brand optional

object The branding details of the sub-merchant's business.

color optional
string The color code of sub-merchant's business brand. This is a 6-character hex code (Regex: [a-fA-F0-9]{6}).
notes optional

object Contains user-defined fields stored by the partner for reference purposes.

contact_name mandatory

string The name of the contact. The minimum length is 4 and the maximum length is 255 characters.

contact_info optional

object Options available for contact support.

chargeback

object The type of contact support.

email optional
string The email id of chargeback POC. The maximum length is:
  • local part (before @): 64 characters.
  • domain part (after @): 68 characters.
    The total character length supported is 132.
phone optional
string The phone number of chargeback POC. The minimum length is 8 and the maximum length is 10 characters.
policy_url optional
string The URL of chargeback policy.
refund

object The type of contact support.

email optional
string The email id of refund POC. The maximum length is:
  • local part (before @): 64 characters.
  • domain part (after @): 68 characters.
    The total character length supported is 132.
phone optional
string The phone number of refund POC. The minimum length is 8 and the maximum length is 10 characters.
policy_url optional
string The URL of refund policy.
support

object The type of contact support.

email optional
string The email id of support POC. The maximum length is:
  • local part (before @): 64 characters.
  • domain part (after @): 68 characters.
    The total character length supported is 132.
phone optional
string The phone number of support POC. The minimum length is 8 and the maximum length is 10 characters.
policy_url optional
string The URL of support policy.
apps optional

object The website/app details of the sub-merchant's business.

websites optional

array The websites for the sub-merchant's business. A minimum of 1 website is required.

android optional

array Android app details

urloptional
string The link of the Android app. Regex is (protocol://:port/resource path?querystring#fragementid)
protocol-both http/https allowed.
name optional
string The name of the Android app.
ios optional

array iOS app details

url optional
string The link of the iOS app. Regex is (protocol://:port/resource path?querystring#fragementid)
protocol-both http/https allowed.
name optional
string The name of the iOS app.

Response Parameters🔗

The response parameters consists of the request parameters and the following two parameters:

type
string The account type. Possible value is standard.
status
string The status of the account. Possible values:
  • created
  • suspended

Fetch an Account🔗

Use the following endpoint to retrieve the details of an account:

/accounts/:account_id

Path Parameters🔗

account_id mandatory
string The unique identifier of a sub-merchant account generated by Razorpay. For example, acc_GP4lfNA0iIMn5B.

Update an Account🔗

The information you can update using the Update an Account API differs based on the product activation status.

Activation Status

Update Permitted

requested

You can update the details for all the fields.

needs_clarification

The fields you can update depend on the reason_code mentioned in the requirements object in the Request a Product Activation API:

  • 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_review

You cannot update any fields.

activated

You cannot use this API to update any fields as your account is already active.

Use the following endpoint to update the details of a sub-merchant account:

/accounts/:account_id

Currently, we do not support making concurrent requests to the following Onboarding APIs including their combination on the same account_id:

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

Path Parameter🔗

account_id mandatory
string The unique identifier of a sub-merchant account generated by Razorpay. For example, acc_GP4lfNA0iIMn5B.

Request Parameters🔗

phoneoptional

integer The sub-merchant's business phone number.

legal_business_name optional

string The name of the sub-merchant's business. For example, Acme Corp. The minimum length is 4 characters and the maximum length is 200.

customer_facing_business_name optional

string The sub-merchant billing label as it appears on the Razorpay Dashboard. The minimum length is 1 character and the maximum length is 255.

profile

object The business details of the sub-merchant's account.

description deprecated

string This parameter has been deprecated. Pass the description using the business_model parameter.

business_model

string The business description. The character limit is between 50-255 characters.

addresses

object Details of sub-merchant's address.

operation optional

object Details of the sub-merchant's operational address.

street1
string Address, line 1. The maximum length is 100 characters.
street2
string Address, line 2. The maximum length is 100 characters.
city
string The city. The maximum length is 100 characters.
state
string The state. The minimum length is 2 and the maximum length is 32.
postal_code
integer The postal code. This should be exactly 6 characters.
country
string The country. The minimum length is 2 and the maximum length is 64.
registeredoptional

object Details of the sub-merchant's registered address.

street1
string Address, line 1. The maximum length is 100 characters.
street2
string Address, line 2. The maximum length is 100 characters.
city
string The city. The maximum length is 100 characters.
state
string The state. The minimum length is 2 and the maximum length is 32.
postal_code
integer The postal code. This should be exactly 6 characters.
country
string The country. The minimum length is 2 and the maximum length is 64.
legal_info optional

object The legal details about the sub-merchant's business.

pan optional
string Valid PAN number details of the sub-merchant's business.
  • This is a 10-digit alphanumeric code. For example, AVOJB1111K.
  • The 4th digit should be either of 'C', 'H', 'F', 'A', 'T', 'B', 'J', 'G', 'L'.
  • The regex for Company PAN is /^[a-zA-z]{5}\d{4}[a-zA-Z]{1}$/.
gst optional
string Valid GSTIN number details of the sub-merchant.
  • This is a 15-digit PAN-based unique identification number.
  • The Regex for GSTIN is /^[0123][0-9][a-z]{5}[0-9]{4}[a-z][0-9][a-z0-9][a-z0-9]$/gi.
cin optional
string CIN is for Private Limited and Public Limited, whereas LLPIN is for LLP business type.
  • This is a 21-digit alpha-numeric number.
  • The Regex for CIN is /^([a-z]{3}-\d{4}|[ul]\d{5}[a-z]{2}\d{4}[a-z]{3}\d{6})$/i.
brand optional

object The branding details of the sub-merchant's business.

color optional
string The color code of sub-merchant's business brand. This is a 6-char hex code (Regex: [a-fA-F0-9]{6}).
notes optional

object Contains user-defined fields stored by the partner for reference purposes.

contact_name mandatory

string The name of the contact. The minimum length is 4 and the maximum length is 255 characters.

contact_info optional

object Options available for contact support.

chargeback

object The type of contact support.

email optional
string The email id of chargeback POC.
phone optional
string The phone number of chargeback POC. The minimum length is 8 and the maximum length is 10 characters.
policy_url optional
string The URL of chargeback policy. Regex is (protocol://:port/resource path?querystring#fragementid)
protocol-both http/https allowed.
refund

object The type of contact support.

email optional
string The email id of refund POC.
phone optional
string The phone number of refund POC. The minimum length is 8 and the maximum length is 10 characters.
policy_url optional
string The URL of refund policy. Regex is (protocol://:port/resource path?querystring#fragementid)
protocol-both http/https allowed.
support

object The type of contact support.

email optional
string The email id of support POC.
phone optional
string The phone number of support POC. The minimum length is 8 and the maximum length is 10 characters.
policy_url optional
string The URL of support policy. Regex is (protocol://:port/resource path?querystring#fragementid)
protocol-both http/https allowed.
apps optional

object The website/app details of the sub-merchant's business.

websites optional

array The websites for the sub-merchant's business. A minimum of 1 website is required.

android optional

array Android app details

urloptional
string The link of the Android app. Regex is (protocol://:port/resource path?querystring#fragementid)
protocol-both http/https allowed.
name optional
string The name of the Android app.
ios optional

array iOS app details

url optional
string The link of the iOS app. Regex is (protocol://:port/resource path?querystring#fragementid)
protocol-both http/https allowed.
name optional
string The name of the iOS app.

Error Response Parameters🔗

Know about the various error responses for this API.

Delete an Account🔗

Use the following endpoint to delete the sub-merchant account:

/accounts/:account_id

Path Parameter🔗

account_id mandatory
string The unique identifier of a sub-merchant account that must be deleted. For example, acc_GPaClllZWaPBfv.

Response Parameters🔗

status
string The status of the account changes to suspended.
suspended_at
integer Timestamp, in Unix format, at which the account will be suspended.
×