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.
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 Curlec 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 Curlec in the authorisation request in the
state
parameter. - Curlec 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.
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 Curlec. 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 Curlec 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 Curlec 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?