Skip to main content
1

[Create an Application](#1-create-an-application)

2

[Get Authorisation from Sub-merchant](#2-get-authorisation-from-sub...

3

[Access Resources](#3-access-resources-using-access-token)

4

[Process Payments](#4-process-payments)

  1. Subscribe to Authorization Revoked Webhook

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:

Particulars | Development Client | Production Client

Redirect URI | Can have any type of Redirect URIs whitelisted, including non-HTTP and localhost. | Cannot use non-HTTPS Redirect URIs.

Test and Live Mode Access | Can access both modes. | Can access only live mode data.
Watch Out!Only an Owner user can create applications on the Dashboard.

To create an application:

  1. Log in to the Dashboard and navigate to Applications under Partners.
  2. Click Create Application under Created Applications.
  3. 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.
  4. Edit the Redirect URIs for your clients if needed.
  5. 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

Request

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 specifying each scope name separately in the URL using array notation. For example: scope[]=read_only&scope[]=rx_read_write. Possible values:
  • read_only: Provides read access to all resources. That is, 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.
  • rx_read_only: Provides read access to all RazorpayX resources. That is, all GET API requests. This means you can only view the payouts, contacts and so on.
  • rx_read_write: Provides read and write access to all RazorpayX resources on the API. This means you can view and create payouts, contacts and so on.
  • rx_partner_read_write: Provides access to fetch payouts, contacts, fund accounts, transactions, as well as approve or reject a payout.
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.

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. https://auth.razorpay.com/token Given below is the sample request to be made from the application’s backend server.
Request

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_XXXXXXXXXXXXXX. 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: 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:
Request
Request ParametersSend 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_XXXXXXXXXXXXXX. 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. https://auth.razorpay.com/revoke
Request
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.
Request

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.
Sample Payload: User's RazorpayX Account Details

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. /orders
Request
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:
Checkout
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:
  1. 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.
  2. Use the SHA256 algorithm, the razorpay_payment_id and the order_id to construct a HMAC hex digest as shown below:
    HMAC Hex Digest
  3. 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:
Java

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.

5. Subscribe to Authorization Revoked Webhook

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. Follow these steps to subscribe to webhooks. Given below is the sample payload:
account.app.authorization_revoked

Next Step

2. Test Integration