Cashfree Payments Developer Documentation

Cashfree Payments will notify you whenever we create an incident at our end. An incident implies that the issuing bank is facing high failure rates or has scheduled a maintenance activity during that time. The former could be due to many reasons and until the failure rates go down, we would recommend customers to use alternative payment instruments. There are two channels through which we notify. You can subscribe to either of the channels by adding your email address and webhook endpoint in the merchant dashboard. Email - Cashfree Payments will send an email alert when an issuer is facing downtime or a scheduled incident. Webhooks - Cashfree Payments will invoke a server to server call whenever an incident is created. You can use this webhook and update your payment page accordingly.

Webhook Schema of Incident Service Webhook

Sample Payload for Creation of Incident

Version (2025-01-01)

{
  "data": {
    "incident": {
      "end_time": "2025-04-29T09:11:48+05:30",
      "id": "x77rkd7phl5dobr94k1s",
      "impact": "HIGH",
      "message": "Payment mode up",
      "start_time": "2025-04-22T09:11:48+05:30",
      "status": "RESOLVED",
      "type": "SCHEDULED"
    },
    "instruments": {
      "upi": {
        "issuers": [
          "DEUTSCHE BANK"
        ]
      }
    }
  },
  "event_time": "2025-04-22T14:42:08+05:30",
  "type": "HEALTH_ALERT"
}

Sample Payload When Incident is Resolved

Version (2025-01-01)

{
    "data": {
      "incident": {
        "end_time": "2025-04-29T09:11:48+05:30",
        "id": "x77rkd7phl5dobr94k1s",
        "impact": "HIGH",
        "message": "Payment mode up",
        "start_time": "2025-04-22T09:11:48+05:30",
        "status": "RESOLVED",
        "type": "SCHEDULED"
      },
      "instruments": {
        "upi": {
          "issuers": [
            "DEUTSCHE BANK"
          ]
        }
      }
    },
    "event_time": "2025-04-22T14:42:08+05:30",
    "type": "HEALTH_ALERT"
}

Payload

Field	Description	Example	Mandatory
end_time	Null when an incident is created. Or end time when incident is resolved	2021-04-16T15:10:36+05:30	No
start_time	Time since we have seen this incident	2021-04-16T14:10:36+05:30	Yes
id	Incident id	Alphanumeric with _,-	Yes
impact	Impact of the downtime	HIGH, MEDIUM, LOW	Yes
message	Human readable message		No
status	Status of the incident. OPEN when created, RESOLVED when resolved, UPDATE when updated with details	OPEN, UPDATE, RESOLVED	Yes
type	Is this a scheduled or an unscheduled downtime?	SCHEDULED, UNSCHEDULED	Yes
instruments	Refers to the payment mode. This will contain a nested object		Yes
upi.issuers	Issuers which are impacted	Array	No
net_banking.issuers	Net banking banks which are impacted	Array	No
wallet.issuers	Wallets which are impacted	Array	No
card.type	Card types which are impacted	CREDIT_CARD, DEBIT_CARD, ALL	No
card.scheme	Card schemes which are impacted	MASTER, VISA, RUPAY, MAESTRO, AMEX, Multiple Schemes	No
card.issuers	Banks which are impacted	Array	No
event_time	Time when this webhook was created		Yes
type	Type of webhook	HEALTH_ALERT	Yes
version	Version of webhook. You should build your parsing logic with respect to this version		Yes

Children	Optional	Type	Possible Values
wallet	Y*	Child attributes	Available below
net_banking	Y*	Child attributes	Available below
upi	Y*	Child attributes	Available below
card	Y*	Child attributes	Available below

At least one of the children needs to be present

Wallet

Children	Optional	Type	Possible Values
issuers	N	Text	See list of wallet issuers below.

Net Banking

Children	Optional	Type	Possible Values
issuers	N	Array	See list of issuers below.

UPI

Children	Optional	Type	Possible Values
issuers	N	Array	See list of issuers below.

Card

Children	Optional	Type	Possible Values
type	N	Text	CREDIT_CARD, DEBIT_CARD, ALL
scheme	N	Text	MASTER, VISA, RUPAY, MAESTRO, AMEX, Multiple Schemes
issuers	N	Array	See list of issuers below.

Payload Headers

Cashfree Payments will send two custom headers for every webhook being invoked by our system.

Name	Description	Example
x-cashfree-timestamp	Timestamp for this event. Used to generate signature	1618562436364
x-cashfree-signature	Cashfree Payments signature for this webhook	ke+K3gR8GssH9AMfJm+0+8jGIL1Mq7hOheP9w36/hL0=

Signature Generation

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 Payment Gateway secret key along with the payload.

//The payload here refers to the raw request sent by 
Cashfree to your endpoint. No modifications need to be 
done to this payload.

payload := {"data":{"bank_name":"Test Bank",
"card_type":"Visa","health":"DEGRADED",
"incident_end_time":"2021-04-07T00:20:30",
"incident_id":"INCIDENT_HIGH_Test Bank_954b95zz-f11a-test-abcd-0eb0e8608847",
"incident_impact":"High",
"incident_start_time":"2021-04-06T00:20",
"incident_type":"Scheduled",
"is_resolved":false,
"issuers":[],
"message":"We are facing high failure issues in Payment gateway at the moment and will keep you updated about the issue.",
"payment_gateway":null,"payment_mode":"DEBIT_CARD",
"scope":"PaymentMode"},
"type":"HEALTH_ALERT","version":1}

# timestamp is present in the header x-cashfree-timestamp
timestamp := 1617695238078

signedPayload := $timestamp.$payload

expectedSignature := Base64Encode(HMACSHA256($signedPayload, $merchantSecretKey))

Bank Names

Axis Bank
Bank of Baroda - Retail Banking
Bank of India
Bank of Maharashtra
Canara Bank
Catholic Syrian Bank
Central Bank of India
City Union Bank
Deutsche Bank
DBS Bank Ltd
DCB Bank - Personal
Dhanlakshmi Bank
Federal Bank
HDFC Bank
ICICI Bank
IDBI Bank
IDFC Bank
Indian Bank
Indian Overseas Bank
IndusInd Bank
Jammu and Kashmir Bank
Karnataka Bank Ltd
Karur Vysya Bank
Kotak Mahindra Bank
Laxmi Vilas Bank - Retail Net Banking
Punjab & Sind Bank
Punjab National Bank - Retail Net Banking
RBL Bank
Saraswat Bank
South Indian Bank
Standard Chartered Bank
State Bank Of India
Tamilnad Mercantile Bank Ltd
UCO Bank
Union Bank of India
Yes Bank Ltd
Bank of Baroda - Corporate
Bank of India - Corporate
DCB Bank - Corporate
Lakshmi Vilas Bank - Corporate
Punjab National Bank - Corporate
State Bank of India - Corporate
Union Bank of India - Corporate
Axis Bank Corporate
Dhanlaxmi Bank Corporate
ICICI Corporate Netbanking
Ratnakar Corporate Banking
Shamrao Vithal Bank Corporate
Equitas Small Finance Bank
Yes Bank Corporate
Bandhan Bank- Corporate banking
Barclays Corporate- Corporate Banking - Corporate
Indian Overseas Bank Corporate
City Union Bank of Corporate
HDFC Corporate
Shivalik Bank
AU Small Finance
Bandhan Bank - Retail Net Banking
Shamrao Vitthal Co-operative Bank
Tamil Nadu State Co-operative Bank

All Banks (Note: This parameter will be sent when all banks are having a downtime)

Wallet Names

FreeCharge
MobiKwik
Ola Money
Reliance Jio Money
Airtel Money
Paytm
Amazon Pay
PhonePe

Compute Signature and Verify

Sample Code

Verify Signature using SDK

var express = require('express')
import { Cashfree } from "cashfree-pg"; 
var app = express()

Cashfree.XClientId = "<x-client-id>";
Cashfree.XClientSecret = "<x-client-secret>";
Cashfree.XEnvironment = Cashfree.Environment.SANDBOX;

app.post('/webhook', function (req, res) {
    try {
        Cashfree.PGVerifyWebhookSignature(req.headers["x-webhook-signature"], req.rawBody, req.headers["x-webhook-timestamp"]))
    } catch (err) {
        console.log(err.message)
    }
})

Compute Signature and Verify manually

function verify(ts, rawBody){
    const body = req.headers["x-webhook-timestamp"] + req.rawBody;
    const secretKey = "<your secret key>";
    let genSignature = crypto.createHmac('sha256',secretKey).update(body).digest("base64");
    return genSignature
}

Payments API

v2025-01-01

Other Versions

Incident Service Webhook

Webhook Schema of Incident Service Webhook

Sample Payload for Creation of Incident

Sample Payload When Incident is Resolved

Payload

Wallet

Net Banking

UPI

Card

Payload Headers

Signature Generation

Bank Names

Wallet Names

Compute Signature and Verify

Sample Code

Verify Signature using SDK

Compute Signature and Verify manually

Payments API

v2025-01-01

Other Versions

​Webhook Schema of Incident Service Webhook

​Sample Payload for Creation of Incident

​Sample Payload When Incident is Resolved

​Payload

​Wallet

​Net Banking

​UPI

​Card

​Payload Headers

​Signature Generation

​Bank Names

​Wallet Names

​Compute Signature and Verify

​Sample Code

​Verify Signature using SDK

​Compute Signature and Verify manually

Webhook Schema of Incident Service Webhook

Sample Payload for Creation of Incident

Sample Payload When Incident is Resolved

Payload

Wallet

Net Banking

UPI

Card

Payload Headers

Signature Generation

Bank Names

Wallet Names

Compute Signature and Verify

Sample Code

Verify Signature using SDK

Compute Signature and Verify manually