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 for now. 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, getting previous payment details . Basic authentication includes using API keys. The API keys is a combination of Key ID and Key Secret where key-id as username and key-secret as password whenever a request is sent from the merchant server.

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

Note:
You can find these keys on your Razorpay's dashboard.

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 with values up to a maximum of 256 characters long.

For example, in Payments, you can store the billing or shipping address 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 or key-secret might 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 timestamp
Timestamp in seconds after which the payments were created
to timestamp
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 contain entities that are shared across origins. Every entity will the following common attributes along with the other attributes.

In an entity, the attributes can be utilized for making an entity-specific API calls. 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 type of entity, for example payment
id string
Unique id that identifies the order on Razorpay

Collection Entity#

Razorpay API also supports returning multiple entities like 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.