Partners | OAuth | Build Integration

To access the necessary information from your sub-merchant's account, you must integrate with OAuth. Follow the steps below for the integration.

1. Create an Application

The first step towards building an OAuth 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.

To create an application:

Log in to the Dashboard and navigate to Applications.
Click Create Application under Created Applications.
Provide the following details and click Save.
- Name: The application name provided here is displayed on the Razorpay authorisation interface.
- Website: Enter the URL of the application's website.
- Logo: Upload a square image for application logo. If logo is absent, a default logo is used.
The following fields are displayed after the application is created, for development and production clients. These are read-only:
- Client ID: Publicly exposed identifier of the client which is generated uniquely. It helps identify your application on Razorpay.
- Client Secret: Privately shared string between the application and Razorpay. It helps to authenticate the identity of the application on server-to-server API calls. Do not expose the client secret publicly.
- Redirect URIs: A whitelisted set of URIs defined during creation. Production clients can only use secure HTTPS URIs to prevent man-in-the-middle attacks. You can define multiple redirect URIs.
Edit the Redirect URIs for your clients if needed.
Click Save.

2. Get Authorisation from Sub-merchant

Following the steps to receive sub-merchant authorisation.

2.1 Initiate Authorisation Using URL

A request is sent to redirect your sub-merchants to Razorpay's authorisation service. You will receive a code upon authorisation from the sub-merchant. You can exchange this code for an access token.

Example

Query Parameters

Define the following query parameters in the URL. All parameters are mandatory unless specified as optional:

client_id

string The unique client identifier. You can find it on your application.

response_type

string Specifies that the application is requesting an authorisation code grant. Possible value is code.

redirect_uri

string Callback URL used by Razorpay to redirect after the user approves or denies the authorisation request. The client should whitelist redirect_uri.

scope

string Defines the kind of 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. This means you can only view the payments, refunds and so on.
read_write: Provides read and write access to all resources on the API. This means you can view and create payments, refunds and so on.

state

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.

Success Response Parameters

We send the following parameters if the user approves the request:

code

URL-encoded authorisation code. This is sent to you once the sub-merchant authorises. You can exchange this code for an access token.

state

The value of the state parameter sent in the authorisation request.

Authorisation Response

After completion, the sub-merchant's browser is redirected to URI specified in the redirect_uri parameter. Once the

sub-merchant authorises

, you can proceed with the steps ahead.

2.2 Get Access Token

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.

POST

https://auth.razorpay.com/token

Given below is the 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

Once the sub-merchant authorises, the following tokens become available to both you and the sub-merchant. You can use these tokens later to create API requests on behalf of the sub-merchant. Know more

about tokens

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. You must use this token instead of key_id and key_secret to call API requests for the respective sub-merchant. Each sub-merchant has a unique access_token. It expires every 90 days.

public_token

string A public key is used for Payments. For example: rzp_test_oauth_32hsbEKriO6ai4.

refresh_token

string Used to refresh the access token when it expires.

Watch Out!

The refresh_token expires in 180 days from the day of generation and must be used to generate a new refresh_token before expiry.

razorpay_account_id

string Identifies the sub-merchant ID who granted the authorisation.

Store the access_token received above on your server. Using this token, you can access the sub-merchant's data on Razorpay APIs based on the level of access granted.

For using RazorpayX as a resource, check

Access Resources using Access Token

About Tokens

Refresh Token API

You can use refresh tokens to generate a new access token. If your access token expires, you will receive a 4XX response from the API. You can make a request using your refresh token to generate a new (access_token and refresh_token) pair.

Refer to the following API request on how to request a new token:

POST

https://auth.razorpay.com/token

Watch Out!

You should make this request from the application's backend server only.

Given below is the sample code:

curl -X POST https://auth.razorpay.com/token
-H "Content-type: application/json" 
-d '{
  "client_id": "<YOUR_CLIENT_ID>",
  "client_secret": "<YOUR_CLIENT_SECRET>",
  "grant_type": "refresh_token",
  "refresh_token": "def5020096e1c470c901d34cd60fa53abdaf3662sa0"
}'

Request Parameters

Send the following parameters in the request:

client_id

mandatory

string Unique client identifier.

client_secret

mandatory

string Client secret string.

grant_type

mandatory

string The type of grant for the request. Possible value is refresh_token.

refresh_token

mandatory

string The previously-stored refresh token value which is about to expire.

Response Parameters

The server will respond with the following parameters:

token_type

string Defines the type of access token. Possible value is Bearer.

expires_in

string Integer representing the TTL of the access token in seconds.

access_token

string Used to access sub-merchant resources on Razorpay. access_token is a private token and should only be used for server-to-server calls.

public_token

string Token used only for Payments. For example: rzp_test_oauth_32hsbEKriO6ai4.

refresh_token

string The new refresh token. The old refresh token will be expired automatically from this point.

Revoke Token API

Use the following endpoint to revoke a token.

POST

https://auth.razorpay.com/revoke

Request Parameters

Send the following parameters in the request:

client_id

mandatory

string Unique client identifier.

client_secret

mandatory

string Client secret string.

token_type_hint

mandatory

string The type of token for the request. Possible value:

access_token
refresh_token

token

mandatory

string The token whose access should be revoked.

Response Parameters

The server will respond with the following parameters:

message

string The confirmation message of the token revoke.

Error Response Parameters

Refer to our

errors

page for the list of errors and solutions.

3. 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.

For Payments

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

For RazorpayX

Subscribing to webhooks

is a mandatory step if you want to access the user's RazorpayX data. Once you

generate the access_token

, the user's RazorpayX account_id will be sent to the webhook URL specified while creating your application.

Below is a sample payload.

{
  "entity": "event",
  "account_id": "acc_FoM4gv3Gn6NKrM",
  "event": "banking_accounts.issued",
  "contains": [
    "accounts"
  ],
  "payload": {
    "accounts": {
      "virtual": {
        "account_number": "3434360450562835"
      },
      "current": [
        {
          "channel": "rbl",
          "account_number": "409000768239"
        }
      ]
    }
  },
  "created_at": 1604920603
}

4. 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",
    "name": "Acme Corp",
    "description": "A Wild Sheep Chase is the third novel by Japanese author Haruki Murakami",
    "image": "https://example.com/your_logo",
    "handler": function (response){
        alert(response.razorpay_payment_id);
    },
    "prefill": {
        "name": "Gaurav Kumar",
        "email": "gaurav.kumar@example.com"
    },
    "notes": {
        "address": "note value"
    },
    "theme": {
        "color": "#F37254"
    }
};
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

Sub-merchants can revoke access to your application from the Dashboard at any time. Once revoked, your application will no longer have the capability to perform any operations on the sub-merchant account.

We recommend subscribing to the account.app.authorization_revoked webhook event. This ensures that you receive real-time notifications whenever a sub-merchant revokes access to your connected application.