Settlement Webhooks

Configure settlement webhooks to receive automated notifications when settlements are initiated, successfully processed, failed, or reversed.

The webhook notifications are sent on all the URLs added and enabled in the settlement webhook. Merchants can add new URLs and enable or disable existing URLs for settlement webhook at any time and it will reflect instantaneously.

Click here to know how to configure webhooks.

Settlement Webhook Version 1

A new version (x-webhook-version: 2022-09-01) of the settlement webhooks is available from 17/11/2022. The new version of the settlement webhooks will notify you about instant settlements in addition to the standard settlement webhooks as part of our new version. Now you will get separate webhooks for Instant Settlements and Standard Settlements.

The list of changes in the new version are:

  • The payment_from and payment_till parameters will notify you about the time considered for the settlement period in addition to the date.
  • The settlement_type parameter will notify you if the settlement type is a standard or instant settlement.
  • New parameters settlement_charge, settlement_tax, and remarks will notify you about the instant settlement charges.

📘

If you are using the older version of the webhook (x-webhook-version: 2021-09-21) we recommend you make the necessary changes and switch to the newer version to start receiving updates about Instant Settlements. We will discontinue support for the older version in a few days.

The table below lists the webhook events available for settlements Version 0 and Version 1.

Webhook EventDescription
SETTLEMENT_INITIATEDThis webhook will be triggered when a settlement is initiated.
SETTLEMENT_SUCCESSThis webhook will be triggered when a settlement is successful.
SETTLEMENT_FAILEDThis webhook will be triggered when a settlement has failed.
SETTLEMENT_REVERSEDThis webhook will be triggered when a settlement has been reversed.

Settlement Initiated

SETTLEMENT_INITIATED webhook is triggered when a settlement has been initiated by Cashfree Payments.


Settlement Success

//Standard Settlement

{
    "data": {
        "settlement": {
            "adjustment": 0,
            "amount_settled": 97.94,
            "payment_amount": 100,
            "payment_from": "2022-02-14 12:00:00",
            "payment_till": "2022-02-14 12:15:00",
            "reason": null,
            "service_charge": 1.75,
            "service_tax": 0.31,
            "settled_on": "2022-02-14T12:35:19+05:30",
            "settlement_type": "STANDARD",   //settlement type //
            "settlement_amount": 97.94,
            "settlement_id": 738,
            "settlement_initiated_on": "2022-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 //
        }
    },
    "event_time": "2022-02-08T13:37:34+05:30",
    "type": "SETTLEMENT_SUCCESS"
}
//Instant Settlement

{
    "data": {
        "settlement": {
            "adjustment": 0,
            "amount_settled": 97.94,
            "payment_amount": 100,
            "payment_from": "2022-02-14 12:00:00",
            "payment_till": "2022-02-14 12:15:00",
            "reason": null,
            "service_charge": 1.75,
            "service_tax": 0.31,
            "settled_on": "2022-02-14T12:35:19+05:30",
            "settlement_type": "INSTANT",   //settlement type //
            "settlement_amount": 97.94,
            "settlement_id": 738,
            "settlement_initiated_on": "2022-02-14T12:35:17+05:30",
            "status": "SUCCESS",
            "utr": 1644822317781212,
            "settlement_charge": 0.19,    // settlement charge //
            "settlement_tax": 0.003,      // settlement tax //
            "remarks": "Settled"         // remarks //
        }
    },
    "event_time": "2022-02-08T13:37:34+05:30",
    "type": "SETTLEMENT_SUCCESS"
}
//On-demand Settlement

{
    "data": {
        "settlement": {
            "adjustment": 0,
            "amount_settled": 97.94,
            "payment_amount": 100,
            "payment_from": "2022-02-14 12:00:00",
            "payment_till": "2022-02-14 12:15:00",
            "reason": null,
            "service_charge": 1.75,
            "service_tax": 0.31,
            "settled_on": "2022-02-14T12:35:19+05:30",
            "settlement_type": "OD_SETTLEMENT",   //settlement type //
            "settlement_amount": 97.94,
            "settlement_id": 738,
            "settlement_initiated_on": "2022-02-14T12:35:17+05:30",
            "status": "SUCCESS",
            "utr": 1644822317781212,
            "settlement_charge": 0.19,    // settlement charge //
            "settlement_tax": 0.003,      // settlement tax //
            "remarks": "Settled"         // remarks //
        }
    },
    "event_time": "2022-02-08T13:37:34+05:30",
    "type": "SETTLEMENT_SUCCESS"
}

Settlement Failed

//Standard Settlement

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

{
    "data": {
        "settlement": {
            "adjustment": 0,
            "amount_settled": 97.94,
            "payment_amount": 100,
            "payment_from": "2022-02-14 12:00:00",
            "payment_till": "2022-02-14 12:15:00",
            "reason": null,
            "service_charge": 1.75,
            "service_tax": 0.31,
            "settled_on": "2022-02-14T12:35:19+05:30",
            "settlement_type": "INSTANT",   //settlement type //
            "settlement_amount": 97.94,
            "settlement_id": 738,
            "settlement_initiated_on": "2022-02-14T12:35:17+05:30",
            "status": "FAILED",
            "utr": 1644822317781212,
            "settlement_charge": 0.19,                // settlement charge //
            "settlement_tax": 0.003,                   // settlement tax //
            "remarks": "Settlement Failed"         // remarks //
        }
    },
    "event_time": "2022-02-08T13:37:34+05:30",
    "type": "SETTLEMENT_FAILED"
}
//On-demand Settlement

{
    "data": {
        "settlement": {
            "adjustment": 0,
            "amount_settled": 97.94,
            "payment_amount": 100,
            "payment_from": "2022-02-14 12:00:00",
            "payment_till": "2022-02-14 12:15:00",
            "reason": null,
            "service_charge": 1.75,
            "service_tax": 0.31,
            "settled_on": "2022-02-14T12:35:19+05:30",
            "settlement_type": "OD_SETTLEMENT",   //settlement type //
            "settlement_amount": 97.94,
            "settlement_id": 738,
            "settlement_initiated_on": "2022-02-14T12:35:17+05:30",
            "status": "FAILED",
            "utr": 1644822317781212,
            "settlement_charge": 0.19,                // settlement charge //
            "settlement_tax": 0.003,                   // settlement tax //
            "remarks": "Settlement Failed"         // remarks //
        }
    },
    "event_time": "2022-02-08T13:37:34+05:30",
    "type": "SETTLEMENT_FAILED"
}

Settlement Reversed

//Standard Settlement

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

{
    "data": {
        "settlement": {
            "adjustment": 0,
            "amount_settled": 97.94,
            "payment_amount": 100,
            "payment_from": "2022-02-14 12:00:00",
            "payment_till": "2022-02-14 12:15:00",
            "reason": null,
            "service_charge": 1.75,
            "service_tax": 0.31,
            "settled_on": "2022-02-14T12:35:19+05:30",
            "settlement_type": "INSTANT",   //settlement type //
            "settlement_amount": 97.94,
            "settlement_id": 738,
            "settlement_initiated_on": "2022-02-14T12:35:17+05:30",
            "status": "REVERSED",
            "utr": 1644822317781212,
            "settlement_charge": 0.19,    // settlement charge //
            "settlement_tax": 0.003,      // settlement tax //
            "remarks": "Settlement Reversed"        // remarks //
        }
    },
    "event_time": "2022-02-08T13:37:34+05:30",
    "type": "SETTLEMENT_REVERSED"
}
//On-demand Settlement

{
    "data": {
        "settlement": {
            "adjustment": 0,
            "amount_settled": 97.94,
            "payment_amount": 100,
            "payment_from": "2022-02-14 12:00:00",
            "payment_till": "2022-02-14 12:15:00",
            "reason": null,
            "service_charge": 1.75,
            "service_tax": 0.31,
            "settled_on": "2022-02-14T12:35:19+05:30",
            "settlement_type": "OD_SETTLEMENT",   //settlement type //
            "settlement_amount": 97.94,
            "settlement_id": 738,
            "settlement_initiated_on": "2022-02-14T12:35:17+05:30",
            "status": "REVERSED",
            "utr": 1644822317781212,
            "settlement_charge": 0.19,    // settlement charge //
            "settlement_tax": 0.003,      // settlement tax //
            "remarks": "Settlement Reversed"        // remarks //
        }
    },
    "event_time": "2022-02-08T13:37:34+05:30",
    "type": "SETTLEMENT_REVERSED"
}

Settlement Webhook Version 0

The settlement webhook version 0 (x-webhook-version: 2021-09-21) notifies you about the standard settlements you have received. To receive notifications about Instant Settlements you must start using the version 1 of our settelement webhook.

Settlement Initiated

SETTLEMENT_INITIATED webhook is triggered when a settlement has been initiated by Cashfree Payments.


{
    "data": {
        "settlement": {
            "adjustment": 0,
            "amount_settled": 5,
            "payment_amount": 5,
            "payment_from": "2022-03-17",
            "payment_till": "2022-03-17",
            "reason": null,
            "service_charge": 0,
            "service_tax": 0,
            "settled_on": "2022-03-17T14:21:18+05:30",
            "settlement_amount": 5,
            "settlement_id": 1155353,
            "settlement_initiated_on": "2022-03-17T14:29:21+05:30",
            "status": "INITIATED",
            "utr": "N076221079016329"
        },
        "event_time": "2022-03-17T14:29:23+05:30",
        "type": "SETTLEMENT_INITIATED"
    }
}

Settlement Success


{
    "data": {
        "settlement": {
            "adjustment": 0,
            "amount_settled": 5,
            "payment_amount": 5,
            "payment_from": "2022-03-17",
            "payment_till": "2022-03-17",
            "reason": null,
            "service_charge": 0,
            "service_tax": 0,
            "settled_on": "2022-03-17T14:21:18+05:30",
            "settlement_amount": 5,
            "settlement_id": 1155353,
            "settlement_initiated_on": "2022-03-17T14:29:21+05:30",
            "status": "SUCCESS",
            "utr": "N076221079016329"
        },
        "event_time": "2022-03-17T14:29:23+05:30",
        "type": "SETTLEMENT_SUCCESS"
    }
}

Settlement Failed


{
    "data": {
        "settlement": {
            "adjustment": 0,
            "amount_settled": 5,
            "payment_amount": 5,
            "payment_from": "2022-03-17",
            "payment_till": "2022-03-17",
            "reason": "REASON",
            "service_charge": 0,
            "service_tax": 0,
            "settled_on": "2022-03-17T14:21:18+05:30",
            "settlement_amount": 5,
            "settlement_id": 1155353,
            "settlement_initiated_on": "2022-03-17T14:29:21+05:30",
            "status": "FAILED",
            "utr": "N076221079016329"
        },
        "event_time": "2022-03-17T14:29:23+05:30",
        "type": "SETTLEMENT_FAILED"
    }
}

Settlement Reversed


{
    "data": {
        "settlement": {
            "adjustment": 0,
            "amount_settled": 5,
            "payment_amount": 5,
            "payment_from": "2022-03-17",
            "payment_till": "2022-03-17",
            "reason": "REASON",
            "service_charge": 0,
            "service_tax": 0,
            "settled_on": "2022-03-17T14:21:18+05:30",
            "settlement_amount": 5,
            "settlement_id": 1155353,
            "settlement_initiated_on": "2022-03-17T14:29:21+05:30",
            "status": "REVERSED",
            "utr": "N076221079016329"
        },
        "event_time": "2022-03-17T14:29:23+05:30",
        "type": "SETTLEMENT_REVERSED"
    }
}

Payload Field Description

FieldDescriptionExample
adjustmentSum of refunds, disputes, and chargeback part of this settlement is displayed here.0
amount_settledTotal amount that is settled in this settlement cycle.15
payment_amountTotal transaction amount considered for settlement.15
payment_fromStart date and time from which the payments are considered for settlement.2022-02-14 12:00:00
payment_tillEnd date and time till which the payments are considered for settlement.2022-02-23 12:00:00
reasonReason for failed and reversed settlements. Click here to know more.Transfer mode not valid for beneficiary.
service_chargeService charges applicable for the payments that are included in this settlement.2
service_taxService tax applicable for the payments that are included in this settlement.0
settled_onDate and time at which the settlement was processed.2022-03-17T14:21:18+05:30
settlement_typeIndicates the settlement type.INSTANT
settlement_amountSum of net settlement amount for the payments part of this settlement.13
settlement_idCashfree settlement ID1155353
settlement_initiated_onDate on which settlement was initiated.2022-03-17T14:29:21+05:30
statusStatus of the settlement (either INITIATED, SUCCESS, FAILED, or REVERSED)SUCCESS
utrUnique transaction reference number given by the bank for the settlement.N076221079016329
settlement_chargeThe additional charge applicable for instant settlement.10.10
settlement_taxThe settlement tax applicable for instant settlement.01.97
remarksAny remarks specified by the merchant.Settlement Initiated
event_timeTime at which settlement webhook was initiated.2022-03-17T14:29:23+05:30
typeType of webhook - SETTLEMENT_INITIATED, SETTLEMENT_SUCCESS, SETTLEMENT_FAILED, or SETTLEMENT_REVERSED.SETTLEMENT_SUCCESS

Reasons for Failed and Reversed Settlements

ReasonCategoryDescription
BANK_GATEWAY_ERRORBankTechnical error at the bank
BENE_BANK_DECLINEDBankRejected by Beneficiary bank due to business reasons
FAILEDBankNo explicit failure reason from the bank
INVALID_IFSC_FAILCustomerInvalid ifsc code provided for bank account
INVALID_ACCOUNT_FAILCustomerBank account is invalid
RETURNED_FROM_BENEFICIARYBankImmediate reversal from the beneficiary bank
INSUFFICIENT_BALANCEMerchantMerchant balance is exhausted, need to add funds
IMPS_MODE_FAILBankIMPS mode not supported for the beneficiary
RTGS_MODE_FAILBankRTGS mode not supported (only for RTGS)
REINITIALIZE_TRANSFER_LATERBankTechnical error at the bank, retry later
NRE_ACCOUNT_FAILCustomerCustomer bank account is an NRE account
ACCOUNT_BLOCKEDCustomerCustomer bank account is blocked
DEST_LIMIT_REACHEDBankTransfer limit to beneficiary exceeded
INVALID_MODE_FAILBankTransfer mode not valid for beneficiary
NPCI_UNAVAILABLEBankNPCI in unavailable
BENEFICIARY_BANK_OFFLINEBankBeneficiary bank is offline
INVALID_AMOUNT_FAILMerchantAmount is invalid for the given transfer mode
SUSPECTED_TRANSFERCustomerSuspicious transfer identified
BENE_NAME_DIFFERSCustomerBeneficiary name not matching with bank records
DISABLED_MODEMerchantTransfer mode not enabled for the account
AMAZON_AMOUNT_EXCEEDMerchantAmount should be less than 10000 for Amazon Pay mode
BENEFICIARY_BLACKLISTEDMerchantBeneficiary is blacklisted
PAYOUT_INACTIVEMerchantPayout account is not active
INVALID_TRANSFER_AMOUNTMerchantTransfer amount is invalid
BENEFICIARY_NOT_EXISTMerchantBeneficiary does not exist
BENEFICIARY_INVALID_MODEMerchantMode Not valid for Beneficiary
INVALID_BENE_ACCOUNT_OR_IFSCMerchantInvalid bank account number or ifsc provided
BENEFICIARY_NAME_DIFFERSCustomerBeneficiary name not matching with bank records
ANY_OTHER_REASONBankNo reason provided for the failure/reversal
INVALID_OR_NO_SUCH_ACCOUNT_TYPECustomerInvalid account

Signature Verification

The signature must be used to verify if the request has not been tampered with. To verify the signature at your end, you will need your Cashfree PG secret key along with the payload.

timestamp is present in the header x-webhook-timestamp

timestamp := 1617695238078;  
signedPayload := $timestamp.$payload;
expectedSignature := Base64Encode(HMACSHA256($signedPayload, $merchantSecretKey));