> ## Documentation Index
> Fetch the complete documentation index at: https://razorpay-881012b3.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a Linked Account (Composite)
> Create a Linked Account with settlement destination in a single atomic API call using Razorpay Route Composite API.
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.
```bash UPI (VPA) theme={null}
curl -X POST https://api.razorpay.com/v2/accounts \
-u [YOUR_KEY_ID]:[YOUR_SECRET] \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 53cda91c-8f81-4e77-bbb9-7388f4ac6bf4" \
-d '{
"type": "route",
"tnc_accepted": true,
"reference_id": "Vendor_lvr_88421",
"legal_business_name": "Ravi Kumar",
"business_type": "individual",
"email": "ravi.kumar@example.com",
"phone": "+919876543210",
"legal_info": {
"pan": "AAACL1234C"
},
"notes": {
"property_id": "BLR_HSR_42B",
"city": "Bengaluru"
},
"settlement_accounts": [
{
"method": "upi",
"upi": {
"vpa": "ravi.kumar@okhdfcbank",
"beneficiary_name": "Ravi Kumar",
"currency": "INR",
"is_default": true
}
}
]
}'
```
```bash Bank Account theme={null}
curl -X POST https://api.razorpay.com/v2/accounts \
-u [YOUR_KEY_ID]:[YOUR_SECRET] \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 7a3e1f9c-22ab-4d11-8e9a-3c8b91d6f201" \
-d '{
"type": "route",
"tnc_accepted": true,
"reference_id": "Vendor_lvr_88422",
"legal_business_name": "Priya Sharma",
"business_type": "individual",
"email": "priya@example.com",
"phone": "+919812345678",
"legal_info": {
"pan": "BCEDP5678Q"
},
"notes": {
"property_id": "BLR_KOR_17A",
"city": "Bengaluru"
},
"settlement_accounts": [
{
"method": "bank_account",
"bank_account": {
"account_number": "1234567890123456",
"beneficiary_name": "Priya Sharma",
"code_type": "ifsc",
"code": "HDFC0000317",
"currency": "INR",
"is_default": true
}
}
]
}'
```
```json Success (UPI) theme={null}
{
"id": "acc_GLGeLkU2JUeyDZ",
"entity": "linked_account",
"type": "route",
"reference_id": "Vendor_lvr_88421",
"status": "created",
"business_type": "individual",
"legal_business_name": "Ravi Kumar",
"customer_facing_business_name": "Ravi Kumar",
"email": "ravi.kumar@example.com",
"phone": "+919876543210",
"legal_info": {
"pan": "AAACL1234C"
},
"product_config": {
"id": "acc_prd_K1eopFF8G21tux",
"entity": "product",
"product_name": "route",
"activation_status": "activated",
"active_configuration": {
"settlement_accounts": [
{
"id": "sa_M1a2b3c4d5e6f7g8",
"entity": "settlement_account",
"method": "upi",
"upi": {
"vpa": "ravi.kumar@okhdfcbank",
"beneficiary_name": "Ravi Kumar",
"currency": "INR",
"is_default": true
},
"verification_status": "verified",
"verified_at": 1708445520,
"active": true
}
]
}
},
"tnc": {
"id": "tnc_K1eopApuHyBE7D",
"accepted": true,
"accepted_at": 1708445500
},
"notes": {},
"created_at": 1708445500
}
```
```json Success (Bank Account) theme={null}
{
"id": "acc_GLGeognbHVDkDZ",
"entity": "linked_account",
"type": "route",
"reference_id": "Vendor_lvr_88422",
"status": "created",
"business_type": "individual",
"legal_business_name": "Priya Sharma",
"customer_facing_business_name": "Priya Sharma",
"email": "priya@example.com",
"phone": "+919812345678",
"legal_info": {
"pan": "BCEDP5678Q"
},
"product_config": {
"id": "acc_prd_K1eopGG9H32uvy",
"entity": "product",
"product_name": "route",
"activation_status": "activated",
"active_configuration": {
"settlement_accounts": [
{
"id": "sa_M1a2b3c4d5e6f7g9",
"entity": "settlement_account",
"method": "bank_account",
"bank_account": {
"account_number": "XXXXXXXXXXXXXX56",
"beneficiary_name": "Priya Sharma",
"code_type": "ifsc",
"code": "HDFC0000317",
"currency": "INR",
"is_default": true
},
"verification_status": "pending",
"active": true
}
]
}
},
"tnc": {
"id": "tnc_K1eopBqvIzCF8E",
"accepted": true,
"accepted_at": 1708445600
},
"notes": {
"property_id": "BLR_KOR_17A",
"city": "Bengaluru"
},
"created_at": 1708445600
}
```
```json Failure theme={null}
{
"error": {
"code": "BAD_REQUEST_ERROR",
"description": "Invalid VPA. Please enter a valid Virtual Payment Address",
"source": "api",
"step": "validation",
"reason": "invalid_vpa_format",
"field": "settlement_accounts[0].upi.vpa",
"metadata": {
"reference_id": "Vendor_lvr_88421",
"idempotency_key": "53cda91c-8f81-4e77-bbb9-7388f4ac6bf4"
}
}
}
```
## Request Parameters
Fixed value: `route`.
Determines whether the terms and conditions are accepted or not. Possible values: `true`/`false`.
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.
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.
The type of business operated by the Linked Account holder. List of possible values are available [here](/docs/payments/route/integration-guide#business-type).
Linked Account holder's email. Required only if Dashboard access is needed.
The Linked Account's business phone number. The minimum length is 8 characters and the maximum length is 15. Optionally prefixed with `+`. For example, `+919876543210`.
The legal details about the Linked Account's business. The mandatory [KYC requirement](/docs/payments/route/integration-guide#kyc-requirements) parameters should be passed depending on the business requirements.
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.
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`.
21-character CIN. Required for registered vendor companies.
Public "doing business as" name. Defaults to `legal_business_name`.
Merchant-side metadata. Maximum 15 key-value pairs. Useful for tagging vendors by property, city, or cohort.
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.
Stakeholder's full legal name.
Stakeholder's email address.
Stakeholder's phone numbers (`primary` and `secondary`).
Stakeholder's PAN. Mandatory if the `stakeholder` object is supplied.
Stakeholder's addresses (`registered`, `residential`).
Stakeholder-level merchant metadata.
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`.
Settlement method. Possible values: `upi`, `bank_account`.
Required when `method` is `upi`.
Vendor's UPI Virtual Payment Address. Format: `username@psp`. The VPA must be validated and active on the vendor's UPI app before submission.
Name registered with the VPA. Must match the UPI registry.
Currency code. Currently supports `INR`.
Must be `true`. We currently support only 1 method per settlement account.
Required when `method` is `bank_account`.
Bank account number. 5–20 characters.
Account holder name.
Routing code type. Currently supports `ifsc`.
IFSC code. 11 characters, format `AAAA0XXXXXX`.
Currency code. Currently supports `INR`.
Must be `true`. We currently support only 1 method per settlement account.
## Response Parameters
Unique identifier of the Linked Account generated by Razorpay. For example, `acc_GLGeLkU2JUeyDZ`.
Entity type. Value: `linked_account`.
Account type. Value: `route`.
The merchant-controlled external ID passed in the request.
Account status. Value at creation: `created`. Transfers can be initiated immediately once the account is in `created` status.
Business type of the Linked Account holder.
Legal name of the Linked Account's business.
Public "doing business as" name of the Linked Account's business.
Linked Account holder's email address.
Linked Account holder's phone number.
Legal identifiers of the Linked Account.
PAN of the Linked Account.
Present only if a `stakeholder` object was supplied in the request.
Unique identifier of the stakeholder entity.
Entity type. Value: `stakeholder`.
Stakeholder's full legal name.
Unix timestamp of stakeholder creation.
Product configuration created atomically along with the account.
Unique identifier of the product configuration.
Entity type. Value: `product`.
Product name. Value: `route`.
Activation status of the product configuration.
Active settlement configuration.
List of settlement destinations on the product configuration.
Unique identifier of the settlement account. For example, `sa_M1a2b3c4d5e6f7g8`.
Entity type. Value: `settlement_account`.
Settlement method. Possible values: `upi`, `bank_account`. Bank account numbers are returned masked, showing only the last 2 characters. For example, `XXXXXXXXXXXXXX56`.
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`.
Unix timestamp when the settlement destination was verified. Present only once `verification_status` is `verified`.
Indicates whether the settlement destination is active.
Terms and Conditions acceptance details.
Unique identifier of the T\&C record.
Indicates whether T\&C have been accepted. Value: `true`.
Unix timestamp of T\&C acceptance.
Merchant-side metadata passed in the request.
Unix timestamp of account creation.
## Errors
**Code:** `400`
This 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:** `400`
This error occurs when the `settlement_accounts` array is absent from the request body.
**Solution:** Add exactly one settlement account object to the array.
**Code:** `400`
This error occurs when `settlement_accounts` is present but is an empty array.
**Solution:** Add exactly one settlement account object to the array.
**Code:** `400`
This 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:** `400`
This 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:** `400`
This 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:** `400`
This 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:** `400`
This error occurs when `tnc_accepted` is missing or set to `false`.
**Solution:** Set `tnc_accepted` to `true`.
**Code:** `400`
This 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:** `409`
This 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:** `409`
This 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:** `400`
This error occurs when `legal_info.gst` is not a valid 15-character GSTIN.
**Solution:** Validate the GSTIN format on your side before submission.
**Code:** `400`
This 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:** `400`
This 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:** `400`
This error occurs when `legal_business_name` is shorter than 4 characters or longer than 200 characters.
**Solution:** Ensure `legal_business_name` is between 4 and 200 characters.
**Code:** `400`
This 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:** `400`
This 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:** `400`
This error occurs when `settlement_accounts[].method` is not one of the supported values.
**Solution:** Use `bank_account` or `upi` as the settlement method.
**Code:** `400`
This 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:** `400`
This error occurs when the VPA is not in the `username@psp` format.
**Solution:** Validate the VPA format on your side before submission.
**Code:** `400`
This 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:** `400`
This error occurs when `settlement_accounts[].upi.currency` or `settlement_accounts[].bank_account.currency` is not `INR`.
**Solution:** Pass `INR` as the currency value.
**Code:** `400`
This 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:** `422`
This 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:** `422`
This 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:** `422`
This 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:** `403`
This 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:** `401`
This 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:** `409`
This 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:** `429`
This 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:** `500`
This 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`.