Skip to main content
POST
Available in🇮🇳 India
Use this endpoint to create a Linked Account along with its settlement destination in a single atomic call. This composite flow collapses the previous four-step onboarding flow (Create Linked Account → Create Stakeholder → Request Product Configuration → Update Product Configuration) into one request. When the settlement_accounts array is present in the request body, the endpoint runs in composite mode and atomically creates the linked account, product configuration (Route), and settlement account. If any part fails, nothing is persisted — there is no half-onboarded state to reconcile.
Watch Out!
  • UPI (VPA) settlement accounts can be created only with live mode API keys. Requests with test mode keys fail. Bank account settlement accounts work in both test and live modes, so use method: bank_account to test your integration.
  • VPA Settlements must be enabled on your account before you pass method: upi. Refer to the VPA Settlements prerequisites.
Handy TipsThis is the Route Linked Account composite API, POST /v2/accounts. It is different from the RazorpayX Composite Payout API, POST /v1/payouts. Make sure your requests go to POST /v2/accounts.

​
Minimum Request for an Individual

When business_type is individual, the legal_info and stakeholder objects are optional. Registered business types, such as partnership, llp and private_limited, must also pass the company PAN in legal_info.pan. The following request body creates a Linked Account that settles to a VPA:
settlement_accounts is a top-level field. If you add a stakeholder object, close it before settlement_accounts. A field placed inside the wrong object is reported as missing.

​
Request Parameters

​
string
required
Fixed value: route.
​
boolean
required
Determines whether the terms and conditions are accepted or not. Possible values: true/false.
​
string
required
Partner’s external account reference id. The minimum length is 1 character and the maximum length is 512. Must be unique per parent merchant account. Used as the idempotency anchor.
​
string
required
Legal name of the individual or business as on PAN and settlement bank account. The minimum length is 4 characters and the maximum length is 200.
​
string
required
The type of business operated by the Linked Account holder. List of possible values are available here.
​
string
Linked Account holder’s email. Required only if Dashboard access is needed.
​
string
The Linked Account’s business phone number. The minimum length is 8 characters and the maximum length is 15. Optionally prefixed with +<country code>. For example, +919876543210 or 9876543210.This limit applies to this top-level phone field only. The stakeholder’s phone number has a different format. Refer to stakeholder.phone.primary.
​
object
The legal details about the Linked Account’s business. Required for registered business types, such as partnership, llp, private_limited, public_limited, trust and society, to carry the company PAN in legal_info.pan.Omit this object when business_type is individual. Refer to the minimum request for an individual.
​
string
required
The company PAN of the Linked Account’s business. Mandatory if the legal_info object is supplied.
  • 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}$/.
  • The business_type is validated against the PAN type.
​
string
Valid GSTIN number details of the Linked Account. Required for vendor companies with annual turnover above ₹20 lakh.
  • 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.
​
string
21-character CIN. Required for registered vendor companies.
​
string
Public “doing business as” name. Defaults to legal_business_name.
​
object
Merchant-side metadata. Maximum 15 key-value pairs. Useful for tagging vendors by property, city or cohort.
​
object
Stakeholder entity, persisted in the same atomic transaction as the linked account and product config. Reserved for parent merchants with regulated downstream KYC obligations.This object is optional, including when business_type is individual. If you pass it, close it before settlement_accounts. The settlement_accounts array is a top-level field and must not be nested inside stakeholder.
​
string
Stakeholder’s full legal name.
​
string
Stakeholder’s email address.
​
object
Stakeholder’s phone numbers.
​
integer
The stakeholder’s primary contact number. The minimum length is 8 digits and the maximum length is 11. Pass the number without the + sign. For example, 9876543210.
​
integer
The stakeholder’s secondary contact number. The minimum length is 8 digits and the maximum length is 11.
​
object
The stakeholder’s identity document details.
​
string
Stakeholder’s PAN. Mandatory if the stakeholder object is supplied. The 4th character must be P.
​
object
Stakeholder’s addresses. Only residential is supported. There is no registered address for a stakeholder. Pass the business’s registered address in profile.addresses.registered, as in the Create a Linked Account API.
​
object
Stakeholder’s residential address.
​
string
The stakeholder’s street address. The minimum length is 10 characters and the maximum length is 255. The field is street, not street1.
​
string
The city. The minimum length is 2 characters and the maximum length is 32.
​
string
The state. The minimum length is 2 characters and the maximum length is 32.
​
string
The postal code. The minimum length is 2 characters and the maximum length is 10.
​
string
The country code in capital letters or the full country name in lower case. For example, IN or india.
​
object
Stakeholder-level merchant metadata.
​
array
required
Array of settlement destinations. We currently support only 1 method per settlement account, so this array must contain exactly one entry. Sending more than one entry returns 400 BAD_REQUEST with reason: feature_not_enabled.
​
string
required
Settlement method. Possible values: upi, bank_account.
​
object
Required when method is upi.
​
string
required
Vendor’s UPI Virtual Payment Address. Format: username@psp. The VPA must be validated and active on the vendor’s UPI app before submission.
​
string
required
Name registered with the VPA. Must match the UPI registry.
​
string
required
Currency code. Currently supports INR.
​
boolean
required
Must be true. We currently support only 1 method per settlement account.
​
object
Required when method is bank_account.
​
string
required
Bank account number. 5–20 characters.
​
string
required
Account holder name.
​
string
required
Routing code type. Currently supports ifsc.
​
string
required
IFSC code. 11 characters, format AAAA0XXXXXX.
​
string
required
Currency code. Currently supports INR.
​
boolean
required
Must be true. We currently support only 1 method per settlement account.

​
Response Parameters

​
string
Unique identifier of the Linked Account generated by Razorpay. For example, acc_GLGeLkU2JUeyDZ.
​
string
Entity type. Value: linked_account.
​
string
Account type. Value: route.
​
string
The merchant-controlled external ID passed in the request.
​
string
Account status. Value at creation: created. Transfers can be initiated immediately once the account is in created status.
​
string
Business type of the Linked Account holder.
​
string
Legal name of the Linked Account’s business.
​
string
Public “doing business as” name of the Linked Account’s business.
​
string
Linked Account holder’s email address.
​
string
Linked Account holder’s phone number.
​
object
Legal identifiers of the Linked Account.
​
string
PAN of the Linked Account.
​
object
Present only if a stakeholder object was supplied in the request.
​
string
Unique identifier of the stakeholder entity.
​
string
Entity type. Value: stakeholder.
​
string
Stakeholder’s full legal name.
​
integer
Unix timestamp of stakeholder creation.
​
object
Product configuration created atomically along with the account.
​
string
Unique identifier of the product configuration.
​
string
Entity type. Value: product.
​
string
Product name. Value: route.
​
string
Activation status of the product configuration.
​
object
Active settlement configuration.
​
array
List of settlement destinations on the product configuration.
​
string
Unique identifier of the settlement account. For example, sa_M1a2b3c4d5e6f7g8.
​
string
Entity type. Value: settlement_account.
​
string
Settlement method. Possible values: upi, bank_account. Bank account numbers are returned masked, showing only the last 2 characters. For example, XXXXXXXXXXXXXX56.
​
string
Verification status of the settlement destination. For UPI, this is synchronous and returns verified in the response. For bank accounts, verification happens asynchronously via penny drop (10–15 minutes) and the status starts as pending.
​
integer
Unix timestamp when the settlement destination was verified. Present only once verification_status is verified.
​
boolean
Indicates whether the settlement destination is active.
​
object
Terms and Conditions acceptance details.
​
string
Unique identifier of the T&C record.
​
boolean
Indicates whether T&C have been accepted. Value: true.
​
integer
Unix timestamp of T&C acceptance.
​
object
Merchant-side metadata passed in the request.
​
integer
Unix timestamp of account creation.

​
Errors

Code: 400This error occurs when a mandatory field is absent in the request body.Solution: Check the metadata.missing_fields array in the error response to identify and add the missing field. If the field is already in your request, check that the body is valid JSON, that every object is closed and that the field sits at the right level. For example, phone and settlement_accounts are top-level fields and are reported as missing if they are nested inside stakeholder. Also confirm that you are calling POST /v2/accounts and not the RazorpayX Composite Payout API.
Code: 400This error occurs when the settlement_accounts array is absent from the request body.Solution: Add exactly one settlement account object to the array.
Code: 400This error occurs when settlement_accounts is present but is an empty array.Solution: Add exactly one settlement account object to the array.
Code: 400This error occurs when more than one settlement destination is provided. We currently support only 1 method per settlement account.Solution: Send exactly one entry in settlement_accounts.
Code: 400This error occurs when the business_type value is not one of the supported enum values.Solution: Use one of the supported business_type values.
Code: 400This error occurs when the legal_info.pan value does not match the expected 10-character alphanumeric format.Solution: Validate the PAN format on your side before submission.
Code: 400This error occurs when the 4th character of the PAN (which encodes the entity type) conflicts with the provided business_type.Solution: Align the business_type with the entity encoded in the PAN.
Code: 400This error occurs when tnc_accepted is missing or set to false.Solution: Set tnc_accepted to true.
Code: 400This error occurs when the reference_id is shorter than 1 character or longer than 512 characters.Solution: Ensure reference_id is between 1 and 512 characters.
Code: 409This error occurs when the provided reference_id maps to an existing Linked Account under the same parent merchant.Solution: Check your mapping table. If the vendor was onboarded earlier, fetch the account using GET /v2/accounts/:account_id.
Code: 409This error occurs when the PAN has already been used to create a Linked Account.Solution: This is likely a previous onboarding attempt. Reconcile and reuse the existing account.
Code: 400This error occurs when legal_info.gst is not a valid 15-character GSTIN.Solution: Validate the GSTIN format on your side before submission.
Code: 400This error occurs when legal_info.gst is not provided for a vendor company whose declared turnover is above ₹20 lakh.Solution: Pass a valid legal_info.gst value for the vendor company.
Code: 400This error occurs when phone is not 8–15 digits, optionally prefixed with + and a country code.Solution: Validate the phone number format on your side before submission.
Code: 400This error occurs when a stakeholder object is passed without kyc.pan.Solution: Include a valid stakeholder.kyc.pan whenever the stakeholder object is supplied, or omit the stakeholder object entirely.
Code: 400This error occurs when stakeholder.kyc.pan does not match the expected 10-character alphanumeric PAN format.Solution: Validate the stakeholder PAN format on your side before submission.
Code: 400This error occurs when settlement_accounts[].method is not one of the supported values.Solution: Use bank_account or upi as the settlement method.
Code: 400This error occurs when settlement_accounts[].bank_account.account_number is shorter than 5 or longer than 20 characters.Solution: Ensure the account number is between 5 and 20 characters.
Code: 400This error occurs when the VPA is not in the username@psp format.Solution: Validate the VPA format on your side before submission.
Code: 400This error occurs when the IFSC code is not 11 characters or does not match the expected format.Solution: Validate the IFSC code on your side before submission.
Code: 400This error occurs when settlement_accounts[].upi.currency or settlement_accounts[].bank_account.currency is not INR.Solution: Pass INR as the currency value.
Code: 400This error occurs when more than one settlement destination for the same method is marked is_default: true.Solution: Ensure only one settlement destination per method has is_default set to true.
Code: 422This error occurs when the VPA cannot be found or has not been activated on the vendor’s UPI app.Solution: Prompt the vendor to verify and activate the VPA on their UPI app before resubmitting.
Code: 422This error occurs when the beneficiary_name provided does not match the name registered with the VPA or bank account.Solution: Re-confirm the exact name with the vendor and update the beneficiary_name accordingly.
Code: 422This error occurs asynchronously when the penny drop verification on settlement_accounts[].bank_account fails.Solution: Verify the account number and IFSC code with the vendor, then update the settlement account.
Code: 403This error occurs when the Route product has not been enabled on the parent platform account.Solution: Contact your Razorpay Integration Manager to enable Route on your parent account.
Code: 401This error occurs when the API credentials passed do not match the parent platform account’s credentials.Solution: Ensure you are using the parent platform account’s Key ID and Key Secret, not the Linked Account’s credentials.
Code: 409This error occurs when a previously used Idempotency-Key is sent again with a request body that does not match the original.Solution: Generate a new Idempotency-Key for a different request, or resend the exact original request body to get the cached response.
Code: 429This error occurs when the number of onboarding requests exceeds the allowed rate.Solution: Throttle requests on your side and retry after the duration specified in the Retry-After header.
Code: 500This error occurs due to a transient failure on Razorpay’s servers. Nothing is persisted for this request.Solution: Retry the request using the same Idempotency-Key.