Skip to content
Fixedmark

Payments and India APIs · 11 min read

Updated

Cashfree Payouts IP Whitelisting vs Signature Auth

Cashfree Payouts rejects production API calls unless they come from a whitelisted IPv4 address or carry an `X-Cf-Signature` header, which is your client ID and a Unix timestamp encrypted with a Cashfree-issued RSA public key. Your account uses one method at a time. On serverless platforms with changing IPs, the signature is usually the simpler choice. A static IP fits when you also call APIs that only accept IPs.

On this page

Which Cashfree APIs check your IP

Cashfree calls this layer two-factor authentication (2FA). Your client ID and secret are the first factor. The second is proof of where the call comes from, or proof that the caller holds a key Cashfree issued. The Payouts 2FA docs say that if the IP is not whitelisted, the production server rejects all incoming requests. The same page names the public key as the option for servers with a dynamic IP.

Not every Cashfree product works this way. The Payouts IP whitelist FAQ states that Payment Gateway APIs do not require IP whitelisting. Checkout and order APIs can run from anywhere. Secure ID (the verification APIs for bank account, PAN, and similar checks) has its own 2FA setting and is stricter than Payouts.

Cashfree products and their caller checks, as documented in November 2026
ProductBase URL (production)Caller check
Payouts v2https://api.cashfree.com/payoutWhitelisted IPv4 or x-cf-signature
Payouts v1 and v1.2https://payout-api.cashfree.comWhitelisted IPv4 or a signature on the authorize call
Secure ID (verification)https://api.cashfree.com/verificationWhitelisted IPv4 or x-cf-signature, in sandbox and production
Payment Gatewayhttps://api.cashfree.com/pgNo IP whitelisting

For Secure ID, the Secure ID getting started guide says you cannot disable 2FA in any environment, sandbox included. For Payouts, the getting started page frames the check around production, but the dashboard also has a 2FA setting in test mode. If sandbox calls fail with an IP error, set the test account's 2FA method too.

One 2FA method is active at a time

This detail decides most designs. In the dashboard, Developers, then Two-Factor Authentication, has a Select 2FA Method drop-down with two choices, IP Whitelist and Public Key. The Secure ID IP whitelisting page is explicit about how it behaves.

  • A Switch Method button toggles the active method. The drop-down only adds IPs or generates keys for the method that is already active. Choosing a different option in it does not switch anything.
  • Send x-cf-signature only when Public Key is active. Do not send it while IP Whitelisting is active.
  • When Public Key is active, every call must carry the header, or you get a missing-signature error.

The Payouts docs describe the same drop-down and a Switch Mode button for the test account, so plan as if Payouts behaves the same way. You cannot accept whitelisted IPs from your office servers and signatures from your Lambda functions on one account. Pick one method per account and environment, and move every caller to it together.

Switching methods is a cutover. Deploy the signing code behind a flag first, switch the method in the dashboard, then turn the flag on. Expect a short window of failed calls, and schedule it when no payout batch is running.

Whitelist a server IP

Whitelisting suits callers with a fixed public IPv4 address, such as a VM with an elastic IP, an office line, or a static egress proxy. First confirm the address the internet sees. Run this on the machine that will call Cashfree, not on your laptop.

Terminal
# Force IPv4. Cashfree whitelists IPv4 only.
curl -4 https://api.ipify.org
  1. 1
    Open the 2FA pageIn the Merchant Dashboard, open Payouts, then Developers, then Two-Factor Authentication. Use Switch to Test first if you are setting up the sandbox account.
  2. 2
    Check the active methodMake sure IP Whitelist is the active method. If Public Key is active, use Switch Method (or Switch Mode) to change it.
  3. 3
    Add each addressClick Add IP Address and enter one IPv4 address at a time. Secure ID docs say CIDR ranges and private addresses are refused, so add single public addresses only.
  4. 4
    Repeat on every Payouts accountIf your business has more than one Payouts account, whitelist the IP on each one, and check that your API keys belong to the account you mean.
  5. 5
    Wait, then testThe Secure ID docs say to wait at least 5 seconds after adding an address before retrying. Then make one call from the server and check the response.

Limits matter less than they look. The Payouts docs say 25 IPs in most places and 10 in one step of the 2FA page. A static IP pair needs two slots, so either figure leaves room for staging and a spare. IPv6 is not supported for API requests, which bites when a host prefers IPv6 for outbound traffic. If that is your stack, read IPv6 egress and IPv4-only allowlists.

One more trap from the getting started page. The Postman web app sends requests from Postman's cloud, whose IPs change, so IP-whitelisted calls fail there. The desktop app sends from your own connection. Signature-based calls work from both.

Sign requests with the public key

The signature method removes the network check. Switch the active method to Public Key, then click Generate Public Key. A PEM file downloads. In production the file is password protected, and Cashfree's current docs say the password goes to your registered email address. The Secure ID docs add that you can download the key only once, and both products allow one key at a time. Put the PEM in your secret manager right away.

To build a signature, take the client ID you send in x-client-id, append a period and the current Unix time in seconds, and encrypt that string with the PEM key using RSA-OAEP with SHA-1. Base64-encode the result and send it as x-cf-signature. A signature is valid for 5 minutes, so make a fresh one per request or cache it for a few minutes at most. The Secure ID guide names SHA-1 outright, and the Java sample on the Payouts page uses RSA/ECB/OAEPWithSHA-1AndMGF1Padding.

import { constants, publicEncrypt } from "node:crypto";
import { readFileSync } from "node:fs";

// The PEM from Developers > Two-Factor Authentication > Public Key.
const publicKey = readFileSync(process.env.CASHFREE_PUBLIC_KEY_PATH, "utf8");

export function cashfreeSignature(clientId) {
  const timestamp = Math.floor(Date.now() / 1000);
  const encrypted = publicEncrypt(
    {
      key: publicKey,
      padding: constants.RSA_PKCS1_OAEP_PADDING,
      oaepHash: "sha1",
    },
    Buffer.from(`${clientId}.${timestamp}`),
  );
  return encrypted.toString("base64");
}

Each sample produces a value that decrypts back to clientId.timestamp with the matching private key, using OAEP and SHA-1 for both the digest and MGF1. Node's publicEncrypt already defaults to OAEP with SHA-1, as the Node.js crypto docs state. The sample sets both options anyway, so a reader does not have to know the defaults.

Send it on a Payouts v2 call

Payouts v2 takes the signature on every request, next to the credentials and the x-api-version header. This curl call fetches a transfer's status against the sandbox, which moves no money. It builds the signature with openssl so you can test the key before writing code.

Terminal
SIG=$(printf '%s.%s' "$CF_CLIENT_ID" "$(date +%s)" \
  | openssl pkeyutl -encrypt -pubin -inkey cashfree_public_key.pem \
      -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha1 \
  | openssl base64 -A)

curl -sS "https://sandbox.cashfree.com/payout/transfers?transfer_id=test_001" \
  -H "x-client-id: $CF_CLIENT_ID" \
  -H "x-client-secret: $CF_CLIENT_SECRET" \
  -H "x-api-version: 2024-01-01" \
  -H "x-cf-signature: $SIG"

On the older v1 API, the signature goes on POST /payout/v1/authorize, which returns a bearer token for the other calls. The authorize reference says that token lasts 6 minutes, so v1 code signs once per token refresh rather than once per call.

What the signature does and does not prove

Cashfree calls the file a public key, but it works like a shared secret. Encryption with a public key needs nothing else, so anyone who holds the PEM and your client credentials can make valid signatures from any network. Store the PEM with the same care as the client secret. Do not commit it, and do not ship it to a browser or a mobile app. An IP whitelist protects against a different failure. A leaked secret and key still fail from any address you did not list.

Calling Cashfree Payouts from serverless

Serverless platforms rarely give you a fixed outbound address by default. Vercel's static IP guide says functions use dynamic IP addresses unless you buy its Static IPs option, which is on Pro and Enterprise plans and shared by a small group of customers per region. On AWS Lambda, a fixed address means attaching the function to a VPC with private subnets and a NAT gateway with an elastic IP, as the Lambda internet access guide lays out. Why serverless egress IPs change covers the other platforms.

For Cashfree alone, the signature is the shortest path. It needs a file and ten lines of code, and it works the same on Vercel, Railway, Render, Lambda, and a cron container. The Secure ID page even names Render as a host where IP whitelisting may not be feasible. A fixed IP still earns its place in some setups.

Choosing a 2FA method for Cashfree Payouts
SituationBetter fitWhy
Only Cashfree needs a check, app on Vercel or LambdaPublic keyNo network setup and nothing to pay for beyond your hosting.
You also call RazorpayX, a bank API, or a brokerStatic IPThose accept only IPs, so one fixed egress pair serves every partner.
Your security team wants a leaked key to be useless off your networkStatic IPThe whitelist holds even when the secret and PEM leak.
Many services in many repos call PayoutsStatic IPOne whitelist entry per address, instead of one PEM copied into every environment.
You run on a VM that already has an elastic IPStatic IPThe address exists already. Whitelist it and skip the signing code.

If RazorpayX is in the same app, note that it has no signature fallback for live payout APIs. RazorpayX Payouts IP whitelisting walks through that side. With a static pair for RazorpayX in place, pointing Cashfree at the same pair keeps one model for both gateways.

Whichever method you pick, route only the calls that need it. Checkout, order creation, and Payment Gateway webhooks do not touch the 2FA check, so they can leave the platform directly. In Next.js, use a per-request dispatcher for the payout client only, as shown in routing only some fetches through a proxy.

Errors you will see and what they mean

Cashfree documents a few 2FA errors. The strings in code below come from its docs. Payouts response bodies can differ by API version, so match on the documented code where there is one and log the full body.

Cashfree 2FA errors and their usual causes
ErrorWhereUsual cause
Signature missing in the requestPayoutsPublic Key is the active method and the request has no X-Cf-Signature header.
A signature mismatch errorPayouts and Secure IDA different client ID in the header and the signed string, a timestamp older than 5 minutes, wrong padding, or a key and client ID from different environments.
ip_validation_failedSecure IDThe calling IP is not on the list, or it was added under a different account from the one that owns the client ID.
IP not whitelisted, after you whitelisted itPayoutsThe IP is on one Payouts account and the keys belong to another, the call left over IPv6, or it came from a different host than you tested.
Invalid clientId and clientSecret combinationPayoutsWrong credentials, or test credentials against the production URL. Credentials are separate per environment.

When an IP error makes no sense, check the address Cashfree saw, not the one you expect. Log the egress IP from inside the function that makes the call. A container that makes one call from a NAT address and the next from another will fail some of the time, which looks random until you compare addresses. Static IP pairs and failover explains why every address in a pair must be on the list.

A 5xx on a transfer does not mean the transfer failed. Cashfree's v2 overview says not to start another transaction after a 5XX response. Call Get Transfer Status with the same transfer_id first, so a retry never pays twice.

Webhooks run the other way

2FA covers calls you make to Cashfree. Payout webhooks are calls Cashfree makes to you, so neither the IP whitelist nor the public key applies to them. The Payouts v2 webhooks page publishes separate source IPs for UAT and production if you want to firewall your endpoint. Verify the signature on every webhook either way. Allowlisting payment webhook source IPs covers that side in depth.

Doing this with Fixedmark

If you choose the IP route, Fixedmark gives your app a pair of static IPv4 addresses and one proxy URL. Fixedmark is in early access. A dedicated pair comes with the Pro plan at a planned $29 a month. The trial runs on a shared pair, so do not whitelist trial addresses with Cashfree. For an Indian payout API, pick the Mumbai region. See regions and pricing.

  1. 1
    Whitelist both addressesAdd both IPs of your Mumbai pair under IP Whitelist in each Payouts account. Each new connection leaves from either address, so one entry alone fails part of the time.
  2. 2
    Store the proxy URLSet FIXEDMARK_PROXY_URL in your platform's environment, next to the Cashfree credentials.
  3. 3
    Proxy the payout client onlyGive the Cashfree Payouts client its own dispatcher or HTTP client with the proxy. Leave other traffic direct.
  4. 4
    Check the egress IPRun curl --proxy "$FIXEDMARK_PROXY_URL" https://fixedmark.com/api/ip a few times and confirm both addresses match the whitelist. The egress IP guide has more checks.
cashfree.mjs
// npm install undici  (undici 8 needs Node.js 22.19+)
import { fetch, ProxyAgent } from "undici";

const proxy = new ProxyAgent(process.env.FIXEDMARK_PROXY_URL);

export async function getTransfer(transferId) {
  const url = new URL("https://api.cashfree.com/payout/transfers");
  url.searchParams.set("transfer_id", transferId);
  const res = await fetch(url, {
    dispatcher: proxy,
    headers: {
      "x-client-id": process.env.CASHFREE_CLIENT_ID,
      "x-client-secret": process.env.CASHFREE_CLIENT_SECRET,
      "x-api-version": "2024-01-01",
    },
  });
  if (!res.ok) throw new Error(`Cashfree ${res.status}: ${await res.text()}`);
  return res.json();
}

Payout calls pass through as an encrypted CONNECT tunnel. Fixedmark never decrypts them, so it never sees amounts, account numbers, or your Cashfree secret. Its connection logs record the destination, SNI, bytes, egress IP, and result, which helps when Cashfree reports an IP error. On plans with destination allowlists, limit the proxy token to api.cashfree.com on port 443 so a leaked token reaches nothing else. Setup for other runtimes is in the Node.js and Python guides.

Sources

Checked November 2026. Confirm current details on the vendor's site before you decide. Prices and limits change.

Blog

Frequently asked questions

Can I use IP whitelisting and the public key at the same time?

Plan as if you cannot. Cashfree's Secure ID docs say one 2FA method is active at a time and that you should not send `x-cf-signature` while IP Whitelisting is active. The Payouts dashboard uses the same method selector and switch control.

Do Cashfree Payment Gateway APIs need IP whitelisting?

No. Cashfree's FAQ states that Payment Gateway APIs do not require IP whitelisting. The check applies to products such as Payouts and Secure ID.

Does Cashfree accept IPv6 addresses or CIDR ranges?

No. Cashfree whitelists single public IPv4 addresses only. Its Secure ID docs also rule out CIDR ranges and private addresses. Force IPv4 in your client if your host prefers IPv6.

How long is an x-cf-signature valid?

Five minutes. Build the signature from the current Unix time in seconds and make a new one at least every 5 minutes. A signature with an older timestamp fails with a mismatch error.

Is the Cashfree public key safe to commit to my repository?

No. Anyone with the PEM and your client credentials can produce valid signatures, because encryption with a public key needs nothing else. Keep it in a secret manager next to the client secret.

Make it fixed.

Fixedmark is in early access. Join the list to get dedicated static IPs when your region opens.