Cashfree Payment Gateway Python SDK

5.0.6 verified Tue May 12 auth: no python install: verified quickstart: verified

Official Cashfree Payment Gateway Python SDK. Current version: 5.0.6 (Mar 2026). THREE packages on PyPI causing confusion: 'cashfree-sdk' (0.1.3 — beta, NOT recommended for production by Cashfree), 'cashfree_pg' (5.0.6 — correct current PG SDK), 'cashfree' (1.0.1 — unrelated package). Use cashfree_pg. API version string must be passed to every API call. Supports SANDBOX and PRODUCTION environments. Amount in rupees (float) — unlike Razorpay which uses paise.

pip install cashfree_pg

Common errors

error ModuleNotFoundError: No module named 'cashfree_pg' ↓

cause The `cashfree_pg` library is not installed in the current Python environment, or an attempt is made to import it while an older/incorrect package (like `cashfree-sdk` or `cashfree`) was installed.

fix

Ensure the correct package is installed using pip install cashfree_pg.

error from cashfree_sdk import Cashfree ↓

cause The developer is attempting to import from a deprecated or incorrect Cashfree SDK package (`cashfree-sdk` or `cashfree`) instead of the official `cashfree_pg` library.

fix

After ensuring cashfree_pg is installed, use from cashfree_pg.api_client import Cashfree.

error authentication_error, Invalid or missing authentication credentials ↓

cause The provided API keys (X-Client-Id, X-Client-Secret) are incorrect, expired, or do not match the environment (SANDBOX/PRODUCTION) being used.

fix

Verify your X-Client-Id and X-Client-Secret from your Cashfree Merchant Dashboard and ensure XEnvironment (e.g., Cashfree.SANDBOX or Cashfree.PRODUCTION) is set correctly during SDK initialization.

error "message":"version value should be 2021-05-21 or 2022-01-01 or 2022-09-01 or 2023-08-01","code":"request_failed","type":"invalid_request_error" ↓

cause The `x_api_version` string passed to the API call is not one of the currently supported versions.

fix

Update the x_api_version parameter in your API calls to a currently supported version, such as "2023-08-01" or the latest version specified in the Cashfree documentation.

error SignatureMismatch error ↓

cause This error typically occurs when the signature generated on your backend (using your secret key and order details) does not match the signature Cashfree calculates, often due to incorrect credentials or a mismatch in transaction parameters like `orderId` or `orderAmount`.

fix

Double-check that your X-Client-Id and X-Client-Secret used for signature generation are correct and that all order details (e.g., order_id, order_amount, order_currency) passed to the API exactly match those used to create any associated tokens or signatures.

Warnings

breaking Three packages on PyPI: cashfree-sdk (beta/not for production), cashfree_pg (correct SDK), cashfree (unrelated). LLMs and old tutorials reference cashfree-sdk which Cashfree explicitly says is not for production. ↓

fix pip install cashfree_pg — this is the official current SDK.

breaking x_api_version string must be passed to every API call. Omitting it raises TypeError. Unlike Razorpay which doesn't require API version per call. ↓

fix x_api_version = '2023-08-01'; cashfree.PGCreateOrder(x_api_version, request, None, None)

gotcha Amount is in RUPEES (float) — not paise. Unlike Razorpay which uses paise. 500 means ₹500. This is the opposite of Razorpay's convention. ↓

fix order_amount=500.00 means ₹500. No multiplication needed.

gotcha SANDBOX environment uses TEST keys from Cashfree dashboard. Test client IDs start with 'TEST_'. Production keys are different — switch XEnvironment=Cashfree.PRODUCTION with live keys. ↓

fix Use Cashfree.SANDBOX for testing, Cashfree.PRODUCTION for live. Keys are different for each environment.

gotcha return_url in OrderMeta must include {order_id} placeholder — Cashfree replaces it with actual order ID. Missing placeholder means you can't identify which order was paid. ↓

fix return_url='https://yourapp.com/callback?order_id={order_id}'

gotcha IP whitelisting required for production. Cashfree blocks API calls from non-whitelisted IPs in production. Add your server IP in Cashfree dashboard under Security settings. ↓

fix Whitelist server IP in Cashfree dashboard → Settings → IP Whitelist.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 2.82s 35.0M

3.10 slim (glibc) - - 1.96s 35M

3.11 alpine (musl) - - 3.58s 39.6M

3.11 slim (glibc) - - 3.00s 39M

3.12 alpine (musl) - - 2.98s 30.9M

3.12 slim (glibc) - - 2.92s 31M

3.13 alpine (musl) - - 2.48s 30.6M

3.13 slim (glibc) - - 2.50s 30M

3.9 alpine (musl) - - 2.57s 34.5M

3.9 slim (glibc) - - 2.33s 34M

Imports

Cashfree PG client + order creation

wrong

# Wrong package — not recommended for production
from cashfree_sdk.pg import PG

# Wrong package — unrelated
import cashfree

correct

from cashfree_pg.models.create_order_request import CreateOrderRequest
from cashfree_pg.api_client import Cashfree
from cashfree_pg.models.customer_details import CustomerDetails
from cashfree_pg.models.order_meta import OrderMeta

cashfree = Cashfree(
    XEnvironment=Cashfree.SANDBOX,  # or Cashfree.PRODUCTION
    XClientId='<x-client-id>',
    XClientSecret='<x-client-secret>'
)

x_api_version = '2023-08-01'  # required for every call

customer = CustomerDetails(
    customer_id='cust_001',
    customer_phone='9999999999'
)
order_meta = OrderMeta(
    return_url='https://yourapp.com/payment/callback?order_id={order_id}'
)
create_request = CreateOrderRequest(
    order_amount=500.00,  # in rupees (not paise)
    order_currency='INR',
    customer_details=customer,
    order_meta=order_meta
)

response = cashfree.PGCreateOrder(x_api_version, create_request, None, None)
print(response.data.order_id)

Use 'cashfree_pg' not 'cashfree-sdk' or 'cashfree'. cashfree-sdk explicitly states it is NOT recommended for production. Amount is in rupees (float), not paise.

Quickstart verified last tested: 2026-04-23

Cashfree PG Python SDK — create and fetch order.

# pip install cashfree_pg
from cashfree_pg.api_client import Cashfree
from cashfree_pg.models.create_order_request import CreateOrderRequest
from cashfree_pg.models.customer_details import CustomerDetails
from cashfree_pg.models.order_meta import OrderMeta

# Initialize — get keys from dashboard.cashfree.com
cashfree = Cashfree(
    XEnvironment=Cashfree.SANDBOX,
    XClientId='TEST_APP_ID',
    XClientSecret='TEST_SECRET_KEY'
)

x_api_version = '2023-08-01'  # pass to every API call

# Create order
customer = CustomerDetails(customer_id='cust_001', customer_phone='9999999999')
meta = OrderMeta(return_url='https://yourapp.com/callback?order_id={order_id}')

request = CreateOrderRequest(
    order_amount=499.00,   # rupees, not paise
    order_currency='INR',
    customer_details=customer,
    order_meta=meta
)

try:
    response = cashfree.PGCreateOrder(x_api_version, request, None, None)
    print('Order ID:', response.data.order_id)
    print('Payment URL:', response.data.payment_link)
except Exception as e:
    print('Error:', e)

# Fetch order status
try:
    order = cashfree.PGFetchOrder(x_api_version, response.data.order_id, None)
    print('Status:', order.data.order_status)
except Exception as e:
    print('Error:', e)