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 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. |
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
| Field | Description | Example |
|---|---|---|
| adjustment | Sum of refunds, disputes, and chargeback part of this settlement is displayed here. | 0 |
| amount_settled | Total amount that is settled in this settlement cycle. | 15 |
| payment_amount | Total transaction amount considered for settlement. | 15 |
| payment_from | Start date and time from which the payments are considered for settlement. | 2022-02-14 12:00:00 |
| payment_till | End date and time till which the payments are considered for settlement. | 2022-02-23 12:00:00 |
| reason | Reason for failed and reversed settlements. Click here to know more. | Transfer mode not valid for beneficiary. |
| service_charge | Service charges applicable for the payments that are included in this settlement. | 2 |
| service_tax | Service tax applicable for the payments that are included in this settlement. | 0 |
| settled_on | Date and time at which the settlement was processed. | 2022-03-17T14:21:18+05:30 |
| settlement_type | Indicates the settlement type. | INSTANT |
| settlement_amount | Sum of net settlement amount for the payments part of this settlement. | 13 |
| settlement_id | Cashfree settlement ID | 1155353 |
| settlement_initiated_on | 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 | Unique transaction reference number given by the bank for the settlement. | N076221079016329 |
| settlement_charge | The additional charge applicable for instant settlement. | 10.10 |
| settlement_tax | The settlement tax applicable for instant settlement. | 01.97 |
| remarks | Any remarks specified by the merchant. | Settlement Initiated |
| event_time | Time at which settlement webhook was initiated. | 2022-03-17T14:29:23+05:30 |
| type | Type of webhook - SETTLEMENT_INITIATED, SETTLEMENT_SUCCESS, SETTLEMENT_FAILED, or SETTLEMENT_REVERSED. | 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 | Merchant | Merchant 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 in unavailable |
| BENEFICIARY_BANK_OFFLINE | Bank | Beneficiary bank is offline |
| INVALID_AMOUNT_FAIL | Merchant | 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 | Merchant | Transfer mode not enabled for the account |
| AMAZON_AMOUNT_EXCEED | Merchant | Amount should be less than 10000 for Amazon Pay mode |
| BENEFICIARY_BLACKLISTED | Merchant | Beneficiary is blacklisted |
| PAYOUT_INACTIVE | Merchant | Payout account is not active |
| INVALID_TRANSFER_AMOUNT | Merchant | Transfer amount is invalid |
| BENEFICIARY_NOT_EXIST | Merchant | Beneficiary does not exist |
| BENEFICIARY_INVALID_MODE | Merchant | Mode Not valid for Beneficiary |
| INVALID_BENE_ACCOUNT_OR_IFSC | Merchant | 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
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));Compute Signature and Verify
function verify(ts, rawBody){
const body = ts + rawBody
const secretKey = "<your secret key>";
let genSignature = crypto.createHmac('sha256',secretKey).update(body).digest("base64");
return genSignature
}
func VerifySignature(expectedSig string, ts int64, body string) (string, error) {
t := time.Now()
currentTS := t.Unix()
if currentTS-ts > 1000*300 {
return "", errors.New("webhook delivered too late")
}
signStr := strconv.FormatInt(ts, 10) + body
fmt.Println("signing String: ", signStr)
key := ""
h := hmac.New(sha256.New, []byte(key))
h.Write([]byte(signStr))
b := h.Sum(nil)
return base64.StdEncoding.EncodeToString(b), nil
}
function computeSignature($ts, $rawBody){
$signStr = $ts . $rawBody;
$key = "";
$computeSig = base64_encode(hash_hmac('sha256', $signStr, $key, true));
return $computeSig;
}
public String generateSignature() {
String payload = "json payload in string";
String timestamp = "x-webhook-timestamp";
String data = timestamp+payload;
String secretKey = "SECRET-KEY"; // Get secret key from Cashfree Merchant Dashboard;
Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
SecretKeySpec secret_key_spec = new SecretKeySpec(secretKey.getBytes(),"HmacSHA256");
sha256_HMAC.init(secret_key_spec);
String computed_signature = Base64.getEncoder().encodeToString(sha256_HMAC.doFinal(data.getBytes()));
return computed_signature; // compare with "x-webhook-signature"
}
import base64
import hashlib
import hmac
def generateSignature():
timestamp = "timestamp data"
payload = 'json data in string'
signatureData = timestamp+payload
message = bytes(signatureData, 'utf-8')
secretkey=bytes("Secret_Key",'utf-8') #Get Secret_Key from Cashfree Merchant Dashboard.
signature = base64.b64encode(hmac.new(secretkey, message, digestmod=hashlib.sha256).digest())
computed_signature = str(signature, encoding='utf8')
return computed_signature #compare with "x-webhook-signature"
Updated 2 months ago