API ReferenceIntegrationsKnowledge Base

API Reference Guide

Razorpay APIs are completely RESTful and all our responses are returned in JSON.

You can use Razorpay APIs in two modes, Test and Live. The API key is different for each mode. Refer to the Generate API Key section below for more details.

Integrations:

  • Looking to integrate your website, ecommerce store or mobile app with Razorpay Payment Gateway? Visit the Introduction to Razorpay page to find the right integration method for you.
  • You can also accept payments without a website or app using other Razorpay products, such as Payment Links, Payment Pages, Subscription Links, Invoices and Smart Collect.
  • If you are looking for S2S integration, contact Support team with your requirements.

API Gateway URL#

The Razorpay API Gateway URL is https://api.razorpay.com/v1. You need to include this before each API endpoint to make API calls.

Recommendation:
While sending API requests to Razorpay servers, it is recommended to honor the TTL of the entries and not cache the DNS aggressively at your end. This is applicable when you are not using Razorpay SDKs. However, if you are using Razorpay SDKs, be informed that our SDKs can handle DNS caching and honor the TTLs that are set in the records.

API Authorization#

All Razorpay APIs are authorized using Basic Authorization. Basic authorization requires the following:

  • <YOUR_KEY_ID>
  • <YOUR_KEY_SECRET>

Generate API Key#

  1. Log into your Dashboard with appropriate credentials.
  2. Select the mode (Test or Live) for which you want to generate the API key. Note:
    You have to generate separate API Keys for the test and live modes. No real money is used in test mode.
  3. Navigate to Settings → API Keys → Generate Key to generate key for the selected mode.

The Key Id and Key Secret appear in a pop-out window as shown below:

Note:
After generating the keys from the Dashboard, download and save them securely. If you do not remember your API Keys, you need to re-generate it from the Dashboard and replace it wherever required.

Errors#

All successful responses are returned with HTTP Status code 200. In case of failure, Razorpay API returns a JSON error response with the parameters that detail the reason for the failure.

Note:
If you are using an official Razorpay Language-wise SDK Integration, the error responses result in exceptions that need to be handled in your integration.

Error Response#

The error response contains code, description, field, source, step, reason and metadata parameters that help you diagnose and solve the error
.

Response Parameters#

error

object The error object.

code

string Type of the error.

description

string Descriptive text about the error.

field

string Name of the parameter in the API request that caused the error.

source

string The point of failure in the specific operation (payment in this case). For example, customer, business

step

string The stage where the transaction failure occurred. The stages can vary depending on the payment method used to complete the transaction.

reason

string The exact error reason. It can be handled programmatically.

metadata

object Contains additional information about the request.

payment_id
string Unique identifier of the payment.
order_id
string Unique identifier of the order associated with the payment.

To understand more about error codes, refer to the Error Codes section.

Entity#

Every API response contains entities that are shared across different endpoints. There are some common attributes for every entity.

entity
string Indicates the type of the entity.
id
integer A unique identifier of the entity.

In an entity, the attributes can be utilized to make entity-specific API calls. For example, you can fetch the payment ID from an order.paid webhook and use it to initiate a refund for that payment.

Collection Entity#

Razorpay API also supports returning multiple entities, for a single request. This response also has another entity collection. For the collection entity, the following parameters are common.

entity
string Indicates the type of the entity. For example, collection.
count
integer Indicates the number of items are returned. For example, 2.
items
array The list of entities.

Notes#

The majority of the entities allow notes object to store additional information and preserve data that is relevant to your integration. It is not used by Razorpay for any operational purposes.

The notes object is a set of key-value pairs that can be used to store additional information about the entity. It can hold a maximum of 15 key-value pairs, each 256 characters long (maximum).

For example, you can store the notes related to:

  • Billing or shipping address of the initiated payment.
  • Reference ID generated for an order.

Query Parameters#

You can send the following query parameters to apply filters on the bulk data and view only the appropriate response.

from
integer Timestamp, in Unix, after which the entities are created.
to
integer Timestamp, in Unix, before which the entities are created.
count
integer Number of entities to fetch. Defaults to 10. This can be used for pagination, in combination with skip.
skip
integer Number of entities to skip. Defaults to 0. This can be used for pagination, in combination with count.
‹›
×