Skip to main content
POST
Available in🇮🇳 India🇲🇾 Malaysia🇸🇬 Singapore🇺🇸 United States
Use this endpoint to create a Linked Account.
Composite Onboarding AvailableYou can now create a Linked Account together with its settlement destination (UPI VPA or bank account) in a single atomic call. See Create a Linked Account (Composite) for details.
VPA (UPI id) as settlement destinationYou can create a Linked Account with a VPA (UPI id) as the settlement destination instead of a bank account. Funds are settled to the beneficiary’s UPI-linked bank account within a few minutes of a transfer being created. Refer to the VPA (UPI id) settlement request and response samples below.Before creating a VPA-based Linked Account, verify the VPA using the Validate VPA API. The verification response returns the account holder’s name, which you must match against your beneficiary records as a compliance requirement. Refer to Name Matching Requirements.
Watch Out!
  • The per-transaction limit for VPA settlements is ₹1,00,000 (set by NPCI). Transfers above this amount are rejected. Use bank account settlement for larger amounts.
  • A Linked Account can be configured with either a VPA or a bank account, not both. To support both settlement methods for the same beneficiary, create two separate Linked Accounts.
  • VPA Linked Accounts must be created individually. Batch upload does not support VPA as an account type.

​
Request Parameters

​
string
required
The Linked Account’s business email address.
​
integer
required
The Linked Account’s business phone number. The minimum length is 8 characters and the maximum length is 15.
​
string
required
The name of the Linked Account’s business. For example, Acme Corp. The minimum length is 4 characters and the maximum length is 200.
​
string
The Linked Account billing label as it appears on the Dashboard. The minimum length is 1 character and the maximum length is 255.
​
string
required
The type of business operated by the Linked Account holder. List of possible values are available here.
​
string
Partner’s external account reference id. The minimum length is 1 character and the maximum length is 512.
​
object
required
The business details of the Linked Account’s account.
​
string
required
The business category of the Linked Account. Possible values: List of Business Categories.
​
string
required
The business sub-category of the Linked Account. Possible values: List of Business Sub-Categories.
​
string
The business description. The character limit between 1-255 characters.
​
object
required
Details of Linked Account’s address.
​
object
required
Details of the Linked Account’s registered address.
​
string
Address, line 1. The maximum length is 100 characters.
​
string
Address, line 2. The maximum length is 100 characters.
​
string
The city. The maximum length is 100 characters.
​
string
The state. The minimum length is 2 and the maximum length is 32.
Below are the list of supported Indian states:
​
integer
The postal code. This should be exactly 6 characters.
​
string
The country. The minimum length is 2 and the maximum length is 64. This can either be a country code in capital letters or the full name of the country in lower case letters. For example, for India, you must write either IN or india.
​
object
Details of the Linked Account’s operational address.
​
string
Address, line 1. The maximum length is 100 characters.
​
string
Address, line 2. The maximum length is 100 characters.
​
string
The city. The maximum length is 100 characters.
​
string
The state. The minimum length is 2 and the maximum length is 32.
Below are the list of supported Indian states:
​
integer
The postal code. This should be exactly 6 characters.
​
string
The country. The minimum length is 2 and the maximum length is 64. This can either be a country code in capital letters or the full name of the country in lower case letters. For example, for India, you must write either IN or india.
​
object
The legal details about the Linked Account’s business. The mandatory KYC requirement parameters should be passed depending on the business requirements.
​
string
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}$/.
​
string
Valid GSTIN number details of the Linked Account.
  • 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.
​
object
Options available for contact support.
​
object
The type of contact support.
​
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.
​
integer
The phone number of chargeback POC. The maximum length is 10 characters.
​
string
The URL of chargeback policy. Regex is (protocol://razorpay.com:port/resource path?querystring#fragementid)
protocol-both http/https allowed. Only domain name is mandatory.
​
object
The type of contact support.
​
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.
​
integer
The phone number of refund POC. The maximum length is 10 characters.
​
string
The URL of refund policy. Regex is (protocol://razorpay.com:port/resource path?querystring#fragementid)
protocol-both http/https allowed.
​
array
The type of contact support.
​
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.
​
integer
The phone number of support POC. The maximum length is 10 characters.
​
string
The URL of support policy. Regex is (protocol://razorpay.com:port/resource path?querystring#fragementid)
protocol-both http/https allowed.
​
object
The app details of the account holder’s business.
​
array
The website/app for the account holder’s business. A minimum of 1 website is required.
​
array
Android app details
​
string
The link of the Android app. Regex is (protocol://razorpay.com:port/resource path?querystring#fragementid)
protocol-both http/https allowed.
​
string
The name of the Android app.
​
array
iOS app details
​
string
The link of the iOS app. Regex is (protocol://razorpay.com:port/resource path?querystring#fragementid)
protocol-both http/https allowed.
​
string
The name of the iOS app.
The following parameters are required only when you create a Linked Account with a VPA (UPI id) as the settlement destination, as shown in the VPA (UPI id) request sample above.
​
object
The settlement destination details for the Linked Account. Required for VPA-based Linked Accounts.
​
string
required
The type of settlement destination. Pass vpa to configure a UPI id as the settlement destination.
​
object
required
The VPA details of the beneficiary.
​
string
required
The beneficiary’s UPI id. The format is username@bankname. For example, gaurav.kumar@paytm or 9000090000@ybl. The maximum length is 100 characters.
​
object
The settlement configuration for the Linked Account. Required for VPA-based Linked Accounts.
​
string
required
The settlement schedule for the Linked Account. Pass instant for transaction-level instant settlement to the VPA. Instant settlement is the only supported mode for VPA-based Linked Accounts.
​
string
required
The banking mode used to process the payout. Pass imps for VPA settlements.

​
Response Parameters

​
string
The unique identifier of the account generated by Razorpay. The maximum length is 18 characters. For example, acc_GLGeLkU2JUeyDZ.
​
string
The account type. Possible value is route.
​
string
The internal reference ID. This value can be maximum of 20 characters. For example, 123123.
​
string
The status of the account. Possible values:
  • created
  • suspended
​
string
The account holder’s email address.
​
integer
The account holder’s phone number. The minimum length is 8 characters and the maximum length is 15.
​
string
The name of the account holder’s business. For example, Acme Corp. The minimum length is 4 characters and the maximum length is 200.
​
string
The type of business operated by the account holder. Possible values: Business Types.
​
object
The account holder’s business details.
​
string
The business category of the account holder. For example, healthcare. Possible values: Business Category.
​
string
The business sub-category of the account holder. For example, clinic. Possible values: Business Sub-Category.
​
object
Details of account holder’s address.
​
object
Details of the account holder’s registered address.
​
string
Address, line 1. The maximum length is 100 characters.
​
string
Address, line 2. The maximum length is 100 characters.
​
string
The city. The maximum length is 100 characters.
​
string
The state. The minimum length is 2 and the maximum length is 100.
​
integer
The postal code. This should be exactly 6 characters.
​
string
The country. The minimum length is 2 and the maximum length is 64. This can either be a country code in capital letters or the full name of the country in lower case letters. For example, for India, you must write either IN or india.
​
object
The legal details about the account holder’s business. The mandatory KYC requirement parameters should be passed depending on the business requirements.
​
string
Valid PAN number details of the account holder’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}$/.
This parameter might be required to complete the KYC process. However, it is optional for this API.
​
string
Valid GSTIN number details of the account holder.
  • 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.
​
object
Contains user-defined fields stored by the partner for reference purposes.
​
string
The name of the contact. The minimum length is 4 and the maximum length is 255 characters.
The following parameters are returned only for a Linked Account created with a VPA (UPI id) as the settlement destination.
​
object
The settlement destination details of the Linked Account.
​
string
The type of settlement destination. Value is vpa.
​
object
The VPA details of the beneficiary.
​
string
The beneficiary’s UPI id. For example, gaurav.kumar@paytm.
​
string
The account holder’s name as returned by the beneficiary’s bank during VPA verification. For example, GAURAV KUMAR. Use this value to perform name matching against your beneficiary records before completing onboarding.
​
object
The settlement configuration of the Linked Account.
​
string
The settlement schedule. Value is instant.
​
string
The banking mode used to process the payout. Value is imps.
​
integer
The Unix timestamp at which the Linked Account was created.

​
Errors

Code: 4xxThis error occurs when there is a mismatch between the API credentials passed in the API call and the API credentials generated on the Dashboard.Solution: Make sure the API Keys are active and entered correctly. Also, there should not be any whitespaces before or after the keys.
Code: 400This error occurs when a mandatory field is empty.Solution: Make sure to fill in all the mandatory fields.
Code: 400This error occurs when Marketplace feature is not enabled for merchants using private auth.Solution: Ensure to enable Marketplace feature for merchants using private auth.
Code: 400This error occurs when the value of a parameter is invalid. For example, when the value of the type parameter is other than route.Solution: Ensure to send correct values for parameters.
Code: 400This error occurs when you pass the value for the reference_id parameter, but the route_code_support feature is not enabled for merchants.Solution: Ensure to enable the route_code_support feature for merchants before passing the value for the reference_id parameter.
Code: 400This error occurs when you try to create a Linked Account with an existing email address.Solution: Make sure the email address is unique while creating a Linked Account.
Code: 400This error occurs when you pass an invalid IFSC code.Solution: Make sure you pass a valid IFSC code.
Code: 400This error occurs when the name field has anything other than alphabets, digits and spaces.Solution: Make sure you enter a valid name without special characters.
Code: 400This error occurs when you pass an invalid bank account number.Solution: Make sure to pass a valid account number.
Code: 400This error occurs when the account_code feature is not enabled for the merchant.Solution: Make sure to enable the correct feature for the merchant - route_code_support.
Code: 400This error occurs when the reference_id format is invalid.Solution: Ensure the reference_id format is valid.
Code: 400This error occurs when the reference_id value has less than a minimum of 3 characters.Solution: The reference_id value should be between 3 to 20 characters.
Code: 400This error occurs when the VPA address passed in account_details.vpa.address does not exist on the UPI network or has been deactivated.Solution: Ask the beneficiary to confirm their UPI id is active. You can also pre-validate the VPA using the Validate VPA API before creating the Linked Account.
Code: 400This error occurs when the value passed in account_details.vpa.address does not follow the username@bankname format.Solution: Make sure the VPA is in the correct format. For example, gaurav.kumar@paytm or 9000090000@ybl.
Code: 400This error occurs when a transfer to this Linked Account exceeds ₹1,00,000, which is the NPCI-mandated per-transaction limit for UPI payouts.Solution: For amounts above ₹1,00,000, create a separate Linked Account with bank account details and use bank account settlement.
Code: 400This error occurs when the cumulative transfers to the beneficiary’s VPA have reached the ₹1,00,000 daily limit set by NPCI. The limit resets at midnight IST.Solution: Queue the transfer for processing after midnight, switch to bank account settlement for this beneficiary or ask the beneficiary if they have an alternate UPI id.
Code: 400This error occurs when the value passed in account_details.account_type is not a recognised account type.Solution: Pass vpa as the value for account_details.account_type for UPI-based settlement.
Code: 400This error occurs when VPA Settlements have not been enabled for your Route account.Solution: Contact our Support team to enable VPA Settlements for your account.
Last modified on October 28, 2026