paymentservice/document/cashfree/08_payouts_and_transfers.md

Cashfree Payouts & Automated Disbursements

1. Overview

Cashfree Payouts allows automated disbursements to vendor bank accounts, delivery partners, refunds, affiliate payouts, and seller settlements 24x7x365 across India.

Supported Rails

• UPI: Instant, up to ₹1,00,000 per transaction (or ₹5,00,000 for select categories).
• IMPS: Instant, available 24x7, up to ₹5,00,000 per transaction.
• NEFT: Batch settlements throughout the day, no upper limit.
• RTGS: Real-time gross settlement for high-value transactions (minimum ₹2,00,000).
• Card Payouts: Direct credits to Visa/Mastercard debit cards.

---

2. Environments & Base URLs

Environment	Base URL
Sandbox (Gamma)	https://payout-gamma.cashfree.com/payout/v1
Production	https://payout-api.cashfree.com/payout/v1

Authentication

Payouts API supports passing credentials in headers or exchanging them for a short-lived bearer token:

X-Client-Id: <PAYOUT_CLIENT_ID>
X-Client-Secret: <PAYOUT_CLIENT_SECRET>

Or via Auth Token:

POST /payout/v1/authorize
Authorization: Bearer <TOKEN>

---

3. Beneficiary Management

Before transferring funds, register the beneficiary (or use quick-transfer APIs).

Add Beneficiary

POST /payout/v1/addBeneficiary

Request Payload

{
  "beneId": "vendor_vignesh_01",
  "name": "Vignesh Tech",
  "email": "vignesh@tradhox.com",
  "phone": "9876543210",
  "bankAccount": "50100234567890",
  "ifsc": "HDFC0001234",
  "address1": "Tradhox HQ, Tech Park",
  "city": "Bengaluru",
  "state": "Karnataka",
  "pincode": "560001"
}

For UPI Disbursements, replace bankAccount and ifsc with vpa:

{
  "beneId": "seller_upi_42",
  "name": "Seller Partner",
  "email": "partner@tradhox.com",
  "phone": "9876543210",
  "vpa": "partner@okaxis",
  "address1": "Seller Hub",
  "city": "Mumbai",
  "state": "Maharashtra",
  "pincode": "400001"
}

---

4. Request a Transfer (Disbursement)

Initiates a payout from your Cashfree account balance to the beneficiary.

Endpoint

POST /payout/v1/requestTransfer

Request Payload

{
  "transferId": "tradhox_payout_88291",
  "beneId": "vendor_vignesh_01",
  "amount": "25000.00",
  "transferMode": "IMPS",
  "remarks": "Vendor weekly payout settlement"
}

Transfer Modes (transferMode):

• IMPS: Instant bank transfer.
• NEFT: Standard bank clearing.
• RTGS: High value bank transfer (>= ₹2,00,000).
• UPI: Instant transfer to UPI VPA.

Response (200 OK)

{
  "status": "SUCCESS",
  "subCode": "200",
  "message": "Transfer initiated successfully",
  "data": {
    "referenceId": "1948571029",
    "transferId": "tradhox_payout_88291",
    "utr": "629184910284",
    "acknowledged": 1
  }
}

---

5. Get Transfer Status

Endpoint

GET /payout/v1/getTransferStatus?transferId=tradhox_payout_88291

Response (200 OK)

{
  "status": "SUCCESS",
  "subCode": "200",
  "message": "Transfer details fetched successfully",
  "data": {
    "transfer": {
      "transferId": "tradhox_payout_88291",
      "referenceId": "1948571029",
      "status": "SUCCESS",
      "statusDescription": "Transfer completed successfully",
      "amount": "25000.00",
      "utr": "629184910284",
      "addedOn": "2026-10-18 21:20:00",
      "processedOn": "2026-10-18 21:20:03"
    }
  }
}

Payout Statuses

• SUCCESS: Transfer completed; beneficiary account credited.
• PENDING: In progress with clearing network (e.g. NEFT window or slow bank response).
• FAILED: Transfer rejected by beneficiary bank (invalid account, IFSC, or limit reached).
• REVERSED: Transaction initially cleared but subsequently reversed by receiving bank.

---

6. Check Account Balance

Verify available wallet balance before triggering payouts.

Endpoint

GET /payout/v1/getBalance

Response (200 OK)

{
  "status": "SUCCESS",
  "subCode": "200",
  "message": "Balance fetched successfully",
  "data": {
    "balance": "485290.50",
    "availableBalance": "485290.50"
  }
}