paymentservice/document/cashfree

Cashfree Knowledge Base

Complete end-to-end documentation for integrating and managing Cashfree across the Tradhox Payments Microservice (paymentservice).

---

Documentation Index

Module	Document	Description
01	Overview & Quickstart	Platform overview, environment endpoints (Sandbox & Production), architecture sequence diagram, and first API call.
02	Authentication, Headers & Security	API key credentials (x-client-id, x-client-secret), versioning (2023-08-01), idempotency, rate limiting, and security compliance.
03	Orders API Specification	Create Order (POST /orders), order lifecycle (ACTIVE, PAID, EXPIRED, TERMINATED), Get Order status, and payments lookup.
04	Checkout Integrations & Payment Methods	Hosted Checkout (redirect), Drop-in JS SDK v3, and Seamless API for UPI (Intent, Collect, QR), Cards (Token Vault), Netbanking, and Wallets.
05	Webhooks & Signature Verification	Event schemas, HMAC-SHA256 signature verification algorithm, anti-replay timestamp validation, and production Django webhook view.
06	Refunds & Disputes API	Full/Partial refunds (POST /orders/{order_id}/refunds), Standard vs Instant refunds, ARN tracking, and chargeback dispute workflows.
07	Settlements & Reconciliation	T+1/T+2 banking settlement cycles, MDR fee & tax calculations, Order-level settlement API, UTR tracking, and settlement webhooks.
08	Payouts & Automated Disbursements	24x7 automated disbursements via UPI, IMPS, NEFT, RTGS, Beneficiary onboarding, transfer status tracking, and balance inquiries.
09	Secure ID & KYC Verification	Bank Account Penny Drop verification, UPI VPA verification, PAN validation, and GSTIN lookup for merchant & vendor compliance.
10	Error Codes & Sandbox Test Data	Standard error formats, common error codes dictionary, test Visa/Mastercard/RuPay card numbers, test UPI handles, and simulated netbanking.
11	Django Integration Blueprint	Production Python CashfreeClient, Django models (PaymentOrder, PaymentTransaction, PaymentRefund), settings configuration, and API views.

---

Quick Reference Summary

Base URLs

• Sandbox: https://sandbox.cashfree.com/pg
• Production: https://api.cashfree.com/pg

Standard Request Headers

Content-Type: application/json
x-api-version: 2023-08-01
x-client-id: <CASHFREE_APP_ID>
x-client-secret: <CASHFREE_SECRET_KEY>
x-idempotency-key: <UUIDv4>

Webhook Verification Formula

payload = x-webhook-timestamp + raw_body
computed_hmac = HMAC_SHA256(secret_key, payload)
computed_signature = Base64Encode(computed_hmac)
valid = (computed_signature == x-webhook-signature)