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

Stakeholder APIs

You can use the Stakeholders APIs to add a stakeholder for an account. Each stakeholder will have their KYC.

Handy Tip
A stakeholder can be a signatory or an owner of the business.

You can create, fetch and update stakeholders using these APIs.

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

Run in Postman

Stakeholders Entity๐Ÿ”—

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

id

string The unique identifier of a stakeholder generated by Razorpay, used to fetch or update a stakeholder. For example, sth_GLGgm8fFCKc92m. Maximum length supported is 18 characters.

entity

string Here it is stakeholder.

percentage_ownership

float The stakeholder's ownership of the business in percentage. Only two decimal places are allowed. For example, 87.55. The maximum length is 100 characters.

name

string The stakeholder's name as per the PAN card. The maximum length is 255 characters.

email

string The stakeholder's email address. The maximum length is:

  • local part (before @): 64 characters.
  • domain part (after @): 68 characters.
    The total character length supported is 132.
relationship

object The stakeholder's relationship with the accountโ€™s business. The default value is false.

  • director: This attribute is set to true if the stakeholder is a director of the account's legal entity. By default, it is set to false.
  • executive: This attribute is set to true if the stakeholder is an executive of the account's legal entity. By default, it is set to false.
phone

object The stakeholder's phone number.

primary
integer The primary contact number of the stakeholder. The minimum length is 8 characters and the maximum length is 11.
secondary
integer The secondary contact number of the stakeholder. The minimum length is 8 characters and the maximum length is 11.
addresses

object Details of stakeholder's address.

residential

string Details of the stakeholder's residential address.

street
string The stakeholder's street address. The minimum length is 10 characters and maximum length is 255.
city
string The city. The minimum length is 2 and maximum length is 32.
state
string The state. The minimum length is 2 and maximum length is 32.
postal_code
string The postal code. The minimum length is 2 and maximum length is 10.
country
string The country. The minimum length is 2 and maximum length is 64.
kyc

object The type of document required to establish the stakeholder's identity.

pan
string The PAN number of the stakeholder.
  • This is a 10-digit alphanumeric code. For example, AVOPB1111K.
  • Regex for Stakeholder PAN: /^[a-zA-z]{5}\d{4}[a-zA-Z]{1}$/
  • Validation for Stakeholder PAN: The 4th digit should be 'P'.
    Handy Tip
    To complete the KYC process, this API parameter might be required, but it is optional for this API.
notes

object Contains user-defined fields stored by the partner for reference purposes. It can hold a maximum of 15 key-value pairs, 512 characters (maximum) each. For example, "note_key": "Beam me up Scottyโ€.

Create a Stakeholder๐Ÿ”—

Use the following API endpoint to create a stakeholder:

/accounts/:account_id/stakeholders

Handy Tip
A stakeholder can be a signatory or an owner of the business.

Path Parameter๐Ÿ”—

account_id
string The unique identifier of the sub-merchant account generated by Razorpay. For example, acc_GLGeLkU2JUeyDZ. This id is used to fetch or update a stakeholder. The stakeholder is created for this sub-merchant account id.

Request Parameters๐Ÿ”—

name mandatory

string The stakeholder's name as per the PAN card. The maximum length is 255 characters.

email

string The stakeholder's email address. The maximum length is:

  • local part (before @): 64 characters.
  • domain part (after @): 68 characters.
    The total character length supported is 132.
percentage_ownershipoptional

float The stakeholder's ownership of the business in percentage. Only two decimal places are allowed. For example, 87.55. The maximum length is 100 characters.

relationship optional

boolean The stakeholder's relationship with the accountโ€™s business. The default value is false.

  • director: This attribute is set to true if the stakeholder is a director of the account's legal entity. By default, it is set to false.
  • executive: This attribute is set to true if the stakeholder is an executive of the account's legal entity. By default, it is set to false.
phone optional

object The stakeholder's phone number.

primaryoptional
integer The primary contact number of the stakeholder. The minimum length is 8 characters and the maximum length is 11.
secondaryoptional
integer The secondary contact number of the stakeholder. The minimum length is 8 characters and the maximum length is 11.
addresses optional

object Details of stakeholder's address.

residential

object Details of the stakeholder's residential address.

street optional
string The stakeholder's street address. The minimum length is 10 characters and maximum length is 255.
city optional
string The city. The minimum length is 2 and maximum length is 32.
state optional
string The state. The minimum length is 2 and maximum length is 32.
postal_code optional
string The postal code. The minimum length is 2 and maximum length is 10.
country optional
string The country. The minimum length is 2 and maximum length is 64.
kyc conditional

object The type of document required to establish the stakeholder's identity.

pan
string The PAN number of the stakeholder.
  • This is a 10-digit alphanumeric code. For example, AVOPB1111K.
  • Regex for Stakeholder PAN: /^[a-zA-z]{5}\d{4}[a-zA-Z]{1}$/.
  • Validation for Stakeholder PAN: The 4th digit should be 'P'.
notes optional

object Contains user-defined fields stored by the partner for reference purposes. Maximum 15 key-value pairs, 512 characters (maximum) each.

Response Parameters๐Ÿ”—

id
string The unique identifier of the stakeholder whose details are created. For example, sth_GLGgm8fFCKc92m.

Fetch a Stakeholder๐Ÿ”—

Use the following endpoint to retrieve the details of a stakeholder:

/accounts/:account_id/stakeholders/:stakeholder_id

Path Parameters๐Ÿ”—

account_id mandatory
string The unique identifier of a sub-merchant account generated by Razorpay. For example, acc_GLGeLkU2JUeyDZ.
id
string The unique identifier of the stakeholder whose details are to be fetched. For example, sth_GOQ4Eftlz62TSL.

Fetch all Stakeholders๐Ÿ”—

Use the following endpoint to retrieve all stakeholders for a given account:

/accounts/:account_id/stakeholders

Path Parameter๐Ÿ”—

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

Update a Stakeholder๐Ÿ”—

The information you can update for a stakeholder using the Update a Stakeholder 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 stakeholder:

/accounts/:account_id/stakeholders/:stakeholder_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_GLGeLkU2JUeyDZ
id mandatory
string The unique identifier of the stakeholder whose details are to be updated. For example, sth_GOQ4Eftlz62TSL

Request Parameters๐Ÿ”—

percentage_ownershipoptional

float The stakeholder's ownership of the business in percentage. Only two decimal places are allowed. For example, 87.55. The maximum length is 100 characters.

name optional

string The stakeholder's name as per the PAN card. The maximum length is 255 characters.

relationship optional

boolean The stakeholder's relationship with the accountโ€™s business. The default value is false.

  • director: This attribute is set to true if the stakeholder is a director of the account's legal entity. By default, it is set to false.
  • executive: This attribute is set to true if the stakeholder is an executive of the account's legal entity. By default, it is set to false.
phone optional

object The stakeholder's phone number.

primaryoptional
integer The primary contact number of the stakeholder. The minimum length is 8 characters and the maximum length is 11.
secondaryoptional
integer The secondary contact number of the stakeholder. The minimum length is 8 characters and the maximum length is 11.
addresses optional

object Details of stakeholder's address.

residential

object Details of the stakeholder's residential address.

street optional
string The stakeholder's street address. The minimum length is 10 characters and maximum length is 255.
city optional
string The city. The minimum length is 2 and maximum length is 32.
state optional
string The state. The minimum length is 2 and maximum length is 32.
postal_code optional
string The postal code. The minimum length is 2 and maximum length is 10.
country optional
string The country. The minimum length is 2 and maximum length is 64.
kyc conditional

object The type of document required to establish the stakeholder's identity.

pan
string The PAN number of the stakeholder.
  • This is a 10-digit alphanumeric code. For example, AVOPB1111K.
  • Regex for Stakeholder PAN: /^[a-zA-z]{5}\d{4}[a-zA-Z]{1}$/.
  • Validation for Stakeholder PAN: The 4th digit should be 'P'.
notes optional

object Contains user-defined fields stored by the partner for reference purposes. Maximum 15 key-value pairs, 512 characters (maximum) each.

×