Build Integration

1. Create an Application

The first step towards building an OAuth integration is creating an application.

Applications are external entities visible to the user. Internally, Razorpay OAuth identifies clients 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:

To create an application:

1. Log in to the

   Razorpay Dashboard

   .

2. Navigate to Applications.

   

3. Click Create Application under Created Applications.

4. 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. Do not expose the client secret publicly. It helps to authenticate the identity of the application on server-to-server API calls.
   • 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.
   

5. Edit the Redirect URIs for your clients if needed.

6. Click Save.

2. Initiate Authorisation and Get Access Token

To connect to a sub-merchant's Razorpay account, the application redirects the user to a Razorpay-hosted webpage. The user can approve or deny the authorisation request on this page.

Given below is a sample authorisation interface:

2.1 Initiate Authorisation Using URL

Use the following URL to redirect users to Razorpay's authorisation service:

Example

Query Parameters

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

Authorisation Response

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

Success Response Parameters

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

Error Response Parameters

Refer to our

2.2 Get Access Token

Exchange the authorisation code received in the previous step for an access token.

Given below is the sample request to be made from the application's backend server.

Request Parameters

Response Parameters

The server responds with the following parameters:

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

Error Response Parameters

Refer to our

About Tokens

Public Token Usage

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

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:

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:

Response Parameters

The server will respond with the following parameters:

Error Response Parameters

Refer to our

Revoke Token API

Use the following endpoint to revoke a token.

Request Parameters

Send the following parameters in the request:

Response Parameters

Error Response Parameters

Refer to our

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.

Payments

Provide the access token in the Bearer authorisation header while requesting

Given below is a sample code for the

RazorpayX

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. Subscribe to Authorization Revoked Webhook

Sub-merchants can revoke access to your application from their Razorpay 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.

Follow these steps to

Given below is the sample payload:

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

Next Step

Related Information

• Revoke Access to Application

• Standard Web Integration

• Errors