API ReferenceIntegrationsKnowledge Base

Authorization

Authorization is enabled via a webpage hosted by Razorpay. When the application needs to connect to a merchant's Razorpay account, it redirects the user to this webpage where the user can approve or deny the authorization request.

Note:
Razorpay OAuth supports the standard authorization code grant. You have to implement the flow described below to obtain an authorization code and then exchange it for an access token. The implicit grant is not currently supported.

Below is a sample authorization interface:

Authorization URL🔗

To initiate authorization, users must be redirected to Razorpay's authorization service on the URL given below:

Copyhttps://auth.razorpay.com/authorize

You must define the following query parameters in the URL. All parameters are mandatory unless specified as optional:

client_id
Unique client identifer.
response_type
The only supported value is code. This specifies that the application is requesting an authorization code grant.
redirect_uri
Callback URL used by Razorpay to redirect after the user approves or denies the authorization request. The redirect_uri must be whitelisted by the client first.
scope
Defines what access your application is requesting from the user. Multiple scopes can be requested by separating each scope with a space. Refer the section on Scopes for further details.
state
A random string generated by your service. This parameter is forwarded to the redirect URL. This helps prevent CSRF attacks, and is explained here.

An example of a complete authorization URL is shown below:

Copyhttps://auth.razorpay.com/authorize ?client_id=8DXCMTshWSWECc &response_type=code &redirect_uri=https://example.com/razorpay_callback &scope=read_only &state=NOBYtv8r6c75ex6WZ

Authorization Response🔗

Once complete, the browser is redirected back to URI specified in the redirect_uri parameter.

Success Response🔗

If the user approved the request, the following query parameters are sent:

code
URL-encoded authorization code. You can exchange this code for an access token in the next step.
state
The value of the state parameter that was sent in the authorization request. Refer Validating States for details on how to successfully validate this parameter.

Error Response🔗

error_code
The error code.
error_description
Description of the error.

Access Token🔗

Once an authorization code has been received, it can be exchanged for an access token, as shown below:

Note: The authorization code is url-encoded and needs to be decoded before sending in this request.

https://auth.razorpay.com/token

This request must be made from the application's backend server.

Request🔗

The following parameters should be sent in the request:

client_id
Unique client identifer.
client_secret
Client secret string.
grant_type
Defines the grant type for the request. This should be set to authorization_code.
redirect_uri
Specifies the same redirect_uri used in the authorization request.
code
Decoded authorization code received in the last step.
mode
Optional. It can have these values: test or live. Defaults to live.

Note: For clients on production can only make requests for live mode.

Response🔗

The server responds with the following parameters:

token_type
Defines the type of access token. This is set to Bearer.
expires_in
Integer representing the TTL of the access token in seconds.
access_token
A private key used to access merchant resources on Razorpay. This token is used for server-to-server calls only.
public_token
A public key is used only for public routes such as Checkout or Payments.
refresh_token
Refresh token that can be used to refresh the access token when it expires.
razorpay_account_id
Identifies the sub-merchant ID who granted the authorization.
Copy curl -H "Content-type: application/json" -XPOST https://auth.razorpay.com/token -d '{ "client_id": "<YOUR_CLIENT_ID>", "client_secret": "<YOUR_CLIENT_SECRET>", "grant_type": "authorization_code", "redirect_uri": "http://example.com/razorpay_callback", "code": "def50200d844dc80cc44dce2c665d07a374d76802", "mode": "test" }
Copy{ "public_token": "rzp_test_oauth_9xu1rkZqoXlClS", "token_type": "Bearer", "expires_in": 7862400, "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6IkY1Z0NQYkhhRzRjcUpnIn0.eyJhdWQiOiJGNFNNeEgxanMxbkpPZiIsImp0aSI6IkY1Z0NQYkhhRzRjcUpnIiwiaWF0IjoxNTkyODMxMDExLCJuYmYiOjE1OTI4MzEwMTEsInN1YiI6IiIsImV4cCI6MTYwMDc3OTgxMSwidXNlcl9pZCI6IkYycVBpejJEdzRPRVFwIiwibWVyY2hhbnRfaWQiOiJGMnFQaVZ3N0lNV01GSyIsInNjb3BlcyI6WyJyZWFkX29ubHkiXX0.Wwqt5czhoWpVzP5_aoiymKXoGj-ydo-4A_X2jf_7rrSvk4pXdqzbA5BMrHxPdPbeFQWV6vsnsgbf99Q3g-W4kalHyH67LfAzc3qnJ-mkYDkFY93tkeG-MCco6GJW-Jm8xhaV9EPUak7z9J9jcdluu9rNXYMtd5qxD8auyRYhEgs", "refresh_token": "def50200f42e07aded65a323f6c53181d802cc797b62cc5e78dd8038d6dff253e5877da9ad32f463a4da0ad895e3de298cbce40e162202170e763754122a6cb97910a1f58e2378ee3492dc295e1525009cccc45635308cce8575bdf373606c453ebb5eb2bec062ca197ac23810cf9d6cf31fbb9fcf5b7d4de9bf524c89a4aa90599b0151c9e4e2fa08acb6d2fe17f30a6cfecdfd671f090787e821f844e5d36f5eacb7dfb33d91e83b18216ad0ebeba2bef7721e10d436c3984daafd8654ed881c581d6be0bdc9ebfaee0dc5f9374d7184d60aae5aa85385690220690e21bc93209fb8a8cc25a6abf1108d8277f7c3d38217b47744d7", "razorpay_account_id": "acc_Dhk2qDbmu6FwZH" }

The access_token received above can be stored on your server. Using this token, you can access the merchant's data on Razorpay APIs based on the level of access granted. Refer Accessing Resources section for more details.

Public Token🔗

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

Copy<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>

Using Scopes🔗

Scopes define the level of access required on the Razorpay merchant's APIs. The following scopes currently available:

scope_name

description

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.

Validate State🔗

The state parameter helps in preventing 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 random unique string and save it in the database.
  2. The random string should be sent to Razorpay in the Authorization request in the state parameter.
  3. Razorpay will send back the same state value as query params on your redirect URI.
  4. In your backend, validate that the state value stored in your database matches the one you received for the client_id and user that initiated the authorization.
×