Vendor Settlement Webhooks

Configure settlement webhooks to receive automated notifications when vendor 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.

The table below lists the webhook events available for settlements.

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 Initiated

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


{
    "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": null,
            "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": 46695,
            "vendor_transaction_amount": 10
        },
        "event_time": "2022-05-26T15:06:15+05:30",
        "type": "VENDOR_SETTLEMENT_INITIATED"
    }
}

Vendor Settlement Success


{
    "data": {
        "settlement": {
            "adjustment": 0,
            "amount_settled": 50,
            "payment_amount": null,
            "payment_from": "2022-04-01",
            "payment_till": "2022-04-01",
            "reason": null,
            "service_charge": 0.25,
            "service_tax": 0.05,
            "settled_on": "2022-04-01T15:03:31+05:30",
            "settled_orders_count": null,
            "settlement_amount": 50,
            "settlement_id": 3598,
            "settlement_initiated_on": "2022-04-01T13:51:00+05:30",
            "settlement_type": null,
            "status": "SUCCESS",
            "utr": 98756789343,
            "vendor_id": 46696,
            "vendor_transaction_amount": 50
        },
        "event_time": "2022-04-01T16:47:12+05:30",
        "type": "VENDOR_SETTLEMENT_SUCCESS"
    }
}

Vendor Settlement Failed


{
    "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": null,
            "settlement_amount": 10,
            "settlement_id": 6151,
            "settlement_initiated_on": "2022-05-26T15: 06: 09+05: 30",
            "settlement_type": null,
            "status": "FAILED",
            "utr": null,
            "vendor_id": 46695,
            "vendor_transaction_amount": 10
        },
        "event_time": "2022-05-26T15:06:15+05:30",
        "type": "VENDOR_SETTLEMENT_FAILED"
    }
}

Vendor Settlement Reversed


{
    "data": {
        "settlement": {
            "adjustment": 0,
            "amount_settled": 50,
            "payment_amount": null,
            "payment_from": "2022-04-01",
            "payment_till": "2022-04-01",
            "reason": null,
            "service_charge": 0.25,
            "service_tax": 0.05,
            "settled_on": "2022-04-01T15:03:31+05:30",
            "settled_orders_count": null,
            "settlement_amount": 50,
            "settlement_id": 3598,
            "settlement_initiated_on": "2022-04-01T13:51:00+05:30",
            "settlement_type": null,
            "status": "REVERSED",
            "utr": 98756789343,
            "vendor_id": 46696,
            "vendor_transaction_amount": 50
        },
        "event_time": "2022-04-01T16:47:12+05:30",
        "type": "VENDOR_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.

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. 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.50

settled_on

Date and time at which the settlement was processed.

2022-03-17T14:21:18+05:30

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

vendor_id

Reference number given by cashfree to each onboarded vendor

6456

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

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

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

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-cashfree-timestamp

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

Did this page help you?