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.
| Product | Base URL (production) | Caller check |
|---|---|---|
| Payouts v2 | https://api.cashfree.com/payout | Whitelisted IPv4 or x-cf-signature |
| Payouts v1 and v1.2 | https://payout-api.cashfree.com | Whitelisted IPv4 or a signature on the authorize call |
| Secure ID (verification) | https://api.cashfree.com/verification | Whitelisted IPv4 or x-cf-signature, in sandbox and production |
| Payment Gateway | https://api.cashfree.com/pg | No 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-signatureonly 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.
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.
# Force IPv4. Cashfree whitelists IPv4 only.
curl -4 https://api.ipify.org- 1Open 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.
- 2Check the active methodMake sure IP Whitelist is the active method. If Public Key is active, use Switch Method (or Switch Mode) to change it.
- 3Add 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.
- 4Repeat 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.
- 5Wait, 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");
}# pip install cryptography
import base64
import os
import time
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding
with open(os.environ["CASHFREE_PUBLIC_KEY_PATH"], "rb") as f:
PUBLIC_KEY = serialization.load_pem_public_key(f.read())
def cashfree_signature(client_id: str) -> str:
message = f"{client_id}.{int(time.time())}".encode()
encrypted = PUBLIC_KEY.encrypt(
message,
padding.OAEP(
mgf=padding.MGF1(algorithm=hashes.SHA1()),
algorithm=hashes.SHA1(),
label=None,
),
)
return base64.b64encode(encrypted).decode()package cashfree
import (
"crypto/rand"
"crypto/rsa"
"crypto/sha1"
"crypto/x509"
"encoding/base64"
"encoding/pem"
"errors"
"fmt"
"time"
)
// Signature encrypts "clientID.unixSeconds" with Cashfree's public key.
func Signature(pemBytes []byte, clientID string) (string, error) {
block, _ := pem.Decode(pemBytes)
if block == nil {
return "", errors.New("no PEM block in public key file")
}
parsed, err := x509.ParsePKIXPublicKey(block.Bytes)
if err != nil {
return "", err
}
pub, ok := parsed.(*rsa.PublicKey)
if !ok {
return "", errors.New("public key is not RSA")
}
msg := fmt.Sprintf("%s.%d", clientID, time.Now().Unix())
enc, err := rsa.EncryptOAEP(sha1.New(), rand.Reader, pub, []byte(msg), nil)
if err != nil {
return "", err
}
return base64.StdEncoding.EncodeToString(enc), nil
}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.
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.
| Situation | Better fit | Why |
|---|---|---|
| Only Cashfree needs a check, app on Vercel or Lambda | Public key | No network setup and nothing to pay for beyond your hosting. |
| You also call RazorpayX, a bank API, or a broker | Static IP | Those accept only IPs, so one fixed egress pair serves every partner. |
| Your security team wants a leaked key to be useless off your network | Static IP | The whitelist holds even when the secret and PEM leak. |
| Many services in many repos call Payouts | Static IP | One whitelist entry per address, instead of one PEM copied into every environment. |
| You run on a VM that already has an elastic IP | Static IP | The 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.
| Error | Where | Usual cause |
|---|---|---|
Signature missing in the request | Payouts | Public Key is the active method and the request has no X-Cf-Signature header. |
| A signature mismatch error | Payouts and Secure ID | A 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_failed | Secure ID | The 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 it | Payouts | The 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 combination | Payouts | Wrong 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.
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.
- 1Whitelist 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.
- 2Store the proxy URLSet
FIXEDMARK_PROXY_URLin your platform's environment, next to the Cashfree credentials. - 3Proxy the payout client onlyGive the Cashfree Payouts client its own dispatcher or HTTP client with the proxy. Leave other traffic direct.
- 4Check the egress IPRun
curl --proxy "$FIXEDMARK_PROXY_URL" https://fixedmark.com/api/ipa few times and confirm both addresses match the whitelist. The egress IP guide has more checks.
// 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.
- Cashfree: 2FA, IP whitelisting and public keys (Payouts)
- Cashfree: Payouts IP whitelisting and public key FAQs
- Cashfree: Getting started with Payouts APIs
- Cashfree: Payouts v1 Authorize
- Cashfree: Payouts v2 overview
- Cashfree: Secure ID IP whitelisting
- Cashfree: Secure ID getting started (2FA signature)
- Cashfree: Payouts v2 webhooks and IPs to whitelist
- Vercel: How to allowlist deployment IP addresses
- AWS: Enable internet access for VPC-connected Lambda functions
- Node.js: crypto.publicEncrypt

