Webhooks
Webhooks are server callbacks to your server from Cashfree. Webhooks are event-based and are sent when specific events related to the transaction happen.
Configure Webhook
- Add your webhook through the merchant dashboard for the first time. Write to [email protected] to edit your Webhook endpoint.
- Ensure you do not process duplicate events.
- Below is the list of events for which we will be notifying on your webhook and a list of parameters being sent.
- Before testing the webhook from the dashboard make sure that you have generated the API keys.
We support webhooks in both encoded and JSON formats.
Amount Collected
The AMOUNT_COLLECTED webhook notifies that money has been received in your Cashfree Virtual account through Auto Collect.
Webhook parameters and descriptions are available below:
Parameter | Description |
---|---|
event | It contains the name of the event which just occurred. Value = AMOUNT_COLLECTED. |
amount | Specifies the amount collected. |
vAccountId | The virtual account ID of the customer who made the payment. |
virtualVpaId | The virtual account ID of the customer who made the payment (if received via VPA). |
isVpa | Value is 1 if the amount is paid via VPA transfer. |
vAccountNumber | The virtual bank account number (if received to Virtual Bank Account). |
referenceId | The reference number generated by Cashfree to track the transaction. |
utr | Unique transaction reference number provided by the bank. |
remitterVpa | Payer's VPA details in case of UPI transactions. |
Customer email address. | |
phone | Customer phone number. |
creditRefNo | Reference number generated by the bank. |
remitterAccount | Payer's bank account number. |
remitterName | Payer's name. |
paymentTime | Time at which the payment was made. |
signature | A unique string that helps distinguish that the request is genuine and initiated by Cashfree. |
transferType | (Applicable from Feb 4th, 2022) Indicates the mode through which the transaction was made to your Auto Collect Virtual account, such as NEFT, RTGS, UPI, or IMPS. |
remarks | (Applicable from Feb 4th, 2022) Remarks that the customer enters when the transaction is initiated. |
Note:
With effect from Feb 4, 2022, we will be adding two new parameters to the βAmount Collectedβ Webhook i.e βtransferTypeβ and βremarks.β
βtransferTypeβ will notify the mode through which the transaction was made to your Auto Collect Virtual account, such as NEFT, RTGS, UPI, or IMPS.
βremarksβ will be the remarks that the customer passes when the transaction is initiated.
Transfer Rejected
The TRANSFER_REJECTED webhook notifies that the transfer request was received, but has been rejected due to some reason (mentioned in the field reason).
Parameter | Description |
---|---|
event | It contains the name of the event which just occurred. Value = TRANSFER_REJECTED. |
amount | Specifies the amount collected. |
vAccountId | The virtual account ID of the customer who made the payment. |
rejectId | The transfer rejected transaction ID. |
utr | Unique transaction reference number provided by the bank. |
remitterAccount | Payer's bank account number. |
transferTime | Time at which the transfer was made. |
reason | Specifies the reason for rejecting the transfer. |
signature | A unique string which helps distinguish that the request is genuine and initiated by Cashfree. |
Amount Settled
The AMOUNT_SETTLED webhook notifies that the settlement has been made.
Parameter | Description |
---|---|
event | It contains the name of the event which just occurred. Value = AMOUNT_SETTLED. |
amount | Specifies the amount settled. (SettlementAmount + adjustment = amount) |
count | No. of transactions that are settled. |
utr | Unique transaction reference number provided by the bank. |
settlementId | Reference number of the settlement made. |
settlementAmount | The settlement amount will be the total transaction amount minus the service charges and taxes. |
adjustment | The differential amount that was deducted or added in the current schedule option. (SettlementAmount + adjustment = amount) |
signature | A unique string that helps distinguish that the request is genuine and initiated by Cashfree. |
Example - AMOUNT_COLLECTED webhook
{
"event":"AMOUNT_COLLECTED",
"amount":"400",
"vAccountId":"abcd123",
"virtualVpaId":"cashmelgabcd123@yesbankltd",
"isVpa":"1",
"email":"[email protected]",
"phone":"9876543210",
"referenceId":87654,
"utr":"N123456789",
"creditRefNo":"0976541123",
"remitterAccount":"123455666778",
"remitterName":"CASHFREE PAYMENTS",
"paymentTime":"2019-07-20 15:27:37",
"signature":"8uV792gBZaasJHBFSsfaMHLuqnZKkoBFjw9gEJ8Sx85V+jgbpg4ME="
}
Refunds
For refunds, we support the following three webhooks:
Refund Success
The REFUND_SUCCESS webhook notifies whenever a refund attempt is successful at the bank (the account is debited), and the beneficiary bank has deposited the money and confirmed it.
Webhook parameters and descriptions are available below:
Parameter | Description |
---|---|
event | It contains the name of the event which just occurred. Value = REFUND_SUCCESS. |
cacRefundId | The Refund ID that Cashfree Autocollect generated and shared with the merchant during the creation of the refund. |
referenceId | The reference number provided by Cashfree Payments for the transaction. |
amount | Specifies the refund amount |
note | Note that the merchant enters when the refund is initiated. |
merchantRefId | MerchantRefId that the merchant enters when the refund is initiated. |
refundUtr | Unique transaction reference number provided by the bank. |
refundStatus | Status of the refund. Possible statuses are: - ACKNOWLEDGED - PROCESSING - SUCCESS - FAILED - REVERSED |
createdAt | Time at which the refund was initiated. |
updatedAt | Time of the last update |
refundRemarks | - |
fundStatus | DEBITED_FROM_MERCHANT |
signature | A unique string that helps distinguish that the request is genuine and initiated by Cashfree Payments. |
Refund Failed
The REFUND_FAILED webhook notifies whenever a refund attempt fails.
Webhook parameters and descriptions are available below:
Parameter | Description |
---|---|
event | It contains the name of the event which just occurred. Value = REFUND_FAILED. |
cacRefundId | The Refund ID that Cashfree Autocollect generated and shared with the merchant during the creation of the refund. |
referenceId | The reference number provided by Cashfree Payments for the transaction. |
amount | Specifies the refund amount |
note | Note that the merchant enters when the refund is initiated. |
merchantRefId | MerchantRefId that the merchant enters when the refund is initiated. |
refundUtr | Unique transaction reference number provided by the bank. |
refundStatus | Status of the refund. Possible statuses are: - ACKNOWLEDGED - PROCESSING - SUCCESS - FAILED - REVERSED |
createdAt | Time at which the refund was initiated. |
updatedAt | Time of the last update |
refundRemarks | Reason for failure |
fundStatus | RETURNED_TO_MERCHANT |
signature | A unique string that helps distinguish that the request is genuine and initiated by Cashfree Payments. |
Refund Reversed
The REFUND_REVERSED webhook notifies whenever the beneficiary bank reverses the refund.
Webhook parameters and descriptions are available below:
Parameter | Description |
---|---|
event | It contains the name of the event which just occurred. Value = REFUND_REVERSED. |
cacRefundId | The Refund ID that Cashfree Autocollect generated and shared with the merchant during the creation of the refund. |
referenceId | The reference number provided by Cashfree Payments for the transaction. |
amount | Specifies the refund amount |
note | Note that the merchant enters when the refund is initiated. |
merchantRefId | MerchantRefId that the merchant enters when the refund is initiated. |
refundUtr | Unique transaction reference number provided by the bank. |
refundStatus | Status of the refund. Possible statuses are: - ACKNOWLEDGED - PROCESSING - SUCCESS - FAILED - REVERSED |
createdAt | Time at which the refund was initiated. |
updatedAt | Time of the last update |
refundRemarks | Reason for reversal. |
fundStatus | RETURNED_TO_MERCHANT |
signature | A unique string that helps distinguish that the request is genuine and initiated by Cashfree Payments. |
Webhook Sample
{
"amount": "250.12",
"referenceId": "100",
"cacRefundId": "98",
"createdAt": "2022-03-13 22:30:38",
"event": "REFUND_SUCCESS",
"fundStatus": "CREDITED_TO_CUSTOMER",
"merchantRefId": "test100",
"note": "test",
"refundRemarks": "Transfer completed successfully",
"refundStatus": "SUCCESS",
"refundUtr": "1647190899292747",
"signature": "1WP7Pm5CQ1XpLLO+0zups2E6ae/VyMq4MMPAWpC8syE=",
"updatedAt": "2022-03-13 22:31:39"
}
Vendor Settlement
The VENDOR_SETTLEMENT_WEBHOOK notifies when a settlement has been made to the vendor.
Parameter | Description |
---|---|
vendorRefId | Unique reference ID of the vendor. |
signature | A unique string that helps distinguish that the request is genuine and initiated by Cashfree Payments. |
amount | The aggregated amount in the settlement time period. (SettlementAmount + adjustment = amount) |
adjustment | Any debit or credit amount due to pending ledger balance or any other adjustment. (SettlementAmount + adjustment = amount) |
settlementAmount | Sum of the net settlement amount for the payments part of this settlement. |
vendorSettlementRefId | Unique reference ID for the vendor settlement. |
utr | Unique transaction reference number provided by the bank. |
count | Number of payments considered in the settlement. |
event | It contains the name of the event which just occurred. Value = VENDOR_SETTLEMENT_WEBHOOK. |
Verify Signature
Verifying the signature (passed along with the POST parameters) is mandatory before you process any response. We also recommend whitelisting only our IP address on your webhook endpoint.
Follow the steps below to calculate and verify the signature passed:
- Get all the POST parameters except βsignatureβ and assign it to an array as key-value pair.
- Sort the array based on keys.
- Concatenate all the values in this array and the resultant is the post data (say, postData).
- postData needs to be encrypted using SHA-256 and then base64 encoded.
- Now verify if the signature calculated and the signature received a match. Proceed further if it matches.
Note:
To verify the signature, use the active API key that was generated first (old API key) and not the latest API keys. Do not go live without verifying the signature.
The following code snippets show you how to generate and verify the signature. This should not be assumed production-ready, kindly consider adding necessary validation before processing.
$data = $_POST;
$signature = $_POST["signature"];
unset($data["signature"]);
// $data now has all the POST parameters except signature
ksort($data); // Sort the $data array based on keys
$postData = "";
foreach ($data as $key => $value){
if (strlen($value) > 0) {
$postData .= $value;
}
}
$hash_hmac = hash_hmac('sha256', $postData, $clientSecret, true) ;
// Use the clientSecret from the oldest active Key Pair.
$computedSignature = base64_encode($hash_hmac);
if ($signature == $computedSignature) {
// Proceed based on $event
} else {
// Reject this call
}
?>
import javax.crypto.spec.SecretKeySpec;
import javax.crypto.Mac;
import org.apache.commons.codec.binary.Base64;
public class ComputedSignature {
public static String generateHMAC(String clientSecret, String data) {
String hash = null; //data is a string which has the json sorted through keys and concatenated values
try {
String secret = clientSecret;
String message = data;
Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
SecretKeySpec secret_key = new SecretKeySpec(secret.getBytes(),"HmacSHA256");
sha256_HMAC.init(secret_key);
hash = Base64.encodeBase64String(sha256_HMAC.doFinal(message.getBytes()));
}
catch (Exception e){ //Log it
}
return hash;
}
}
Updated 10 months ago