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.

​
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.
​
object
required
The legal details about the Linked Account’s business. The mandatory KYC requirement parameters should be passed depending on the business requirements.
​
string
required
Valid PAN number details of the Linked Account’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}$/.
  • 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 such as individuals.
​
string
Stakeholder’s full legal name.
​
string
Stakeholder’s email address.
​
object
Stakeholder’s phone numbers (primary and secondary).
​
string
Stakeholder’s PAN. Mandatory if the stakeholder object is supplied.
​
object
Stakeholder’s addresses (registered, residential).
​
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.
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.