Settlement Webhooks

Learn more about webhooks triggered when a payout to merchant or vendor account happens

We broadly send two types of notifications when a payout happens.

1. Payout to Merchant account
2. Payout to Vendor account (if you are using Easy Split)

Settlement Webhook

This webhook is triggered whenever there is a payout to your merchant account. The settlement webhooks will notify you about instant settlements in addition to the standard settlement webhooks. We send webhooks for four different events for a settlement.

Webhook Event	Description
SETTLEMENT_INITIATED	This webhook will be triggered when a settlement is initiated.
SETTLEMENT_SUCCESS	This webhook will be triggered when a settlement is successful.
SETTLEMENT_FAILED	This webhook will be triggered when a settlement has failed.
SETTLEMENT_REVERSED	This webhook will be triggered when a settlement has been reversed.

The following webhook is sent for other types of settlements as well: instant settlement or an on-demand settlement.

Version 2025-01-01

2025-01-01

{
    "data": {
        "settlement": {
            "adjustment": 0,
            "amount_settled": 97.94,
            "payment_amount": 100,
            "payment_from": "2025-02-14 12:00:00",
            "payment_till": "2025-02-14 12:15:00",
            "reason": null,
            "service_charge": 1.75,
            "service_tax": 0.31,
            "settled_on": "2025-02-14T12:35:19+05:30",
            "settlement_type": "STANDARD",   //settlement type //
            "settlement_amount": 97.94,
            "settlement_id": 738,
            "settlement_initiated_on": "2025-02-14T12:35:17+05:30",
            "status": "SUCCESS",
            "utr": 1644822317781212,
            "settlement_charge": 0,    // applicable for instant settlement //
            "settlement_tax": 0,       // applicable for instant settlement //
            "remarks": null,           // applicable for instant settlement //
            "forex_conversion_handling_charge":null,
            "forex_conversion_handling_tax":null,
            "forex_conversion_rate":null,
            "charges_currency":null
        }
    },
    "event_time": "2022-02-08T13:37:34+05:30",
    "type": "SETTLEMENT_SUCCESS"
}

Understand these fields in detail

Payload Field Description

Field	Description	Example
adjustment	Sum of refunds, disputes, and chargebacks included in this settlement.	0
amount_settled	Total amount settled in this schedule.	15
payment_amount	Total transaction amount considered for settlement.	15
payment_from	Start date and time from which payments are considered for settlement.	2022-02-14 12:00:00
payment_till	End date and time till which payments are considered for settlement.	2022-02-23 12:00:00
reason	Reason for failed or reversed settlements.	Transfer mode not valid for beneficiary.
service_charge	Service charges applicable to the payments included in this settlement.	2
service_tax	Service tax applicable to the payments included in this settlement.	0
settled_on	Date and time when the settlement was processed.	2022-03-17T14:21:18+05:30
settlement_type	Type of settlement (e.g., INSTANT).	INSTANT
settlement_amount	Net settlement amount for the payments included in this settlement.	13
settlement_id	Unique settlement ID generated by Cashfree.	1155353
settlement_initiated_on	Date on which settlement was initiated.	2022-03-17T14:29:21+05:30
status	Status of the settlement (INITIATED, SUCCESS, FAILED, or REVERSED).	SUCCESS
utr	Unique transaction reference number provided by the bank for the settlement.	N076221079016329
settlement_charge	Additional charge applicable for instant settlement.	10.10
settlement_tax	Settlement tax applicable for instant settlement.	01.97
remarks	Any remarks specified by the merchant.	Settlement Initiated
event_time	Time when the settlement webhook was triggered.	2022-03-17T14:29:23+05:30
type	Type of webhook event (SETTLEMENT_INITIATED, SETTLEMENT_SUCCESS, SETTLEMENT_FAILED, or SETTLEMENT_REVERSED).	SETTLEMENT_SUCCESS

Vendor Settlement Webhook

This section only applies to merchants using our Easy Split product

These settlement webhooks automate notifications when vendor settlements are initiated, successfully processed, failed, or reversed.

Webhook Event	Description
VENDOR_SETTLEMENT_INITIATED	This webhook will be triggered when a vendor settlement is initiated.
VENDOR_SETTLEMENT_SUCCESS	This webhook will be triggered when a vendor settlement is successful.
VENDOR_SETTLEMENT_FAILED	This webhook will be triggered when a vendor settlement has failed.
VENDOR_SETTLEMENT_REVERSED	This webhook will be triggered when a vendor settlement has been reversed.

Vendor Settlement Webhook

{
    "data": {
        "settlement": {
            "adjustment": 0,
            "amount_settled": 10,
            "payment_amount": null,
            "payment_from": "2022-05-26",
            "payment_till": "2022-05-26",
            "reason": null,
            "service_charge": 0.05,
            "service_tax": 0.01,
            "settled_on": "2022-05-26T15: 06: 14+05: 30",
            "settled_orders_count": 2,
            "settlement_amount": 10,
            "settlement_id": 6151,
            "settlement_initiated_on": "2022-05-26T15: 06: 09+05: 30",
            "settlement_type": null,
            "status": "CREATED",
            "utr": null,
            "vendor_id": "Vendor_123adj4dr4osn23fn",
            "vendor_transaction_amount": 10,
            "account_mode": "BANK",
            "account_number": "XXXXXXX1234",
            "ifsc": "HDFC0000001",
            "vpa": null
        },
        "event_time": "2022-05-26T15:06:15+05:30",
        "type": "VENDOR_SETTLEMENT_INITIATED"
    }
}

Transaction Wise Settlement Webhook

This section only applies to merchants using our Transaction Wise Settlement model

These TWS(Transaction Wise Settlement) webhooks are triggered when settlement are initiated, successfully processed, failed, or reversed.

Webhook Event	Description
TRANSACTION_WISE_SETTLEMENT_INITIATED	This webhook will be triggered when a TWS is initiated.
TRANSACTION_WISE_SETTLEMENT_SUCCESS	This webhook will be triggered when a TWS is successful.
TRANSACTION_WISE_SETTLEMENT_FAILED	This webhook will be triggered when a TWS has failed.
TRANSACTION_WISE_SETTLEMENT_REVERSED	This webhook will be triggered when a TWS has been reversed.

Transaction Wise Settlement Webhook

{
    "data":{
         "order":{
            "order_id":"order_OFR_2",
            "order_amount":2,
            "order_currency":"INR",
            "order_tags":null
         },
         "payment":{
            "cf_payment_id":"1453002795",
            "payment_status":"SUCCESS",
            "payment_amount":1,
            "payment_currency":"INR",
            "payment_message":"00::Transaction success",
            "payment_time":"2022-12-15T12:20:29+05:30",
            "bank_reference":"234928698581",
            "auth_id":null,
            "payment_method":{
               "upi":{
                  "channel":"collect",
                  "upi_id":"suhasg6@ybl",
                  "upi_instrument":"UPI_CREDIT_CARD",
                  "upi_instrument_number":"masked card number",
                  "upi_payer_ifsc":"SBI0025434",
                  "upi_payer_account_number":"XXXXX0231"
               }
            },
            "payment_group":"upi"
         },
         "customer_details":{
            "customer_name":null,
            "customer_id":"7112AAA812234",
            "customer_email":"[e-mail]",
            "customer_phone":"9908734801"
         },
         "payment_gateway_details":null,
         "payment_offers":null,
         "settlement": {
             "settlement_id": "1639789947",
             "status": "SUCCESS",
             "utr": "1212743972438575",
             "payment_amount": 500.00,
             "settlement_initiated_on": "2025-03-15T22:21:29+05:30",
             "settled_on": "2025-03-15T22:22:30+05:30",
             "reason": "Transfer completed successfully",
             "adjustment": 0.00,
             "settlement_amount": 441.00,
             "service_charge": 50.00,
             "service_tax": 9.00,
             "amount_settled": 441.00,
             "payment_from": "2025-03-15T22:21:29+05:30",
             "payment_till": "2025-03-15T22:21:29+05:30",
             "settlement_type": "NORMAL_SETTLEMENT",
             "remarks": null,
             "settlement_charge": 0.00,
             "settlement_tax": 0.00
         }
       },
         "event_time": "2025-04-10T22:22:06+05:30",
         "type": "TRANSACTION_WISE_SETTLEMENT_SUCCESS"
       }
}