Cashfree Payment Gateway Python SDK

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

• pip install cashfree_pg Python (correct PG SDK — use this)

Imports

• Cashfree PG client + order creation

  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

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)