Technology Partners | Integrate with Custom Onboarding SDK

With the Custom Onboarding SDK, you can streamline sub-merchant enrollment by handling the process on their behalf — they do not need to create individual accounts or complete KYC verification themselves. Use the APIs and generate access token for your sub-merchants. You can onboard multiple sub-merchants with a single application unless there is a difference of commissions amongst the sub-merchants.

To integrate with Custom Onboarding SDK:

1. Create an Application

The first step towards building an integration is creating an application on the Razorpay Partner Dashboard. Here, an application refers to a software entity that you register on Razorpay to facilitate OAuth-based authentication and authorisation for businesses on your platform. It acts as an intermediary between you and Razorpay. Internally, Razorpay OAuth identifies the applications by their client_id.

When you create an application on Razorpay, we generate two clients linked to the application: development and production clients.
Each client has its own client_id and client_secret.
You can use the development client in your sandbox environment or during the integration phase, and the production client once you go live.

Development and Production Clients

Given below is a comparison of the development and production clients:

Watch Out!

Only an Owner user can create applications on the Dashboard.

2. Generate Token

The next step is to generate a bearer token to access onboarding APIs. You must use the access token generated in the response to hit the

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.

3. Create Account and Upload KYC Details

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.

List of required KYC documents as per business type.

4. Generate Onboarding URL

Below is the sample code to generate the onboarding URL.

Sample Onboarding URL

Query Parameters

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. All GET 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. This will reduce sub-merchant onboarding time. Know more about

onboarding signature

Success Response Parameters

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 Response Parameters

Refer to our

errors

page for the complete list of errors and solutions.

Redirect Users to Onboarding

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.

Onboarding Signature

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.

Watch Out!

The response of the account creation API, returns id as acc_HQVlm3bnPmccC0. However, for the onboarding signature, the sub-merchant id must be entered without the 'acc_' which means acc_HQVlm3bnPmccC0 must be entered as HQVlm3bnPmccC0.

Authorisation Response

After completion, the browser is redirected to URI specified in the redirect_uri parameter.

5. Fetch Access Token

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.

Request Parameters

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.

Response Parameters

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.

Error Response Parameters

Refer to our

errors

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.

Regenerate Access Token

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.

6. Access Resources Using Access 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

Razorpay APIs

Given below is a sample code for the

Fetch all Payments API

7. Process Payments

As a Technology Partner, you can allow sub-merchants to accept payments through various Payment Methods and channels. after getting access_token.

1. Access Payment APIs using OAuth

You can process payments on behalf of your sub-merchants using

Razorpay APIs

. Use the tokens generated during

OAuth integration

Use the access_token generated in the

build integration

step to authenticate using Bearer Auth.

Below is a sample code to create an Order and process payments.

POST

/orders

The parameter descriptions and errors are present in the

Create an Order API

documentation.

2. Public Token

Using the public_token for authorisation can secure a public-facing implementation such as Razorpay Checkout. In such cases, the public_token can replace the key_id field as shown below:

<button id="rzp-button1">Pay</button>
<script src="https://checkout.razorpay.com/v1/checkout.js"></script>
<script>
var options = {
    "key": "rzp_test_oauth_32hsbEKriO6ai4", // Public Token
    "amount": "29900", // Amount is in currency subunits. Default currency is INR. 
    "currency": "INR",
    "name": "Acme Corp", //your business name
    "description": "Test Transaction",
    "image": "https://example.com/your_logo",
    "order_id": "order_9A33XWu170gUtm", //This is a sample Order ID. Pass the `id` obtained in the response of Step 1
    "callback_url": "https://eneqd3r9zrjok.x.pipedream.net/",
    "prefill": { //We recommend using the prefill parameter to auto-fill customer's contact information especially their phone number
        "name": "Gaurav Kumar", //your customer's name
        "email": "gaurav.kumar@example.com",
        "contact": "9000090000" //Provide the customer's phone number for better conversion rates 
    },
    "notes": {
        "address": "Razorpay Corporate Office"
    },
    "theme": {
        "color": "#3399cc"
    }
};
var rzp1 = new Razorpay(options);
document.getElementById('rzp-button1').onclick = function(e){
    rzp1.open();
    e.preventDefault();
}
</script>

Know more about

Web Standard Integration

3. Verify Payment Signature

This is a mandatory step to confirm the authenticity of the details returned to the Checkout form for successful payments.

To verify the razorpay_signature returned to you by the Checkout form:

Create a signature in your server using the following attributes:
- order_id: Retrieve the order_id from your server. Do not use the razorpay_order_id returned by Checkout.
- razorpay_payment_id: Returned by Checkout.
- client_secret: Available in your server. The client_secret that was generated from the
  RazorpayDashboard
  .

Use the SHA256 algorithm, the razorpay_payment_id and the order_id to construct a HMAC hex digest as shown below:

generated_signature = hmac_sha256(order_id + "|" + razorpay_payment_id, client_secret);

  if (generated_signature == razorpay_signature) {
    payment is successful
  }

If the signature you generate on your server matches the razorpay_signature returned to you by the Checkout form, the payment received is from an authentic source.

Generate Signature on Your Server

Given below is the sample code for payment signature verification:

RazorpayClient razorpay = new RazorpayClient("[CLIENT_KEY_ID]", "[CLIENT_KEY_SECRET]");


String secret = "EnLs21M47BllR3X8PSFtjtbd";


JSONObject options = new JSONObject();
options.put("razorpay_order_id", "order_IEIaMR65cu6nz3");
options.put("razorpay_payment_id", "pay_IH4NVgf4Dreq1l");
options.put("razorpay_signature", "0d4e745a1838664ad6c9c9902212a32d627d68e917290b0ad5f08ff4561bc50f");


boolean status =  Utils.verifyPaymentSignature(options, secret);

Post Signature Verification

With this, your integration is complete. Test the integration before going live. Replace the test key with the live key and integrate with other

APIs

Subscribe to webhook events to receive real time notifications on the onboarding status of your clients. Check the available

Partner Webhooks

With this, your integration is complete. Test the integration before going live.