Partners

Platform

Payments Oauth

Integration Steps

Payments OAuth Integration Steps

Steps to integrate Razorpay OAuth with your application.

Follow these steps to integrate Razorpay OAuth with your application:

Create an Application.
Get Authorisation.
Access Resources.

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, however, Razorpay OAuth works with clients identified 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:

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 Admin user can create applications on the Razorpay Dashboard.

To create an application:

Log into the Razorpay Dashboard.
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. 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.

Edit the Redirect URIs for your clients if needed.
Click Save.

2. Initiate Authorisation and Get Access Token🔗

To connect to a 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 authorisation code grant.
Implement the flow described below to obtain an authorisation code and then exchange it for an access token. The implicit grant is currently not supported.

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:

https://auth.razorpay.com/authorize

Example🔗

Given below is an example of a complete authorisation URL:

 Request Success Response
Copyhttps://auth.razorpay.com/authorize
    ?client_id=8DXCMTshWSWECc
    &response_type=code
    &redirect_uri=https://example.com/razorpay_callback
    &scope=read_only
    &state=NOBYtv8r6c75ex6WZ
Copy{
  "code": "def502004bd206ce8bea64a73bbaff9586e4bf4f1d247e25de748174a977220bab48ab04b3e5a931afee2d125f3e567bd2a036fb25a62c55ab333429d203c5ba725abfadc520f49358f710362dc1f37abda854b20efbdcb540a00ec902afb8ee047ffb38df4316f83365267a0fc2fada1bcf2e212e0e450df9afd6581358faa343a1daebef4a1c041669ff1e9bebeee960f6963d19a8cc4c884ec5dfc8325a163d3ece880d5def3c84dcbb2d51e618667a1fbf1990fb798a41c4c4581738e3e1d7b6763ac6293c1bbf876e4294fb5b6fcd5b47200ef66e26b4e38016292175ecbd695d6cba7c1ea3155ef70f3326347aa541c4d4d83362619ef42c0178d538e6cc92682a43a36c946ad176d158a2c0d515da1d8a3be1ec5efd37f77ae4b11784318c705b0feeea8a7f06199bf21efc4a9b0bf70c63804339eafc970697bed03b763c63516da776c0403e42798e582deaea3fd385dba7fb6e80b5c6977f3b8d1001bdf5926d582ef79fda5d0b2c",
  "state": "ACVD2346"
}

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.

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:

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.

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:

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🔗

error_code: The error code.
error_description: Description of the error. ˍ

Know more about Errors.

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 Response
Copycurl -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": "authorisation_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"
}

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 authorisation_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🔗

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 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 merchant's data on Razorpay APIs based on the level of access granted.

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:

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

Know more about Razorpay Web Standard Integration.

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, 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 Response
Copycurl -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"
}'
Copy{
  "public_token": "rzp_test_oauth_9xu1rkZqoXlClS",
  "token_type": "Bearer",
  "expires_in": 7862400,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijl4dTF",
  "refresh_token": "def5020096e1c470c901d34cd60fa53abdaf36620e823ffa53"
}

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

Revoke Token API🔗

Use the following API to revoke the token.

/revoke

 Request Success Response
Copycurl -X POST https://auth.razorpay.com/revoke
-H "Content-type: application/json"
-d '{
  "client_id": "JA1p85ntMrHJhA",
  "client_secret": "DcTFepYebC7FuNk39C8M3yl2",
  "token_type_hint": "access_token",
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJKQTFwODVudE1ySEpoQSIsImp0aSI6IkpPZkd0aHFDTmhqQUhTIiwiaWF0IjoxNjUxMTI0NTU0LCJuYmYiOjE2NTExMjQ1NTQsInN1YiI6IiIsImV4cCI6MTY1ODk4Njk1MiwidXNlcl9pZCI6bnVsbCwibWVyY2hhbnRfaWQiOiJKOWpoSTdzZkM1S1V0NiIsInNjb3BlcyI6WyJyZWFkX3dyaXRlIl19.h1oL_Tik642Q18DdyEnIVziW1kgw6k09K8ALuI4uWQBH3jE4R8p1e6ysQq-Et4E_MZd7ADfC1W6kFwe3PXlkLC6emaZAKESZghbtTBM6RYnhieErAOcD7ytc0P8c75aNRlC6MWwlWaH20OFYuSay7iGFyw2jp4by4xDFlYweVLc"
}'
Copy{
  "message": "Token Revoked"
}

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🔗

Given below are sample codes for two types of errors:

Status Code 401: When token is not validated

 Error Response - 401
Copy{
  "error": {
    "description": "Could not validate the token provided"
  }
}

Status Code 500: When token is already revoked

 Error Response - Token Already Revoked
Copy{
  "error": {
    "code": "SERVER_ERROR",
    "description": "The server encountered an error. The  incident has been reported to admins"
  }
}

3. Access Resources using Access Token🔗

After you obtain an access token, you can use it to access the 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.

Bearer Authorisation🔗

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 Response
Copycurl -X GET https://api.razorpay.com/v1/payments
-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"
Copy{
  "entity": "collection",
  "count": 2,
  "items": [
    {
      "id": "pay_G8VaL2Z68LRtDs",
      "entity": "payment",
      "amount": 900,
      "currency": "INR",
      "status": "captured",
      "order_id": "order_G8VXfKDWDEOHHd",
      "invoice_id": null,
      "international": false,
      "method": "netbanking",
      "amount_refunded": 0,
      "refund_status": null,
      "captured": true,
      "description": "Purchase Shoes",
      "card_id": null,
      "bank": "KKBK",
      "wallet": null,
      "vpa": null,
      "email": "gaurav.kumar@example.com",
      "contact": "+919999999999",
      "customer_id": "cust_DitrYCFtCIokBO",
      "notes": [],
      "fee": 22,
      "tax": 4,
      "error_code": null,
      "error_description": null,
      "error_source": null,
      "error_step": null,
      "error_reason": null,
      "acquirer_data": {
        "bank_transaction_id": "0125836177"
      },
      "created_at": 1606985740
    },
    {
      "id": "pay_G8VQzjPLoAvm6D",
      "entity": "payment",
      "amount": 1000,
      "currency": "INR",
      "status": "captured",
      "order_id": "order_G8VPOayFxWEU28",
      "invoice_id": null,
      "international": false,
      "method": "upi",
      "amount_refunded": 0,
      "refund_status": null,
      "captured": true,
      "description": "#G8VPNzYJsQWMvY",
      "card_id": null,
      "bank": null,
      "wallet": null,
      "vpa": "gaurav.kumar@exampleupi",
      "email": "gaurav.kumar@example.com",
      "contact": "+919999999999",
      "customer_id": "cust_DitrYCFtCIokBO",
      "notes": [],
      "fee": 24,
      "tax": 4,
      "error_code": null,
      "error_description": null,
      "error_source": null,
      "error_step": null,
      "error_reason": null,
      "acquirer_data": {
        "rrn": "033814379298"
      },
      "created_at": 1606985209
    }
  ]
}

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

Next Step🔗

Test Integration

ON THIS PAGE

3. Access Resources using Access Token

Bearer Authorisation

Next Step