Skip to main content
Building a reliable Cashfree API integration requires more than correct API calls. These practices cover security, error handling, performance, and testing the areas most likely to cause issues if overlooked.

​
Security

Apply the following practices to protect your API credentials and ensure only legitimate requests reach your integration.

​
Verify webhook signatures

Always verify the signature of every incoming webhook payload before processing it. Skipping this step exposes your integration to spoofed or tampered requests.
Never process a webhook payload without first validating its signature. For step-by-step instructions and code examples, see the webhook signature verification page for your product.

​
Secure your API keys

Exposed API keys (x-client-id and x-client-secret) can result in unauthorised transactions and data breaches. Apply the following controls to protect your keys.
  • Never commit API keys to version control.
  • Never expose API keys in client-side or browser-facing code.
  • Store keys in environment variables or a dedicated secrets manager.
  • Restrict key access to only the services and environments that require it.
  • Rotate keys immediately if you suspect they have been compromised.

​
Avoid logging sensitive data

Do not log raw API request or response bodies that contain sensitive fields such as card numbers, CVVs, bank account details, or authentication tokens. Logging this data creates a PCI DSS compliance risk and increases the potential impact of a security breach.
Log only the fields required for debugging, such as order IDs, status codes, and timestamps.

​
Reliability

Follow these practices to ensure your integration handles failures gracefully and maintains consistent behaviour under load.

​
Use idempotency keys

Include a unique idempotency key in every mutating request (for example, payment creation or refund initiation) using the x-idempotency-key request header. If a request fails or times out, retrying with the same key prevents duplicate transactions. 
x-idempotency-key: <uuid>
Use a UUID as the key value. Generate a new UUID for each logical operation, and reuse the same key only when retrying that specific request.

​
Subscribe to webhooks instead of polling

Subscribe to webhook events instead of polling the API for status updates. Polling consumes rate limit quota and introduces unnecessary latency into your integration. For setup instructions, see webhooks for further detailed information.

​
Avoid concurrent requests

Do not send multiple simultaneous requests from the same account. Concurrent requests increase the likelihood of rate limit errors and can degrade integration performance.
If your use case requires high request volume, use a queue or a similar mechanism to process requests sequentially and manage throughput.

​
Include a request ID

Add a unique identifier to each request using the x-request-id header. This makes it easier to trace requests in logs, correlate errors, and collaborate with Cashfree support during troubleshooting.

​
Performance

Apply the following practices to reduce latency, manage throughput, and make efficient use of your API quota.

​
Handle rate limit errors

When your integration receives a rate limit error, pause all outgoing requests and apply the following logic before retrying.
  • If the x-ratelimit-retry response header is present, wait the number of seconds it specifies before retrying.
  • If the x-ratelimit-remaining header value is 0, do not send another request until the time indicated by x-ratelimit-reset has passed.
When applying exponential backoff, start with a one-second delay and double the wait time with each subsequent attempt (2s, 4s, 8s). Add a small random jitter to each interval to prevent multiple clients from retrying simultaneously. Limit retries to three to five attempts.
To increase your rate limit or burst limit, raise a request through the Merchant Dashboard. For detailed steps, see the rate limits page for your product.

​
Optimise connections with keep-alive

Use HTTP keep-alive to reuse a single connection across multiple API requests. This reduces per-request latency and lowers resource usage on both client and server. Set the following header in all API requests. 
Connection: keep-alive

​
Integration

Follow these practices to ensure your integration stays current, reduces manual effort, and aligns with Cashfree’s supported conventions.

​
Specify the API version

Always use the latest API version to access current features, performance improvements, and security updates. Cashfree APIs use a date-based versioning scheme. Specify the version in the x-api-version request header using the format YYYY-MM-DD. 
x-api-version: 2025-01-01
If you are on an older version, upgrade to the latest to benefit from new capabilities and bug fixes.

​
Use Cashfree SDKs

Cashfree provides official SDKs in popular programming languages to reduce integration effort. The SDKs handle authentication, request and response formatting, response parsing, and error handling.

Cashfree SDKs

Access pre-built libraries for your preferred language and start integrating faster.

​
Testing

Complete all integration testing in the Cashfree sandbox environment before deploying to production. The sandbox replicates production behaviour without processing real transactions. To retrieve your sandbox API keys, follow these steps.
  1. Log in to the Merchant Dashboard and sign in with your credentials.
  2. Navigate to your product under Developers > API Keys.
  3. Copy the test mode keys and use them in your sandbox environment.