API ReferenceIntegrationsKnowledge Base

API Reference Guide

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

API Endpoint#

The base URL of all our APIs are: https://api.razorpay.com/v1

Authentication#

To use Razorpay APIs, you can generate an API key on your Dashboard, under Settings > API Keys.

Note:
After generating the keys from the Dashboard, you must download and save them securely. Razorpay does not store your key secret. If you lose access to your key secret, you can generate a new key from your dashboard and update all your integrations.

An API key consists of a Key ID and a Key Secret.

Note:
The API Key ID is used to initiate payments, and can be exposed publicly. The API Key Secret is like your password, and should not be exposed or used for client-side requests.

Razorpay APIs use basic access authentication to authenticate all server-side requests. The API Key can be used for basic authentication by sending the Key ID as the username and the Key Secret as the password.

For example, you can access your payments at
https://<key-id>:<key-secret>@api.razorpay.com/v1/payments.

Note:
You should check the HTTP Status code of the response for every request to API.

Errors#

In case of an error, Razorpay API returns a JSON with an error code and description. In case the error is in a specific field, it also returns the field name in the error object.

All successful responses are returned with HTTP Status code 200.

In case you are using official Razorpay SDKs, error responses will result in an exception which you need to catch and handle in your integration.

Error Codes#

GATEWAY_ERROR
Error in Gateway Communication. See description for more details.
BAD_REQUEST_ERROR
Error in merchant request. Check the description and correct the request accordingly.
SERVER_ERROR
There is some problem with the server.

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 entity.
id
integer An unique identifier of the entity.

In an entity, the attributes can be utilized for making 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.

Notes#

Many of Razorpay's entities allow additional information to be stored in the Notes object, in order to persist data that is relevant to your integration. It is not used by Razorpay for any operational purposes.

The notes field is a key-value store and can have a maximum of 15 key-value pairs, each of 256 characters (maximum).

For example, when initiating Payments, you can store the billing or shipping address in the notes field. When creating an order, you can enter the reference ID generated at your end in the notes field.

Collection Entity#

Razorpay API also supports returning multiple entities such as payments, refunds for a single request. This response is itself an entity of the type 'collection'. Every collection entity will have the following common attributes.

entity
string Indicates type of entity, collection.
count
string Indicates type of entity, collection.
item
array List of entities.

Pagination#

from
integer Timestamp, in seconds, after which the entities were created.
to
integer Timestamp, in seconds, before which the entities were created.
count
integer Number of entities to fetch. Defaults to 10.
skip
integer Number of entities to be skipped. Defaults to 0.