Custom Onboarding SDK
Integrate with Custom Onboarding SDK to create client accounts using APIs and prefill KYC details.
To integrate with Custom Onboarding SDK:
You require a bearer token to access onboarding APIs. Below is a sample code to generate a bearer token using Onboarding SDK.
The access_token
is valid for 90 days. After your access token expires, you will receive a 4XX error response. Regenerate the access token using your credentials.
Use onboarding APIs to add KYC details of your clients. You can pre-fill all or a few KYC details using APIs and let the users fill in the remaining on the onboarding form.
Below are the APIs available to onboard clients.
API | Action |
---|---|
Create and update a client account. Add basic details like name, phone number, email ID and KYC details like business name, type and business PAN details. Check the for the complete list of fields. | |
Configure products for an account. Update payment methods, settlement details and refund settings. Check the for the complete list of fields. | |
Add the KYC details of the authorised signatory or the owner of the business. Check the for the list of fields. | |
Upload KYC documents for accounts and stakeholders. Know more about . |
Below is a sample code to create a client account. Know more about
.id
string
The unique identifier of a sub-merchant account generated by Razorpay. The maximum length is 18 characters. For example, acc_GLGeLkU2JUeyDZ
.
type
string
The account type. Possible value is standard
.
status
string
The status of the account. Possible values:
created
: Account status when the merchant account is created.activated
: Account status when the merchant KYC is approved.needs_clarification
: Account status when the merchant is asked to provide clarifications related to the KYC details submitted.under_review
: Account status when the merchant submits all the KYC requirements.suspended
: Account status when the merchant account is identified as potentially fraudulent and is suspended.rejected
: Account status when the KYC details submitted by the merchant are rejected during manual review.
string
The sub-merchant's business email address.
phone
integer
The sub-merchant's business phone number. The minimum length is 8 characters and the maximum length is 15.
legal_business_name
string
The name of the sub-merchant's business. For example, Acme Corp
. The minimum length is 4 characters and the maximum length is 200.
customer_facing_business_name
string
The sub-merchant billing label as it appears on the Razorpay Dashboard. The minimum length is 1 character and the maximum length is 255. This parameter might be required to complete the KYC process. However, it is optional for this API.
business_type
string
The type of business operated by the sub-merchant. Possible values:
reference_id
string
Partner's external account reference id. The minimum length is 1 character and the maximum length is 512.
profile
object
The business details of the sub-merchant's account.
category
string
The business category of the sub-merchant. Possible values:
subcategory
string
The business sub-category of the sub-merchant. Possible values:
description
deprecated
string
This parameter has been deprecated. Pass the description using the business_model
parameter.
business_model
string
The business description. The minimum length is 1 character and the maximum length is 255.
addresses
object
Details of sub-merchant's address.
operation
object
Details of the sub-merchant's operational address. This parameter might be required to complete the KYC process. However, it is optional for this API.
street1
string
Address, line 1. The maximum length is 100 characters.
street2
string
Address, line 2. The maximum length is 100 characters.
city
string
The city. The maximum length is 100 characters.
state
string
The state. The minimum length is 2 and the maximum length is 100.
postal_code
integer
The postal code. This should be exactly 6 characters.
country
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
.
registered
object
Details of the sub-merchant's registered address.
street1
string
Address, line 1. The maximum length is 100 characters.
street2
string
Address, line 2. The maximum length is 100 characters.
city
string
The city. The maximum length is 100 characters.
state
string
The state. The minimum length is 2 and the maximum length is 100.
postal_code
integer
The postal code. This should be exactly 6 characters.
country
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
.
legal_info
object
The legal details about the sub-merchant's business.
pan
string
Valid PAN number details of the sub-merchant'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. Business types like proprietorship and individual (not_yet_registered
), do not require Business PAN.
gst
string
Valid GSTIN number details of the sub-merchant.
- 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
.
cin
string
CIN is for Private Limited and Public Limited, whereas LLPIN is for LLP business type.
- This is a 21-digit alpha-numeric number.
- The Regex for CIN is
/^([a-z]{3}-\d{4}|[ul]\d{5}[a-z]{2}\d{4}[a-z]{3}\d{6})$/i
.
brand
object
The branding details of the sub-merchant's business.
color
string
The color code of sub-merchant's business brand. This is a 6-character hex code (Regex: [a-fA-F0-9]{6}).
notes
object
Contains user-defined fields stored by the partner for reference purposes.
contact_name
string
The name of the contact. The minimum length is 4 and the maximum length is 255 characters.
contact_info
object
Options available for contact support.
chargeback
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.
phone
integer
The phone number of chargeback POC. The maximum length is 10 characters.
policy_url
string
The URL of chargeback policy. Regex is (protocol://<domainname>
:port/resource path?querystring#fragementid)
protocol-both http/https allowed. Only domain name is mandatory.
refund
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.
phone
integer
The phone number of refund POC. The maximum length is 10 characters.
policy_url
string
The URL of refund policy. Regex is (protocol://<domainname>
:port/resource path?querystring#fragementid)
protocol-both http/https allowed.
support
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.
phone
integer
The phone number of support POC. The maximum length is 10 characters.
policy_url
string
The URL of support policy. Regex is (protocol://<domainname>
:port/resource path?querystring#fragementid)
protocol-both http/https allowed.
apps
object
The app details of the sub-merchant's business
websites
array
The website/app for the sub-merchant's business. A minimum of 1 website is required.
android
array
Android app details
url
string
The link of the Android app. Regex is (protocol://<domainname>
:port/resource path?querystring#fragementid)
protocol-both http/https allowed.
name
string
The name of the Android app.
ios
array
iOS app details
url
string
The link of the iOS app. Regex is (protocol://<domainname>
:port/resource path?querystring#fragementid)
protocol-both http/https allowed.
name
string
The name of the iOS app.
activated_at
integer
Unix timestamp that indicates when the merchant account was activated. This parameter has null
value till the account is activated.
live
boolean
Indicates the payments acceptance status of the merchant account. Possible values:
true
: Merchant can start accepting customer payments.false
: Merchant cannot accept customer payments.
hold_funds
boolean
Indicates the settlements status of the merchant account. Possible values:
true
: Settlement are on hold. Funds are not transferred to the merchant account.false
: Settlements can be transferred to the merchant account.
You can request a product configuration to configure and activate Razorpay products for a client account according to their requirements. Know more about
.id
string
The unique identifier of a product generated by Razorpay for a sub-merchant account. This id is used to fetch or update a product.
product_name
string
The product(s) to be configured. Possible values:
payment_gateway
payment_links
tnc
object
It consists of the configuration for the accepted terms and conditions by the merchant for the requested product. If the terms and conditions are accepted by the user for the requested product, it would consist of the following fields:
id
string
The unique identifier representing the acceptance of terms and conditions for a product by a user.
accepted
boolean
The flag that represents whether the terms and conditions are accepted by the user.
accepted_at
integer
The Unix timestamp at which the terms and conditions were accepted by the user for the requested product.
activation_status
string
The status of the
requested
needs_clarification
under_review
activated
suspended
configuration
object
The following are the possible configurations:
payment_methods
object
The payment methods configured, such as, netbanking, UPI, Wallet and EMI.
upi
object
The UPI type payment method.
status
string
The status of UPI payment method.
instrument
array
The list of UPI instruments requested or enabled.
netbanking
object
The netbanking type payment method.
status
string
The status of the netbanking payment method.
instrument
array
The netbanking instrument object.
type
string
The type of netbanking payment method. Possible values:
- Retail
- Corporate
bank
array
The list of netbanking banks requested or enabled. Refer the
wallet
object
The Wallet type payment method.
status
string
The status of the Wallet payment method.
instrument
array
The list of Wallet instruments requested or enabled.
emi
string
The EMI type payment method.
status
string
The status of EMI payment method.
instrument
array
The EMI instrument object.
type
string
The type of EMI payment method. Possible values:
card_emi
cardless_emi
partner
array
The list of EMI partners requested or enabled. Possible values:
- For
card_emi
:debit
andcredit
. - For
cardless_emi
:zestmoney
andearlysalary
.
paylater
object
The payment method to be enabled.
enabled
boolean
Enables or disables the payment method. Possible values:
true
: Enables thepaylater
payment method.false
: Does not enable thepaylater
payment method.
instrument
string
The Paylater service provider. Possible values are:
epaylater
getsimpl
payment_capture
object
The payment capture settings object.
mode
string
The mode through which payment capture is done. Possible values:
automatic
: Payments are auto-captured (default)manual
: You have to manually capture payments using our Capture API or from the Partner's Dashboard.
automatic_expiry
numeric
This denotes the time in minutes when the payment is in the authorized state. This is auto-captured.
manual_expiry
numeric
This denotes the time in minutes until you can manually capture payments in the authorized state.
- Must be equal to or greater than the
automatic_expire_period
value. - The default and the maximum value is 7200 minutes.
- The payments in the authorized state after the
manual_expire_period
are auto-refunded.
settlements
object
The Settlement settings object.
account_number
string
The bank account number to which settlements are made. Account details can be found on the Partner's Razorpay Dashboard. For example, 7878780080316316.
ifsc_code
string
The IFSC associated with the bank account. For example, RATN0VAAPIS
.
beneficiary_name
string
The name of the beneficiary associated with the bank account.
Handy Tip
This API parameter is needed complete the KYC process. However, it is optional for this API.
refund
object
This denotes the payment refund settings.
default_refund_speed
string
Speed at which the refund is to be processed. Possible values are:
- normal: Indicates that the refund will be processed at the normal speed. By default, the refund will take 5-7 working days.
- optimum: Indicates that the refund will be processed at an optimal speed based on Razorpay's internal fund transfer logic. That is:
- If the refund can be processed instantly, Razorpay will initiate the process irrespective of the payment method used to make the payment.
- If an instant refund is not made, Razorpay will initiate a refund that is processed at the normal speed. For example, payments made using debit cards, netbanking or unsupported credit cards.
checkout
object
The checkout form of the payment capture.
theme_color
string
The theme color for sub-merchant's checkout page
logo
string
The logo of the sub-merchant's business on the checkout page.
flash_checkout
boolean
The flagging options Enable or Disable for Razorpay's Flash Checkout to securely save the card details of your customers.
notifications
object
This denotes the notifications settings.
string
The email addresses that will receive notifications regarding payments, settlements, daily payment reports, webhooks, and so on.
boolean
The WhatsApp notifications you receive regarding payments, settlements, daily payment reports, webhooks, etc.
sms
boolean
The SMS notifications you receive regarding payments, settlements, daily payment reports, webhooks, etc. This attribute will be set to false
.
requested_configuration
object
The configuration of the product requested by the user that is yet to be set as active.
active_configuration
object
The configuration of the product that has been set as active.
requirements
object
The list of requirements to be enabled for this product or some of the configurations under this product. It is classified into two types:
- Required document: field_reference: "proof_type.document_type". For example:
business_proof_of_identification.business_pan_url
. The sub-merchant needs to upload thebusiness_pan_url
document to get the requirement fulfilled. - Selected required document: field_reference : "proof_type". For example:
individual_proof_of_address
. The sub-merchant can upload ONE of the following groups, that is, submit [aadhar_front
,aadhar_back
] or [voter_id_front
,voter_id_back
] or [passport_front
,passport_back
]. Once all the documents of any ONE of the groups are uploaded, the requirement gets fulfilled.
field_reference
string
The field which is in issue or missing. The JSON key path in resolution URL.
resolution_url
string
The URL to address the requirement. The API endpoint to be used for updating missing fields or documents.
status
string
The status of the requirement.
reason_code
string
The reason code for showing in the requirement. Description will be sent only when reason code is "". Possible values are:
field_missing
needs_clarification
document_missing
description
string
This parameter is displayed when the reason_code is needs_clarification
.
requested_at
integer
The Unix timestamp at which the product configuration is requested.
Below is a sample code to create a stakeholder. Know more about
.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.
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 totrue
if the stakeholder is a director of the account's legal entity. By default, it is set tofalse
.executive
: This attribute is set totrue
if the stakeholder is an executive of the account's legal entity. By default, it is set tofalse
.
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. 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
.
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 to validate Stakeholder PAN:
/^[a-zA-z]{5}\d{4}[a-zA-Z]{1}$/
- Validation for Stakeholder PAN: The 4th digit should be 'P'.
- If the business type is HUF, the karta's PAN should be provided.
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”.
You need to upload account and stakeholder documents for KYC verification. Know more about
.You need to share the Razorpay-hosted co-branded onboarding URL with your clients. Clients use this URL to continue the onboarding process.
- The user will be redirected to the co-branded onboarding form when they click the embedded onboarding button on your platform. The user has to enter any pending KYC details and verify the pre-filled information.
- After the necessary details are submitted, the user is prompted to authorise your platform to access data and create payments and refunds.
- The client gives authorisation, which allows Razorpay to connect their client account to your Partner account.
- On successful authorisation, Razorpay redirects the user back to a URL configured by you in your application settings. While redirecting, Razorpay shares an authentication code. You need to use this Auth code in the token API request to generate an Auth token.
Below is the sample code to generate the onboarding URL.
Define the following query parameters in the URL.
client_id
mandatory
string
The unique client identifier.
response_type
mandatory
string
Specifies that the application is requesting an authorisation code grant. Possible value is code
.
redirect_uri
mandatory
string
Callback URL used by Razorpay to redirect after the user approves or denies the authorisation request. The client should whitelist the redirect_uri
.
scope
mandatory
string
Defines what access your application is requesting from the user. You can request multiple scopes by separating with a space. Possible values:
read_only
: Provides read access to all resources. AllGET
API requests.read_write
: Provides read and write access to all resources on the API.
state
mandatory
string
A random string generated by your service. This parameter helps prevent cross-site request forgery (CSRF) attacks. State validation has to be implemented by your application and should work as described below:
- Your application should generate a unique random string and save it in the database.
- Send the random string to Razorpay in the authorisation request in the
state
parameter. - Razorpay sends back the same
state
value as query params on your redirect URI. - In your backend, you validate that the state value stored in your database matches the one you received for the
client_id
and the user that initiated the authorisation.
onboarding_signature
conditionally mandatory
string
This parameter is applicable only for accounts created using KYC pre-fill. Know more about
We send the following query parameters if the user approves the authorisation request:
code
URL-encoded authorisation code. You can exchange this code for an access token in the next step.
state
The value of the state
parameter sent in the authorisation request.
Error | Cause | Solution |
---|---|---|
phone number unverified |
| Use a valid onboarding_signature . An onboarding signature is valid for 24 hours. You can regenerate it using the same code. |
Refer to our
page for the complete list of errors and solutions.onboarding_signature
is a mandatory parameter if you are pre-filling KYC details. The onboarding signature is used to verify the identity of the partner initiating the onboarding URL.
Use the below sample code to generate an onboarding_signature
.
After completion, the browser is redirected to URI specified in the redirect_uri
parameter.
You require an access token to create payments and refunds on behalf of your clients using APIs. Exchange the authorisation code received in the previous step for an access token.
Handy Tips
The authorisation code is URL-encoded. Decode it before sending in this request.
Given below is a sample request to be made from the application's backend server.
client_id
mandatory
string
Unique client identifier.
client_secret
mandatory
string
Client secret string.
grant_type
mandatory
string
Defines the grant type for the request. Possible value is authorization_code
.
redirect_uri
mandatory
string
Specifies the same redirect_uri
used in the authorisation request.
code
mandatory
string
Decoded authorisation code received in the last step.
mode
optional
string
The type of mode. Possible values:
test
live
(default)
Handy Tips
Clients on production can only make requests for live mode.
The server responds with the following parameters:
token_type
string
Defines the type of access token. Possible value is Bearer
.
expires_in
integer
Integer representing the TTL of the access token in seconds.
access_token
string
A private key used to access sub-merchant resources on Razorpay. Used for server-to-server calls only.
public_token
string
A public key is used only for public routes such as Checkout or Payments.
refresh_token
string
Used to refresh the access token when it expires.
razorpay_account_id
string
Identifies the sub-merchant ID who granted the authorisation.
Refer to our
page for the list of errors and solutions.Store the access_token
received above on your server. Using this token, you can access the sub-merchant's data, create payments and refunds using Razorpay APIs.
The access_token
is valid for 90 days. After your access token expires, you will receive a 4XX error response. Use a refresh token to generate a new access token. You can make a request using your refresh token to generate a new (access_token and refresh_token) pair.
Below is a sample API request to request a new token.
After you obtain an access token, you can use it to access the sub-merchant's data on Razorpay APIs. The access is controlled based on the scope requested for and granted by the user during the authorisation process.
Provide the access token in the Bearer
authorisation header while requesting
Given below is a sample code for the
.After you obtain an access token, you can use it to access the sub-merchant's data on Razorpay APIs. The access is controlled based on the scope requested for and granted by the user during the authorisation process.
Subscribe to webhook events to receive real time notifications on the onboarding status of your clients. Check the available
.With this, your integration is complete. Test the integration before going live.
Was this page helpful?
ON THIS PAGE