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. 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 theirclient_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_idandclient_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.To create an application:
- Log in to the Dashboard and navigate to Applications under Partners.
- 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.
- 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.
- Edit the Redirect URIs for your clients if needed.
- 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, allGETAPI 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, allGETAPI 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:
- 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
stateparameter. - Razorpay sends back the same
statevalue 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_idand 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 theredirect_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
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:
testlive(default)
Handy Tips
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.
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
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
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_tokenrefresh_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 theBearer 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 theaccess_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 gettingaccess_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 theaccess_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
2. Public Token
Using thepublic_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
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 therazorpay_signature returned to you by the Checkout form:
-
Create a signature in your server using the following attributes:
order_id: Retrieve theorder_idfrom your server. Do not use therazorpay_order_idreturned by Checkout.razorpay_payment_id: Returned by Checkout.client_secret: Available in your server. Theclient_secretthat was generated from the RazorpayDashboard.
-
Use the SHA256 algorithm, the
razorpay_payment_idand theorder_idto construct a HMAC hex digest as shown below:HMAC Hex Digest -
If the signature you generate on your server matches the
razorpay_signaturereturned 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 theaccount.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