Understand Razorpay APIs

REST APIs

REST is an architectural style or design pattern for APIs. When a client request is made through a RESTful API, it transfers a representation of the state of the requested resource. Web services that follow the REST architectural style are called RESTful web services.

A RESTful web application exposes information about its resources. It also enables the client to take actions on those resources, such as creating new resources (for example, creating a new user) or changing existing resources (for example, editing a post).

Resources

A resource is any piece of data that an API can provide, modify, or interact with. It represents an entity or object, such as a customer, payment, order, invoice, or refund.

Each resource is identified by a unique URL (endpoint) and is typically manipulated using HTTP methods.

HTTP Methods

HTTP defines a set of request methods, also known as HTTP verbs, to indicate the desired action for a given resource.

Given below is the list of methods commonly adopted by Razorpay APIs:

curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET]
-X GET https://api.razorpay.com/v1/payments/pay_DG4ZdRK8ZnXC3k

{
  "id": "pay_G3P9vcIhRs3NV4",
  "entity": "payment",
  "amount": 100,
  "currency": "INR",
  "status": "captured",
  "order_id": "order_GjCr5oKh4AVC51",
  "invoice_id": null,
  "international": false,
  "method": "card",
  "amount_refunded": 0,
  "refund_status": null,
  "captured": true,
  "description": "Payment for Adidas shoes",
  "card_id": "card_KOdY30ajbuyOYN",
  "bank": null,
  "wallet": null,
  "email": "gaurav.kumar@example.com",
  "contact": "9000090000",
  "customer_id": "cust_K6fNE0WJZWGqtN",
  "token_id": "token_KOdY$DBYQOv08n",
  "notes": [],
  "fee": 1,
  "tax": 0,
  "error_code": null,
  "error_description": null,
  "error_source": null,
  "error_step": null,
  "error_reason": null,
  "acquirer_data": {
      "auth_code": "064381",
      "arn": "74119663031031075351326",
      "rrn": "303107535132"
  },
  "created_at": 1605871409
}

HTTPS Status Codes

HTTP response status codes indicate whether a specific HTTP request is successfully completed. Responses are grouped into five classes:

• Informational responses (100–199)
• Successful responses (200–299)
• Redirection messages (300–399)
• Client error responses (400–499)
• Server error responses (500–599)

Refer to

Parameter Types

Following table lists the various parameter types with examples:

The following images highlight the different types of API parameters.

Data Types

Razorpay APIs use standard data types to represent different kinds of information in API requests and responses. The following table outlines the primary data types used:

Conventions

Following are some conventions followed in Razorpay APIs:

Entity

All Razorpay API responses carry this attribute with the value being the name of the API resource. For example, "entity: "order". There are some common attributes for every entity.

In an entity, the attributes can be used 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

A list of objects/entities is called collection. Usually, when fetching an API resource using the GET method, multiple entities are expected in the result. In this case, it is returned in a collection form. For the collection entity, the following parameters are common.

Notes

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).

The majority of the entities allow the notes object to store additional information and preserve data relevant to your integration. Razorpay does not use it for any operational purposes.

You can store the notes related to:

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

Identifier

Razorpay attributes are uniquely identified by their identifier which is mostly present in the attribute id. The identifier is of 14 characters, alphanumeric and case-sensitive.

Response Body

When you make a request to the Razorpay API, the server responds with a JSON object containing relevant data. The response body structure varies depending on the API endpoint and the type of request.

Versioning

All Razorpay APIs are backwards-compatible. If an API or its parameters are deprecated, we add a warning note for the same for a specific period of time.

Rate Limiting

Razorpay uses a request Rate Limiter to limit the number of requests received by the API within a time frame. Rate Limiter helps maintain system stability during heavy traffic loads.

• While integrating with any APIs, watch for HTTP status code 429 and build the retry mechanism based on the requirement.
• Use an exponential backoff/stepped backoff strategy to reduce request volume and stay within the limit.
• Add some randomisation within the backoff schedule to avoid the

  thundering herd effect

  .

Pagination

Usually, when you make calls to the Razorpay APIs, there will be a large volume of responses. You can paginate the results to ensure that these responses are easier to handle, using a combination of the query parameters given below to receive a specific number of records in the API response.

Related Information

• Authentication

• Errors

• Best Practices

• Glossary