Configure Webhook

To configure the webhook, go to Partner Dashboard > Developers > Webhooks. Add your webhook endpoint where you want to receive alerts. Ensure you do not process duplicate events.

Webhook will be sent to your configured endpoint as a POST request with the body containing the various parameters specifying the details of each event. Each request contains an event parameter that identifies its type.

We support webhooks in both encoded and JSON formats.

Webhook header parameters and descriptions are available below:

Parameter	Description
x-cashfree-timestamp	Timestamp in ISO format. Time at which the webhook is triggered.
x-cashfree-signature	String. It is a base64 encoded entity of the hash (SHA256) of the raw payload sorted by alphabetical order of keys and the latest partner api key. This signature should be used to verify authenticity of the webhook.

Webhook parameters and descriptions are available below:

Parameter	Description
data.merchant_id	Unique merchant id provided by the partner at the time of merchant creation.
data.merchant_name	Name of the merchant
data.created_at	Timestamp in ISO format for when the merchant was created in CF system.
data.onboarding_status	Onboarding status for the merchant
event_time	Timestamp in ISO format. Time when event was created.
type	Type of webhook. Value is “MERCHANT_ONBOARDING_STATUS”
version	Version of webhook. Default is 1.

Example - MERCHANT_ONBOARDING_STATUS webhook

{
 "data": {
    “merchant_id” : “CF89797”,
    “created_at” : “2021-06-23T23:15:20+0530”,
    “merchant_name” : “Business A”,
    “onboarding_status” : “ACTIVE”
    },
 "event_time": "2021-04-16T14:10:36+05:30",
 "type": "MERCHANT_ONBOARDING_STATUS",
 "version": 1
}

Verify Signature

Verifying the signature (passed along with the POST parameters as header) is mandatory before you process any response. We also recommending whitelisting only our IP address on your webhook endpoint.

Follow steps below to calculate and verify the signature passed:

Get all the POST parameters 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.
For the SHA-256 encryption use the latest api key as the secret key.
Now verify if the signature calculated and the signature received a match. Proceed further if it matches.

Do not go live without verifying the signature.

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, $apiKey, 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 = apiKey;
            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;
    }
}

Activation Lifecycle

Onboarding Status

Pending Email Verification: The Merchant must first verify their registered email address. An email is sent automatically from Cashfree Payments (from [email protected]) to the merchant email ID you specified when you added the merchant details.
If the merchant has not received the email in their Primary inbox, please ask them to check it in the Spam folder. If the merchant has not received the email you can use the Resend Email email to send the verification email again.

Email Verified: This means that Merchant has verified their email address, and can now start their KYC verification process.

KYC Status

Min KYC Pending: Merchant must submit the required KYC details and documents.
Min KYC Submitted: Merchant has submitted their KYC details and documents and the documents are being reviewed by Cashfree Payments
Min KYC Rejected: Merchant KYC has discrepancies and corresponding KYC details and documents need to be provided.
Min KYC Approved: Merchant KYC has been approved and Payment Gateway product is activated.

📘
Note:
If the merchants have verified their email you can fill out the KYC on behalf of the merchant and activate the account for your merchants.