API Authentication

Almost all Cashfree APIs require authentication. There are some exceptions like the /order/sessions Payments API.

Payment Gateway requires its own client ID and client secret. Payouts and Secure ID share a separate set of keys. For example, if you use both the Payments API and the Payouts API, you must generate one set of keys for the Payments API and a different set of keys for the Payouts API.

Types of API credentials

The credentials you need depend on how you integrate with Cashfree. The following table maps each credential to the names you may see in the documentation, SDKs, and sample code, and shows where to get it:

Credential	Also referred to as	Request header	Who needs it	Where to get it
App ID	Client ID, `appId`, `CASHFREE_APP_ID`	`x-client-id`	All merchants	Generate API keys in the Merchant Dashboard
Secret Key	Client secret, `secretKey`, `CASHFREE_SECRET_KEY`	`x-client-secret`	All merchants	Generate API keys in the Merchant Dashboard
Partner API Key	`CASHFREE_PARTNER_API_KEY`	`x-partner-apikey`	Embedded Partners only	Generate partner API keys in the Partner Dashboard
OAuth Client ID	`oauth-client-id`, `CASHFREE_OAUTH_CLIENT_ID`	Not applicable	Software partners using the OAuth flow only	Create an OAuth application in the Partner Dashboard
OAuth Client Secret	`oauth-client-secret`	Not applicable	Software partners using the OAuth flow only	Create an OAuth application in the Partner Dashboard

If you are a merchant integrating Cashfree into your own website or app, you need only the App ID and Secret Key. The Partner API Key, OAuth Client ID and OAuth Client Secret apply only to platforms that process payments on behalf of other businesses, and require a partner account with Cashfree.

Merchant authentication

The standard authentication for merchants uses two specific headers x-client-id and x-client-secret. Pass your appId and secretKey in these fields.
Ensure that you place your secret key securely and that no one else can access it.
Also never call any API which requires authentication from the client as that would require you to expose the secret key to the client.

Below is a curl request which shows how to send these headers in the API call.

curl --request {REQUEST-TYPE} \
  --url https://sandbox.cashfree.com/pg/{resource} \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: 2025-01-01' \
  --header 'x-client-id: <YOUR_APP_ID>' \
  --header 'x-client-secret: <YOUR_SECRET_KEY>'
  ...
  ...

Generate API keys

Payment Gateway uses its own client ID and client secret, while Payouts and Secure ID share one set of keys. Use this procedure to generate API keys for Payment Gateway, Payouts or Secure ID from the Merchant Dashboard.

Before you beginMake sure the following are in place:

You are the account owner, or your role has access to API keys. Among the default roles, Admin and Developer have this access. For more information, see Access management.
To generate production keys, your account is activated for the product. You can generate test keys before activation. For more information, see Account activation.
You can complete two-factor authentication (2FA) on the Merchant Dashboard. You need 2FA to generate production keys and to view Payment Gateway production keys.

Payment Gateway keys do not work with the Payouts or Secure ID APIs, and Payouts or Secure ID keys do not work with the Payments API. If you use both the Payments API and the Payouts API, generate keys separately in Payment Gateway and in Payouts. Keys that you generate in Payouts or Secure ID work with both the Payouts API and the Secure ID API.

To generate your API keys:

Log in to the Merchant Dashboard. On the home page, select the product you need keys for: Payment Gateway, Payouts or Secure ID.

Select the environment

Choose the environment that matches your integration stage:

Test: Click Switch to Test in the top-right corner to generate sandbox credentials. A yellow banner shows that you are in the test environment.
Production: Stay in the production environment to generate live credentials. If you are in the test environment, click Switch to Prod.

Each environment has its own set of keys, so use the correct set for the environment you work in.

Open API Keys

Go to Developers > API Keys.For Payment Gateway, you can also go directly to your Production API credentials.

Generate the keys

Click Generate API Keys. If you are in the production environment, complete the 2FA verification when prompted.

In the Payment Gateway test environment, Cashfree generates your API keys automatically. Skip to the next step.

View and copy the keys

The dashboard shows the keys in a masked format. To see the full keys, click the icon next to the key and select View API Key. In the production environment, complete the 2FA verification when prompted.

API Keys page in the Merchant Dashboard showing the View API Key option

Copy the client ID and client secret.

Store the keys securely

Save the keys in a secure location, such as a secrets manager. Never expose the client secret in client-side code, public repositories or support tickets.

You now have a client ID and client secret for the selected product and environment. Pass them in the x-client-id and x-client-secret headers of your API requests.

The number of API keys you can have depends on the product:

Payment Gateway: One API key pair at a time.
Payouts and Secure ID: Up to 10 API keys, shared between both products.

The following example uses Payment Gateway test keys to fetch an order with the Get Order API:

curl --request GET \
  --url https://sandbox.cashfree.com/pg/orders/<ORDER_ID> \
  --header 'x-client-id: <CLIENT_ID>' \
  --header 'x-client-secret: <CLIENT_SECRET>' \
  --header 'x-api-version: 2025-01-01'

If the keys are valid, the API returns the order details:

{
  "cf_order_id": "2149460581",
  "order_id": "<ORDER_ID>",
  "order_amount": 22,
  "order_currency": "INR",
  "order_status": "ACTIVE"
}

If the keys are missing, invalid or belong to a different product or environment, the API returns HTTP status 401 with an authentication error:

{
  "message": "authentication Failed",
  "code": "request_failed",
  "type": "authentication_error"
}

Troubleshooting

If you run into problems while generating or using your keys, check the following:

The Developers section or API Keys option is not visible

Your role might not have access to API keys. Ask your account owner to assign you the Admin or Developer role, or a role that includes access to API keys.

API requests fail with an authentication error

Check that the keys belong to the product you are calling: Payment Gateway keys for the Payments API, and Payouts or Secure ID keys for the Payouts API and the Secure ID API. Also check that the environment matches the base URL: test keys with sandbox URLs and production keys with production URLs.

You lost your client secret

Go to Developers > API Keys and generate a new set of keys. Update your integration with the new keys.

Partner authentication

If you are building a platform and want to use the Payment APIs on behalf of your customers you can do so using by leveraging authentication for platforms. You should use the x-partner-apikey and x-partner-merchantid headers instead of the x-client-id and x-client-secret headers.

x-partner-apikey: This is the common API Key generated and unique for each Partner
x-partner-merchantid: This is the unique merchant ID for each merchant associated with the Partner.
To view the merchant ID for each merchant, login to your Cashfree Partner Dashboard with your partner login credentials > go to the Merchants section, and copy the Merchant ID of the respective merchant.

To generate your partner API key, see Generate partner API keys.

​Types of API credentials

​Merchant authentication

​Generate API keys

​Troubleshooting

​Partner authentication

Types of API credentials

Merchant authentication

Generate API keys

Troubleshooting

Partner authentication