| Webhook event | Description |
|---|---|
| VENDOR_SETTLEMENT_INITIATED | Cashfree triggers this webhook when a vendor settlement starts. |
| VENDOR_SETTLEMENT_SUCCESS | Cashfree triggers this webhook when a vendor settlement succeeds. |
| VENDOR_SETTLEMENT_FAILED | Cashfree triggers this webhook when a vendor settlement fails. |
| VENDOR_SETTLEMENT_REVERSED | Cashfree triggers this webhook when a vendor settlement is reversed. |
Vendor settlement initiated
Cashfree Payments triggers the SETTLEMENT_INITIATED webhook when it initiates a settlement.{
"data": {
"settlement": {
"settlement_id": 49703,
"status": "CREATED",
"utr": "1686217237243457",
"payment_amount": null,
"settlement_initiated_on": "2023-06-08T15:10:35+05:30",
"settled_on": "null",
"reason": null,
"adjustment": 100.00,
"settlement_amount": 600.00,
"service_charge": 0.50,
"service_tax": 0.09,
"amount_settled": null,
"payment_from": "2023-06-08",
"payment_till": "2023-06-08",
"vendor_id": "esSettlementsAutomationVendor",
"vendor_transaction_amount": 500.00,
"account_mode": "BANK",
"settled_orders_count": 1
}
},
"event_time": "2023-06-08T15:10:37+05:30",
"type": "VENDOR_SETTLEMENT_CREATED"
}
Vendor settlement success
{
"data": {
"settlement": {
"settlement_id": 49703,
"status": "SUCCESS",
"utr": "1686217237243457",
"payment_amount": null,
"settlement_initiated_on": "2023-06-08T15:10:35+05:30",
"settled_on": "2023-06-08T15:10:37+05:30",
"reason": null,
"adjustment": 100.00,
"settlement_amount": 600.00,
"service_charge": 0.50,
"service_tax": 0.09,
"amount_settled": 600.00,
"payment_from": "2023-06-08",
"payment_till": "2023-06-08",
"vendor_id": "esSettlementsAutomationVendor",
"vendor_transaction_amount": 500.00,
"account_mode": "BANK",
"settled_orders_count": 1
}
},
"event_time": "2023-06-08T15:10:37+05:30",
"type": "VENDOR_SETTLEMENT_SUCCESS"
}
Vendor settlement failed
{
"data": {
"settlement": {
"settlement_id": 49703,
"status": "FAILED",
"utr": "1686217237243457",
"payment_amount": null,
"settlement_initiated_on": "2023-06-08T15:10:35+05:30",
"settled_on": "null",
"reason": null,
"adjustment": 100.00,
"settlement_amount": 600.00,
"service_charge": 0.50,
"service_tax": 0.09,
"amount_settled": null,
"payment_from": "2023-06-08",
"payment_till": "2023-06-08",
"vendor_id": "esSettlementsAutomationVendor",
"vendor_transaction_amount": 500.00,
"account_mode": "BANK",
"settled_orders_count": 1
}
},
"event_time": "2023-06-08T15:10:37+05:30",
"type": "VENDOR_SETTLEMENT_FAILED"
}
Vendor settlement reversed
{
"data": {
"settlement": {
"settlement_id": 49703,
"status": "REVERSED",
"utr": "1686217237243457",
"payment_amount": null,
"settlement_initiated_on": "2023-06-08T15:10:35+05:30",
"settled_on": "null",
"reason": Failed from bank end,
"adjustment": 100.00,
"settlement_amount": 600.00,
"service_charge": 0.50,
"service_tax": 0.09,
"amount_settled": null,
"payment_from": "2023-06-08",
"payment_till": "2023-06-08",
"vendor_id": "esSettlementsAutomationVendor",
"vendor_transaction_amount": 500.00,
"account_mode": "BANK",
"settled_orders_count": 1
}
},
"event_time": "2023-06-08T15:10:37+05:30",
"type": "VENDOR_SETTLEMENT_REVERSED"
}
Payload field description
| Field | Description | Example |
|---|---|---|
| adjustment | The sum of refunds, disputes, and chargeback part of this settlement is displayed here. | 0 |
| amount_settled | The total amount that is settled in this schedule option. | 50 |
| payment_amount | Total transaction amount considered for settlement. | 100 |
| payment_from | Start date from which the payments are considered for settlement. | 2022-03-15 |
| payment_till | End date till which the payments are considered for settlement. | 2022-03-23 |
| reason | Reason for failed and reversed settlements. For more information, see Reasons for failed and reversed settlements. | Transfer mode is not valid for beneficiary. |
| service_charge | Service charges are applicable for the payments that are included in this settlement. | 2 |
| service_tax | Service tax is applicable for the payments that are included in this settlement. | 0.50 |
| settled_on | Date and time at which the settlement was processed. | 2022-03-17T14:21:18+05:30 |
| settlement_amount | The sum of net settlement amount for the payments part of this settlement. | 13 |
| settlement_id | Cashfree settlement ID | 1155353 |
| settlement_initiated_on | The date on which settlement was initiated. | 2022-03-17T14:29:21+05:30 |
| status | Status of the settlement (either INITIATED, SUCCESS, FAILED, or REVERSED) | SUCCESS |
| utr | The unique transaction reference number is given by the bank for the settlement. | N076221079016329 |
| vendor_id | Reference ID as shared by you when onboarding the vendor. | IS_1hour_Upi |
| vendor_transaction_amount | Transaction amount split of vendor | 50 |
| event_time | Time at which settlement webhook was initiated. | 2022-03-17T14:29:23+05:30 |
| type | Type of webhook - VENDOR_SETTLEMENT_INITIATED, VENDOR_SETTLEMENT_SUCCESS, VENDOR_SETTLEMENT_FAILED, or VENDOR_SETTLEMENT_REVERSED. | VENDOR_SETTLEMENT_SUCCESS |
Reasons for failed and reversed settlements
| Reason | Category | Description |
|---|---|---|
| BANK_GATEWAY_ERROR | Bank | Technical error at the bank |
| BENE_BANK_DECLINED | Bank | Rejected by Beneficiary bank due to business reasons |
| FAILED | Bank | No explicit failure reason from the bank |
| INVALID_IFSC_FAIL | Customer | Invalid ifsc code provided for bank account |
| INVALID_ACCOUNT_FAIL | Customer | Bank account is invalid |
| RETURNED_FROM_BENEFICIARY | Bank | Immediate reversal from the beneficiary bank |
| INSUFFICIENT_BALANCE | Vendor | Your balance is exhausted, need to add funds |
| IMPS_MODE_FAIL | Bank | IMPS mode not supported for the beneficiary |
| RTGS_MODE_FAIL | Bank | RTGS mode not supported (only for RTGS) |
| REINITIALIZE_TRANSFER_LATER | Bank | Technical error at the bank, retry later |
| NRE_ACCOUNT_FAIL | Customer | Customer bank account is an NRE account |
| ACCOUNT_BLOCKED | Customer | Customer bank account is blocked |
| DEST_LIMIT_REACHED | Bank | Transfer limit to beneficiary exceeded |
| INVALID_MODE_FAIL | Bank | Transfer mode not valid for beneficiary |
| NPCI_UNAVAILABLE | Bank | NPCI is unavailable |
| BENEFICIARY_BANK_OFFLINE | Bank | Beneficiary bank is offline |
| INVALID_AMOUNT_FAIL | Vendor | Amount is invalid for the given transfer mode |
| SUSPECTED_TRANSFER | Customer | Suspicious transfer identified |
| BENE_NAME_DIFFERS | Customer | Beneficiary name not matching with bank records |
| DISABLED_MODE | Vendor | Transfer mode not enabled for the account |
| AMAZON_AMOUNT_EXCEED | Vendor | Amount should be less than 10000 for Amazon Pay mode |
| BENEFICIARY_BLACKLISTED | Vendor | Beneficiary is blacklisted |
| PAYOUT_INACTIVE | Vendor | Payout account is not active |
| INVALID_TRANSFER_AMOUNT | Vendor | Transfer amount is invalid |
| BENEFICIARY_NOT_EXIST | Vendor | Beneficiary does not exist |
| BENEFICIARY_INVALID_MODE | Vendor | Mode Not valid for Beneficiary |
| INVALID_BENE_ACCOUNT_OR_IFSC | Vendor | Invalid bank account number or ifsc provided |
| BENEFICIARY_NAME_DIFFERS | Customer | Beneficiary name not matching with bank records |
| ANY_OTHER_REASON | Bank | No reason provided for the failure/reversal |
| INVALID_OR_NO_SUCH_ACCOUNT_TYPE | Customer | Invalid account |
Signature verification
Use the signature to verify that the request has not been tampered with. To verify the signature, you need your Cashfree PG secret key and the payload. timestamp is present in the header x-webhook-timestampActual signature is present in the header x-webhook-signature
"headers": {
"host": "gamma.cashfree.com",
"x-request-id": "ad4dc1e65f8901302455b247237a667a",
"x-real-ip": "172.0.57.13",
"x-forwarded-for": "172.0.57.13",
"x-forwarded-host": "gamma.cashfree.com",
"x-forwarded-port": "80",
"x-forwarded-proto": "http",
"x-forwarded-scheme": "http",
"x-scheme": "http",
"x-original-forwarded-for": "52.66.25.127",
"content-length": "592",
"accept": "_/_",
"content-type": "application/json",
"user-agent": "ReactorNetty/1.0.30",
"x-datadog-parent-id": "4281924148563621550",
"x-datadog-sampling-priority": "1",
"x-datadog-trace-id": "228569355002181270",
"x-webhook-signature": "Xm0YzEJCRsh0XvIEK12D4FqpmC60cReKoqPBn424kV0=",
"x-webhook-timestamp": "1686217237543",
"x-webhook-version": "2022-09-01"
}