Build Integration

Steps to integrate Razorpay OAuth with your application.


Follow these steps to integrate Razorpay OAuth with your 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.

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

ParticularsDevelopment ClientProduction Client
Redirect URICan have any type of Redirect URIs whitelisted, including non-HTTP and localhost.Cannot use non-HTTPS Redirect URIs.
Test and Live Mode AccessCan access both modes.Can access only live mode data.

Watch Out!

Only an Admin user can create applications on the Razorpay Dashboard.

To create an application:

  1. Log in to the

    .

  2. Navigate to Applications.

    Create Application
  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.
    Add Application Details

    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.
    View Production and Development Credentials for Application
  5. Edit the Redirect URIs for your clients if needed.

  6. Click Save.

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.

Handy Tips

  • Razorpay OAuth supports the standard .
  • Implement the flow described below to obtain an authorisation code and then exchange it for an access token. The is currently not supported.

Given below is a sample authorisation interface:

Sample Authorisation Interface

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

POST
https://auth.razorpay.com/authorize

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

client_id

string The unique client identifier.

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 the redirect_uri.

scope

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

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:

  1. Your application should generate a unique random string and save it in the database.
  2. Send the random string to Razorpay in the authorisation request in the state parameter.
  3. Razorpay sends back the same state value as query params on your redirect URI.
  4. 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.

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:

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

page for the list of errors and solutions.

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.

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.

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

.

Refer to our

page for the list of errors and solutions.

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

.

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.

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 public routes such as Checkout or 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.

Error Response Parameters

Refer to our

page for the list of errors and solutions.

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

message

string The confirmation message of the token revoke.

Error Response Parameters

Refer to our

page for the list of errors and solutions.

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

.

is a mandatory step if you want to access the user's RazorpayX data. Once you , 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
}

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.


Is this integration guide useful?