API Reference Guide

Razorpay APIs are completely RESTful and all our responses are returned in JSON. We have language bindings in cURL, Java, .NET, PHP, Python, Ruby and Node. cURL examples are provided that can be used in other languages as well.

API Endpoint#

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

Authentication#

Basic authentication is used by Razorpay to authenticate all server-side requests such as capture, refund and fetch previous payment details. Basic authentication includes using API keys. API keys is a combination of Key ID and Key Secret where key-id is used as the username and key-secret as the password, whenever a request is sent from your server.

The API request format is
https://<key-id>:<key-secret>@api.razorpay.com/v1.

Note:
You can generate the API keys on your Dashboard. Watch the generate API keys short animation for more information.

After generating the keys from the Dashboard, you must download and save them securely. Razorpay does not store your Key Secret, so, if you lose it, you will have to regenerate it from the dashboard and update all the integrations with the same.

Note:
Your Key-Secret is like your password. Do not use it for client-side requests or share it with anyone.

Notes#

All the additional information about an entity can be stored in the notes object, if available. It consists of key-value pairs to store any relevant information. It is not used by Razorpay for any operational purposes.

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

For example, in Payments, you can store the billing or shipping address in the Notes field. In Orders, you can enter the Order ID that you generate at your end in the Notes field.

Errors#

Incase of an error during the request, Razorpay API returns 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 the Razorpay SDKs (e.g. PHP SDK), it will throw an exception with the error which you need to catch.

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

HTTP Status Codes#

200 OK
Worked as expected
400 Bad Request
Missing or invalid input
401 Not Authorized
Authentication Error. KEY_ID and KEY_SECRET that you entered could be invalid.
500, 502, 504 Gateway Error
Internal Razorpay Error

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.

Pagination#

from :integer Timestamp, in seconds, after which the payments were created.

to
integer Timestamp, in seconds, before which payments were created.

count :integer Number of payments to fetch. Defaults to 10.

skip :integer Number of payments to be skipped. Defaults to 0.

Entity#

Our response contains entities that are shared across origins. There are some common attributes for every entity.

In an entity, the attributes can be utilized for making an entity-specific API call. For example, in a paid invoice response, you found a payment entity. You can use the payment id and make refund API call, for initiating a refund for the paid amount.

entity :string Indicates the type of entity.

id :integer An unique identifier of the entity.

Collection Entity#

Razorpay API also supports returning multiple entities such as payments, refunds for a single request. Every collection entity will the following common attributes along with the other attributes.

entity
string Indicates type of entity, in this case, the value is collection.
count
string Indicates type of entity, in this case, the value is collection.
item
string Collection of entities.