Cashfree payment getaways integration

Executive Summary

You will use one Cashfree merchant account to handle all customer payments and vendor (hotel‑owner) payouts via Easy Split. Vendors are onboarded in‑app through your UI using Cashfree’s Partner Onboarding APIs—no separate Cashfree dashboard login required. Customer orders are created server‑side with split instructions, processed via a secure hosted checkout, and automatically disbursed (T+2) to vendors. Cashfree charges a flat Annual Maintenance Contract (AMC) of ₹4,999/yr and a Transaction Discount Rate (TDR) of 1.95–2.0% on each successful capture (no extra split or refund fees) Cashfree Cashfree Cashfree. Refunds (standard or Instant) are processed via a single API call; Cashfree handles split reversals internally and does not apply a second TDR on refunds Cashfree Cashfree.

---

1. Merchant Account Setup

1.1 Sign‑Up & KYC

1. Register at Cashfree’s merchant portal. Cashfree

2. Verify Email & Login to the Dashboard.

3. Under Profile, fill in business details (legal name, PAN/GSTIN), bank details (account number & IFSC), and upload KYC documents (Incorporation certificate, identity & address proofs). Cashfree

4. Approval typically takes 1–2 business days.

1.2 API Credentials

• Sandbox Keys: Available immediately for testing.

• Production Keys: Generated post‑KYC approval; store Client ID & Client Secret securely in environment variables. Cashfree

1.3 Go‑Live Configuration

• Whitelist your domains or app package names under Settings → Whitelist.

• Configure Webhooks (e.g., /webhook/cashfree) to receive PAYMENT_SUCCESS, PAYMENT_FAILED, and REFUND_PROCESSED events. Cashfree

---

2. Vendor Onboarding (Partner APIs)

You collect vendor details/documents in your own UI and push them via API—vendors never log into Cashfree directly.

2.1 Create Sub‑Merchant

• Endpoint: POST https://api.cashfree.com/partners/v3/merchants

• Payload: { businessName, businessType, pan, gstin, bankAccount, ifsc, email, phone } Cashfree

2.2 Upload KYC Documents

• Endpoint: POST https://api.cashfree.com/partners/v3/merchants/{merchant_id}/documents

• Payload: Base64‑encoded ID & address proofs. Cashfree

2.3 Check Verification Status

• Endpoint: GET https://api.cashfree.com/partners/v3/merchants/{merchant_id}/status

• Response: VERIFIED or pending; store partner_id for payouts. Cashfree

---

3. Order Creation & Split Payout Flow

3.1 Compute Fees & Splits

• Order Amount: ₹X.

• Platform Fee (your share): e.g., 5% of ₹X (implicit, by not allocating full amount in splits).

• Vendor Splits: Distribute the remainder among vendors.

3.2 Create Order

httpCopyEditPOST https://api.cashfree.com/pg/v1/orders  
Headers: x-client-id, x-client-secret  
Body: {
  order_id, order_amount, customer_details,
  order_meta: { cashfree_splits: [ { partner_id, amount }, … ] }
}

• Returns payment_session_id. Cashfree

3.3 Host Checkout & Webhook

• Client‑side: Mount Cashfree.js with sessionId.

• Server‑side Webhook: Verify X-Cashfree-Signature; handle PAYMENT_SUCCESS or PAYMENT_FAILED. Cashfree

3.4 Automatic Disbursement

• On success, Cashfree deducts 2% TDR and splits the net to vendors and your platform on T + 2 business days. Cashfree

---

4. Fees & Pricing

No per‑vendor, split, or refund fees—all encompassed by the TDR & AMC.

---

5. Refund & Cancellation Handling

5.1 Failed Payments

• Event: PAYMENT_FAILED webhook.

• Action: Mark order failed; no refund call required (no capture occurred).

5.2 Post‑Payment Cancellations

1. Initiate Refund:

    httpCopyEditPOST https://api.cashfree.com/pg/v1/orders/{order_id}/refunds  
    { refund_amount, refund_reason }
   

   Returns refund_id. Cashfree

2. Webhook: Receive REFUND_PROCESSED; update order & notify customer. Cashfree

3. Split‑Aware Reversal:

   • Before T+2: Vendor payouts are simply not sent.

   • After T+2: Cashfree debits vendor balances (and your platform share) automatically, then issues the full refund. Cashfree

No extra 2% TDR on refunds—the original TDR is never re‑charged.

---

6. Security & Best Practices

• Secure Keys: Store Client ID/Client Secret in env variables; never expose in front end.

• Webhook Verification: Always verify X-Cashfree-Signature. Cashfree

• TLS Everywhere: Enforce HTTPS on all endpoints.

• PCI Compliance: Use Cashfree’s hosted checkout to keep card data off your servers.

• Idempotency & Validation: Enforce unique order IDs and validate all amounts/partner IDs.

---

This document equips your client with a clear, end‑to‑end picture of integrating Cashfree for multi‑vendor payments—covering setup, flows, pricing, and edge‑case refunds. Let me know if you need code samples or slide decks!