---
title: "Cashfree Payouts IP Whitelisting vs Signature Auth"
description: "How Cashfree Payouts checks callers: IPv4 whitelisting or an RSA x-cf-signature. Which to pick, how to set each up, and calling Payouts from serverless."
canonical: https://fixedmark.com/blog/cashfree-payouts-ip-whitelisting
updated: 2026-11-10
source: Fixedmark (https://fixedmark.com), BitMask LLP
---

Payments and India APIs · 11 min read

# 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.

## 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](https://www.cashfree.com/docs/payouts/payouts/integrations/payouts-2fa) 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](https://www.cashfree.com/docs/payouts/payouts/integrations/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_

| 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](https://www.cashfree.com/docs/api-reference/vrs/getting-started) says you cannot disable 2FA in any environment, sandbox included. For Payouts, the [getting started page](https://www.cashfree.com/docs/api-reference/payouts/getting-started-with-payouts-apis) 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](https://www.cashfree.com/docs/secure-id/get-started/integration/ip-whitelisting-verification) 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**

```bash
# Force IPv4. Cashfree whitelists IPv4 only.
curl -4 https://api.ipify.org
```

1. 1

   **Open the 2FA page** In 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 method** Make 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 address** Click 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 account** If 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 test** The 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](https://fixedmark.com/blog/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](https://www.cashfree.com/docs/api-reference/vrs/getting-started) names SHA-1 outright, and the Java sample on the Payouts page uses `RSA/ECB/OAEPWithSHA-1AndMGF1Padding`.

**Node.js**

```javascript
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");
}
```

**Python**

```python
# 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()
```

**Go**

```go
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](https://nodejs.org/api/crypto.html) 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**

```bash
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](https://www.cashfree.com/docs/api-reference/payouts/v1/authorize) 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](https://vercel.com/kb/guide/how-to-allowlist-deployment-ip-address) 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](https://docs.aws.amazon.com/lambda/latest/dg/configuration-vpc-internet.html) lays out. [Why serverless egress IPs change](https://fixedmark.com/blog/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_

| 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](https://fixedmark.com/blog/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](https://fixedmark.com/blog/nextjs-route-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_

| 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](https://fixedmark.com/blog/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](https://www.cashfree.com/docs/api-reference/payouts/v2/webhooks/webhooks-v2) 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](https://fixedmark.com/blog/payment-webhook-source-ip-allowlisting) 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](https://fixedmark.com/regions) and [pricing](https://fixedmark.com/pricing).

1. 1

   **Whitelist both addresses** Add 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 URL** Set `FIXEDMARK_PROXY_URL` in your platform's environment, next to the Cashfree credentials.
3. 3

   **Proxy the payout client only** Give the Cashfree Payouts client its own dispatcher or HTTP client with the proxy. Leave other traffic direct.
4. 4

   **Check the egress IP** Run `curl --proxy "$FIXEDMARK_PROXY_URL" https://fixedmark.com/api/ip` a few times and confirm both addresses match the whitelist. The [egress IP guide](https://fixedmark.com/docs/verify-egress-ip) has more checks.

**cashfree.mjs**

```javascript
// 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](https://fixedmark.com/docs/logs) record the destination, SNI, bytes, egress IP, and result, which helps when Cashfree reports an IP error. On plans with [destination allowlists](https://fixedmark.com/docs/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](https://fixedmark.com/docs/node) and [Python](https://fixedmark.com/docs/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)](https://www.cashfree.com/docs/payouts/payouts/integrations/payouts-2fa)
- [Cashfree: Payouts IP whitelisting and public key FAQs](https://www.cashfree.com/docs/payouts/payouts/integrations/ip-whitelist-faq)
- [Cashfree: Getting started with Payouts APIs](https://www.cashfree.com/docs/api-reference/payouts/getting-started-with-payouts-apis)
- [Cashfree: Payouts v1 Authorize](https://www.cashfree.com/docs/api-reference/payouts/v1/authorize)
- [Cashfree: Payouts v2 overview](https://www.cashfree.com/docs/api-reference/payouts/v2/payouts-api-v2-new)
- [Cashfree: Secure ID IP whitelisting](https://www.cashfree.com/docs/secure-id/get-started/integration/ip-whitelisting-verification)
- [Cashfree: Secure ID getting started (2FA signature)](https://www.cashfree.com/docs/api-reference/vrs/getting-started)
- [Cashfree: Payouts v2 webhooks and IPs to whitelist](https://www.cashfree.com/docs/api-reference/payouts/v2/webhooks/webhooks-v2)
- [Vercel: How to allowlist deployment IP addresses](https://vercel.com/kb/guide/how-to-allowlist-deployment-ip-address)
- [AWS: Enable internet access for VPC-connected Lambda functions](https://docs.aws.amazon.com/lambda/latest/dg/configuration-vpc-internet.html)
- [Node.js: crypto.publicEncrypt](https://nodejs.org/api/crypto.html)

Keep reading

## Related guides

- [Use case Payment gateway APIs Whitelist one IP pair for RazorpayX and Cashfree payouts, or lock Stripe keys to it, then deploy anywhere.](https://fixedmark.com/use-cases/payment-gateway-apis)
- [Use case Bank and UPI APIs Whitelist one dedicated IP pair with your bank, UPI partner bank, or GSP, then deploy on Vercel or Railway without re-whitelisting.](https://fixedmark.com/use-cases/bank-and-upi-apis)
- [Integration Vercel Fixed egress IPs for Vercel Functions without the $100 per project add-on.](https://fixedmark.com/integrations/vercel)
- [Integration AWS Lambda A fixed IP for Lambda without VPC, subnets, and two NAT Gateways.](https://fixedmark.com/integrations/aws-lambda)
- [Guide Regions Static IP pairs in Mumbai, Singapore, and the US.](https://fixedmark.com/regions)

## 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.
