Resources

Here you can find all the basic resources for the new integration.

INTEGRATION TOOLKIT

Try our Integration

Use the below attributes to try out the integration in sandbox.

AttributeValueDescription
Sandbox endpointhttps://sandbox.cashfree.com/pgUse this endpoint to access any resource for the new API. For example - to create an order use the following complete URL - https://sandbox.cashfree.com/pg/orders
Production endpointhttps://api.cashfree.com/pgUse this endpoint to access any resource for the new API. For example - to create an order use the following complete URL in production - https://api.cashfree.com/pg/orders
x-client-idSample value: 193asdlfjl1adf891You can access the appId from the PG merchant dashboard.
x-client-secretSample value: hkahlyoi08918212khldhgb1You can access the secret key from the PG merchant dashboard.
x-api-version2022-09-01With every new update, we will publish a new version for the docs. As of now there, are three version 2021-05-21, 2022-01-01 and latest 2022-09-01.
x-idempotency-keystring(uuid)You can use this to avoid duplicate operations

Errors

The error object looks as below. Any non 200 response should be treated as an error. For example if you do not pass the version header, the api will respond with a 400 response code (bad request). The type and code variables should help you identify what is wrong with your requests.

{
  "message": "version is missing in header",
  "code": "request_failed",
  "type": "invalid_request_error"
}

The following is an exhaustive list of error types.

Error TypeDescription
authentication_errorAuthentication error is thrown if your x-client-id or x-client-secret are incorrect.
invalid_request_errorInvalid request error is thrown when your request body or request headers are not in order.
rate_limit_errorRate limit error is thrown with response cod 429. We throw this error when you breach our API limits. You can use the response headers to know more about the limits and other details. (see below for more details).
api_errorSomething went wrong with the API. Please retry after sometime.

Rate limiting

We use rate limiting for all endpoints. Rate limiting is based on your IP and your account Id. By default the following rate limits are applied per minute. You can also view your rate limits in the response headers.

Rate Limits in Sandbox

APIRate limit value per minuteRate limit type
Create Order30Account
Get Order60Account
Get Payments30Account
Pay Order30IP
Get Settlements20Account
Initiate Refund30Account
Get refund60Account

Rate Limit in Production

APIRate limit value per minuteRate limit type
Create Order200Account
Get Order400Account
Get Payments100Account
Get Payments by ID130Account
Pay Order100IP
Get Settlements30Account
Initiate Refund100Account
Get Refund30Account

📘

Custom Rate Limits

The rate limits mentioned above are default rate limits. However, we have an option to provide custom rate limits and burst limits at an account level depending on the usage and use case. Please contact [email protected] to know more.

You can view your api usage and rate limits on your merchant dashboard.

  1. Go to Developers>Rate Limits
  2. You can view your rate limit, burst limit, API usage and violation of various APIs.
2998

Rate limiting headers

All responses will have the following headers to help merchants understand rate limiting

Header nameExampleDescription
x-ratelimit-limit100Max number of calls that can be made in a minute
x-ratelimit-remaining30Remaining number of calls that can be made in a minute
x-ratelimit-retry0Number of seconds you will have to wait to make the next call
x-ratelimit-typeapp_id or ipType of rate limiting applied

Idempotency

Idempotency works by saving the resulting status code and body of the first request made for any given idempotency key, regardless of whether it succeeded or failed. Subsequent requests with the same key return the same result, including 500 errors.
Currently supported on all POST calls that uses x-client-id & x-client-secret. To use enable, pass x-idempotency-key in the request header. The value of this header must be unique to each operation you are trying to do. One example can be to use the same order_id that you pass while creating orders

Header nameExampleDDescription
x-idempotency-replayedtrue or falseIf the request was successful earlier you would get true
x-idempotency-keystring, uuid etcA key for idempotency

Timeout Configuration

We suggest to set specific timeouts for each API that your application makes. You can use below timeouts as reference for our APIs.

APITimeout (seconds)
Create Order5
Get Order5-8
Pay Order12-15
Get Payments5-8
Get Settlements12-15
Initiate Refund4-6
Get refund4-6