softPOS Webhooks v2022 | Cashfree Payments

Webhooks are server callbacks to your server from Cashfree Payments. Webhooks are event-based and are sent when specific events related to the transaction happen. Cashfree Payments sends the following webhooks for softPOS:

Payment success webhook version: (2022-09-01)

The new payment success webhook notifies you about the payment, and gives you comprehensive information about successful payments. A notification is sent to your backend from Cashfree Payments when payments are successful. These notifications are useful in cases when the internet connection is unstable or slow while the payment is being processed. This will allow you to reconcile all the successful orders at your end. Notifications will be sent to notifyUrl which is a part of the request parameter specified while creating an order request as well as endpoints configured on the Merchant Dashboard.

Sample payload

  "data": {
        "order": {
            "order_id": "order_OFR_2",
            "order_amount": 2,
            "order_currency": "INR",
            "order_tags": null
        },
        "payment": {
            "cf_payment_id": 1453002795,
            "payment_status": "SUCCESS",
            "payment_amount": 1,
            "payment_currency": "INR",
            "payment_message": "00::Transaction success",
            "payment_time": "2022-12-15T12:20:29+05:30",
            "bank_reference": "234928698581",
            "auth_id": null,
            "payment_method": {
                "upi": {
                    "channel": null,
                    "upi_id": "9611199227@paytm"
                }
            },
            "payment_group": "upi"
        },
        "customer_details": {
            "customer_name": null,
            "customer_id": "7112AAA812234",
            "customer_email": "[miglaniyogesh7@gmail.com]()",
            "customer_phone": "9908734801"
        },
        "payment_gateway_details": {
            "gateway_name": "CASHFREE",
            "gateway_order_id": "1580762800",
            "gateway_payment_id": "1453002795",
            "gateway_status_code": null
        },
        "payment_offers": [  
            {  
                "offer_id": "0f05e1d0-fbf8-4c9c-a1f0-814c7b2abdba",  
                "offer_type": "DISCOUNT",  
                "offer_meta": {  
                    "offer_title": "50% off on UPI",  
                    "offer_description": "50% off for testing",  
                    "offer_code": "UPI50",  
                    "offer_start_time": "2022-11-09T06:23:25.972Z",  
                    "offer_end_time": "2023-02-27T18:30:00Z"  
                },  
                "offer_redemption": {  
                    "redemption_status": "SUCCESS",  
                    "discount_amount": 1,  
                    "cashback_amount": 0  
                }  
            }  
        ],
        "terminal_details": {
        "cf_terminal_id": 989876,
        "terminal_phone": "9773769999"
    }
    },
    "event_time": "2023-01-03T11:16:10+05:30",
    "type": "PAYMENT_SUCCESS_WEBHOOK"
}

Payment failed webhook version: (2022-09-01)

The payment failed webhook notifies you when transactions fail and we receive a failed response from the bank.

    "data": {
    "order": {
        "order_id": "CFPay_g47u3888d0k0_tblfm766qc",
        "order_amount": 1.8,
        "order_currency": "INR",
        "order_tags": {
            "cf_link_id": "13746255"
        }
    },
    "payment": {
        "cf_payment_id": 1504280029,
        "payment_status": "FAILED",
        "payment_amount": 1.8,
        "payment_currency": "INR",
        "payment_message": "AMOUNT SHOULD BE WITHIN RANGE BETWEEN 20.00 TO 500000.00.",
        "payment_time": "2023-01-06T20:00:11+05:30",
        "bank_reference": "NA",
        "auth_id": "null",
        "payment_method": {
            "netbanking": {
                "channel": null,
                "netbanking_bank_code": "3054",
                "netbanking_bank_name": "UCO Bank"
            }
        },
        "payment_group": "net_banking"
    },
    "customer_details": {
        "customer_name": null,
        "customer_id": null,
        "customer_email": null,
        "customer_phone": "9611199227"
    },
    "error_details": {
        "error_code": "GATEWAY_ERROR",
        "error_description": "AMOUNT SHOULD BE WITHIN RANGE BETWEEN 20.00 TO 500000.00. for this bank",
        "error_reason": "invalid_amount",
        "error_source": "cashfree"
    },
    "payment_gateway_details": {
        "gateway_name": "CASHFREE",
        "gateway_order_id": "1634766330",
        "gateway_payment_id": "1504280029",
        "gateway_status_code": null
    },
    "payment_offers": null,
    "terminal_details": {
        "cf_terminal_id": 989876,
        "terminal_phone": "9773769999"
    }
},
"event_time": "2023-01-06T20:00:12+05:30",
"type": "PAYMENT_FAILED_WEBHOOK"
}

User dropped webhook version: (2022-09-01)

The User Dropped Webhook notifies you when customers drop out of the payment flow without completing the transaction. It will help you understand if customers attempted to pay or not. Some common scenarios where the transaction will be marked as USER_DROPPED are:

Android UPI Intent Payments - when a user clicks on the back button in the UPI app without making any payment attempt.
Card Payments - when a user drops out of the payment flow by closing the OTP verification page.
UPI Collect Transactions - when a user does not enter the UPI PIN and closes the transaction screen

    "data": {
        "order": {
            "order_id": "testspos83",
            "order_amount": 1.00,
            "order_currency": "INR",
            "order_tags": null
        },
        "payment": {
            "cf_payment_id": 2150264295,
            "payment_status": "USER_DROPPED",
            "payment_amount": 1.00,
            "payment_currency": "INR",
            "payment_message": null,
            "payment_time": "2023-11-03T12:37:32+05:30",
            "bank_reference": null,
            "auth_id": null,
            "payment_method": {
                "upi": {
                    "channel": null,
                    "upi_id": "testsuccess@gocash"
                }
            },
            "payment_group": "upi"
        },
        "customer_details": {
            "customer_name": "johndoe",
            "customer_id": "9112",
            "customer_email": "[johndoe@cashfree.com]()",
            "customer_phone": "9876543210"
        },
        "payment_gateway_details": {
            "gateway_name": null,
            "gateway_order_id": null,
            "gateway_payment_id": null,
            "gateway_status_code": null,
            "gateway_settlement": null
        },
        "payment_offers": null,
        "terminal_details": {
            "cf_terminal_id": 20532321,
            "terminal_phone": "9876543210"
        }
    },
    "event_time": "2023-11-03T12:37:44+05:30",
    "type": "PAYMENT_USER_DROPPED_WEBHOOK"
}

Refund webhook version: (2022-09-01)

Refund webhooks can be configured to receive automated notifications for refunds when either they are successfully processed or are cancelled. Merchants can build their own downstream systems like auto-updating their refund status, and sending a communication to customers by consuming refund webhooks. The webhook notification will be sent on all the URLs added and enabled under the refund webhook. Merchants can add new URLs and enable or disable existing URLs for refund webhook at any point in time and it will be reflected instantaneously.

Sample payload

{
 "data": {
    "refund": {
        "cf_refund_id": 11325632,
        "cf_payment_id": 789727431,
        "refund_id": "refund_sampleorder0413",
        "order_id": "sampleorder0413",
        "refund_amount": 2.00,
        "refund_currency": "INR",
        "entity": "Refund",
        "refund_type": "MERCHANT_INITIATED",
        "refund_arn": "205907014017",
        "refund_status": "SUCCESS",
        "status_description": "Refund processed successfully",
        "created_at": "2022-02-28T12:54:25+05:30",
        "processed_at": "2022-02-28T13:04:27+05:30",
        "refund_charge": 0,
        "refund_note": "Test",
        "refund_splits": [  
            {  
                "merchantVendorId": "sampleID12345",  
                "amount": 1,  
                "percentage": null  
            },  
            {  
                "merchantVendorId": "otherVendor",  
                "amount": 1,  
                "percentage": null  
            }  
        ],
        "metadata": null,
        "refund_mode": "STANDARD",
        "terminal_details": {
            "cf_terminal_id": 911876,
            "terminal_phone": "9876543210"
        }
    }
},
"event_time": "2022-02-28T13:04:28+05:30",
"type": "REFUND_STATUS_WEBHOOK"
}

Payload field description

Field	Description	Example
cf_refund_id	Cashfree Payments ID for a refund.	11325632
cf_payment_id	Cashfree Payments ID of the payment for which refund is initiated.	789727431
cf_terminal_id	Cashfree Payments Terminal ID of the payment for which refund is initiated.	21345
terminal_phone	The phone number of the corresponding terminal.	9876543212
refund_id	Merchant’s refund ID of the refund	refund_sampleorder0413
order_id	Merchant’s order Id of the order for which refund is initiated.	sampleorder0413
refund_amount	Amount that was refunded	2.00
refund_currency	Currency of the refund amount.	INR
entity	Type of object (refund always)	Refund
refund_type	Type of refund (for webhook it will always be MERCHANT_INITIATED)	MERCHANT_INITIATED
refund_arn	The bank reference number for refund	205907014017
refund_status	Status of the refund (either SUCCESS or CANCELLED in refund webhook)	SUCCESS
status_description	Description of refund status	Refund processed successfully
created_at	Time of refund creation	2022-02-28T12:54:25+05:30
processed_at	Time when refund was processed successfully	2022-02-28T13:04:27+05:30
refund_charge	Charges in INR for processing refund	0
refund_note	Note added by merchant for the refund	Cancelled Order
refund_splits	Refund split details	[]
metadata	Additional refund metadata	null
refund_mode	Method or speed of processing refund (INSTANT or STANDARD)	STANDARD
event_time	Time at which refund webhook was initiated.	2022-02-28T13:04:28+05:30
type	Type of webhook. REFUND_STATUS_WEBHOOK always	REFUND_STATUS_WEBHOOK

Auto refund webhook version: (2022-09-01)

Auto-refund webhooks can be configured to receive automated notifications when auto-refunds are initiated, processed and delayed. Auto-refunds are refunds triggered automatically for unsuccessful payments, disputes, duplicate payments; or instances where payments are received directly to your VPA, regardless of whether an order has been generated. Cashfree Payments sends webhook notifications to every URL added and enabled under Auto-refund Webhooks. You can add new URLs and enable or disable existing ones for auto-refund webhooks at any point in time. The changes take effect immediately.

Sample payload

Auto-Refund Webhook Sample Payload

{
    "data": {
        "auto_refund": {
            "event": "AUTO-REFUND",
            "cf_refund_id": 1243460973,
            "cf_payment_id": "2148333968",
            "bank_reference": "234928698581",
            "order_id": "order_1944392Tpba8y2fHcHVx0SwREojp51Jgr",
            "refund_amount": 39,
            "refund_currency": "INR",
            "refund_type": "PAYMENT_AUTO_REFUND",
            "refund_arn": "205907014017",
            "refund_status": "SUCCESS",
            "status_description": "Auto-Refund processed successfully",
            "refund_reason": "Multiple payments were performed against same order.",
            "created_at": "2023-08-11T14:08:28+05:30",
            "processed_at": null,
            "refund_charge": 0,
            "refund_splits": null,
            "metadata": null
        },
        "terminal_details": {
            "cf_terminal_id": 989876,
            "terminal_phone": "9773769999"
        }
    },
    "event_time": "2023-08-11T14:10:21+05:30",
    "type": "AUTO_REFUND_STATUS_WEBHOOK"
}

Find the description for each field of the payload below:

Field	Description	Example
cf_refund_id	It represents the ID created by Cashfree Payments to identify the refund.	1243460973
cf_payment_id	It represents the ID created by Cashfree Payments to identify the payment for the initiated refund.	2148333968
cf_terminal_id	Cashfree Payments Terminal ID of the payment for which refund is initiated.	21345
terminal_phone	The phone number of the corresponding terminal.	9876543212
order_id	It represents the ID created by you to identify the order for which the refund is initiated.	sampleorder0413
bank_reference	It represents the bank reference number for the transaction.	234928698581
refund_currency	It represents the currency of the refund amount.	INR
refund_amount	It represents the refunded amount.	2
refund_type	It represents the refund type. The value will always be PAYMENT_AUTO_REFUND.	PAYMENT_AUTO_REFUND
refund_arn	It represents the bank reference number for the refund.	205907014017
refund_status	It represents the status of the refund (either SUCCESS or INITIATED).	SUCCESS
status_description	It represents the description of the refund status. (Two possible values: Auto-Refund initiated successfully or Auto-Refund processed successfully).	Auto-Refund initiated successfully
created_at	It represents the time of auto-refund creation.	2022-02-28T12:54:25+05:30
processed_at	It represents when the auto-refund was processed successfully.	2022-02-28T13:04:27+05:30
refund_reason	It represents the reason of initiation of Auto-refund. (Possible values: Credit was received for an incomplete payment. Refunded to customer for Dispute. Payment made directly to your VPA without order creation. Multiple payments were performed against same order. Payment details (amount, bank, etc.) do not match with created order or the payment was made after TTL.)	Multiple payments were performed against same order
refund_charge	It represents the charges for processing refund in INR.	0
refund_splits	It represents the refund split details.	[]
metadata	It represents the additional metadata.	null
event_time	It represents when the refund webhook was initiated.	2022-02-28T13:04:28+05:30
type	It represents the webhook type. The value will always be AUTO_REFUND_STATUS_WEBHOOK.	AUTO_REFUND_STATUS_WEBHOOK

Dispute webhooks version: (2022-09-01)

Dispute webhooks can be configured to receive automated notifications when disputes are created, updated and closed. The webhook notification will be sent on all the URLs added and enabled under the dispute webhook. Merchants can add new URLs and enable or disable existing URLs for refund webhook at any point in time and it will be reflected instantaneously.

Webhook	Description
DISPUTE_CREATED	Dispute_created webhook will be triggered when a new dispute is created.
DISPUTE_UPDATED	Dispute_updated webhook will be triggered when a dispute is updated, for example when a comment is added by the Cashfree team, when the dispute moves into further stages like Pre-arbitration, Arbitration, or when the status of the dispute changes.
DISPUTE_CLOSED	This webhook will be triggered when a dispute is closed.

Dispute created

Sample Payload

    "data": {
        "dispute": {
            "dispute_id": "433475258",
            "dispute_type": "DISPUTE",
            "reason_code": "1402",
            "reason_description": "Duplicate Processing",
            "dispute_amount": 3,
            "created_at": "2023-06-15T21:49:48+05:30",
            "updated_at": "2023-06-15T21:49:48+05:30",
            "respond_by": "2023-06-18T23:59:59+05:30",
            "dispute_status": "DISPUTE_CREATED",
            "cf_dispute_remarks": "Dispute is created, please take action",
            "dispute_action_on": "MERCHANT"
        },
        "order_details": {
            "order_id": "order_1944392DR1kMTFYdIf8bI2awAcC3i9FTa",
            "order_amount": 3,
            "order_currency": "INR",
            "cf_payment_id": 885473311,
            "payment_amount": 3,
            "payment_currency": "INR"
        },
        "customer_details": {
            "customer_name": "Dileep Kumar s",
            "customer_phone": "8000000000",
            "customer_email": "dileep@gmail.com"
        },
        "terminal_details": {
            "cf_terminal_id": 989876,
            "terminal_phone": "9876543212"
        }
    },
    "event_time": "2023-06-15T21: 50: 04+05: 30",
    "type": "DISPUTE_CREATED"
}

Dispute updated

Sample Payload

    "data": {
        "dispute": {
            "dispute_id": "433475257",
            "dispute_type": "PRE_ARBITRATION",
            "reason_code": "13.1",
            "reason_description": "Merchandise / Services Not Received",
            "dispute_amount": 40000,
            "created_at": "2023-06-15T21:16:03+05:30",
            "updated_at": "2023-06-15T21:19:15+05:30",
            "respond_by": "2023-06-19T23:59:59+05:30",
            "dispute_status": "PRE_ARBITRATION_CREATED",
            "cf_dispute_remarks": "Pre Arbitration request has been raised for this case.\\nTarget Date :: 2023-06-18T00:00 -> 2023-06-19T23:59:59.",
            "dispute_update": "TYPE_UPDATE",
            "dispute_action_on": "MERCHANT"
        },
        "order_details": {
            "order_id": "order_1944392D4jHtCeVPPdTXkaUwg5cfnujQe",
            "order_amount": 40000,
            "order_currency": "INR",
            "cf_payment_id": 885457437,
            "payment_amount": 40000,
            "payment_currency": "INR"
        },
        "customer_details": {
            "customer_name": "Dileep Kumar s",
            "customer_phone": "8000000000",
            "customer_email": "dileep@gmail.com"
        },
        "terminal_details": {
            "cf_terminal_id": 989876,
            "terminal_phone": "9876543212"
        }
    },
    "event_time": "2023-06-15T21:20:24+05:30",
    "type": "DISPUTE_UPDATED"
}

Dispute closed

Sample Payload

    "data": {
        "dispute": {
            "dispute_id": "433475257",
            "dispute_type": "CHARGEBACK",
            "reason_code": "4855",
            "reason_description": "Goods or Services Not Provided",
            "dispute_amount": 4500,
            "created_at": "2023-06-15T21:16:03+05:30",
            "updated_at": "2023-06-15T21:16:51+05:30",
            "respond_by": "2023-06-18T00:00:00+05:30",
            "resolved_at": "2023-06-15T21:16:51.682836678+05:30",
            "dispute_status": "CHARGEBACK_MERCHANT_WON",
            "cf_dispute_remarks": "Chargeback won by merchant"
        },
        "order_details": {
            "order_id": "order_1944392D4jHtCeVPPdTXkaUwg5cfnujQe",
            "order_amount": 4500,
            "order_currency": "INR",
            "cf_payment_id": 885457437,
            "payment_amount": 4500,
            "payment_currency": "INR"
        },
        "customer_details": {
            "customer_name": "Dileep Kumar s",
            "customer_phone": "8000000000",
            "customer_email": "dileep@gmail.com"
        },
        "terminal_details": {
            "cf_terminal_id": 989876,
            "terminal_phone": "9876543212"
        }
    },
    "event_time": "2023-06-15T21:17:14+05:30",
    "type": "DISPUTE_CLOSED"
}

Payload field description

Field	Description	Example	Type
dispute_id	Cashfree’s unique ID to identify a dispute.	433475257	Long
dispute_type	Type of dispute created. Possible values: - DISPUTE - RETRIEVAL - CHARGEBACK - PRE_ARBITRATION - ARBITRATION	Chargeback	String
cf_terminal_id	Cashfree Payments Terminal ID of the payment for which refund is initiated.	989876	Long
terminal_phone	The phone number of the corresponding terminal.	9876543212	String
reason_code	Condition for which the customer is filing the case. See dispute reason codes to know more.	13.6	String
reason_description	Description of the reason code. Codes for Chargeback cases are specified by Card networks/NPCI.	Credit not processed	String
dispute_amount	The amount for which the dispute has been created.	4500	BigDecimal
created_at	Time on which the dispute was registered on Cashfree’s system.	2023-06-15T21:16:03+05:30	LocalDateTime
updated_at	Time on which the dispute was updated.	2023-06-15T21:16:51+05:30	LocalDateTime
respond_by	Time by which the merchant is expected to respond to the dispute.	2023-06-18T00:00:00+05:30	LocalDateTime
dispute_status	Status of Dispute. All possible values are listed in the table below.	CHARGEBACK_CREATED	String
cf_dispute_remarks	Any remarks specified by Cashfree on the dispute.	Please submit documents.	String
dispute_update	Specifies what has been updated on the dispute. Possible Values: - STATUS_UPDATE - TYPE_UPDATE - COMMENT_UPDATE	TYPE_UPDATE	String
dispute_action_on	Specifies whether the action is on Cashfree or Merchant at a time. Possible Values: - MERCHANT - CASHFREE	MERCHANT	String
resolved_at	Time on which the dispute was resolved/closed.	2023-06-15T21:16:51.682836678+05:30	LocalDateTime
event_time	Time at which dispute webhook was initiated.	2023-06-15T21:16:51+05:30	LocalDateTime
type	Type of webhook. Possible Values: - DISPUTE_CREATED - DISPUTE_UPDATED - DISPUTE_CLOSED	DISPUTE_CREATED	String

Payments API

v2026-01-01

Other Versions

Offline Payments Webhooks

Payment success webhook version: (2022-09-01)

Sample payload

Payment failed webhook version: (2022-09-01)

User dropped webhook version: (2022-09-01)

Refund webhook version: (2022-09-01)

Sample payload

Payload field description

Auto refund webhook version: (2022-09-01)

Sample payload

Dispute webhooks version: (2022-09-01)

Dispute created

Dispute updated

Dispute closed

Payload field description

​Payment success webhook version: (2022-09-01)

​Sample payload

​Payment failed webhook version: (2022-09-01)

​User dropped webhook version: (2022-09-01)

​Refund webhook version: (2022-09-01)

​Sample payload

​Payload field description

​Auto refund webhook version: (2022-09-01)

​Sample payload

​Dispute webhooks version: (2022-09-01)

​Dispute created

​Dispute updated

​Dispute closed

​Payload field description

Payment success webhook version: (2022-09-01)

Sample payload

Payment failed webhook version: (2022-09-01)

User dropped webhook version: (2022-09-01)

Refund webhook version: (2022-09-01)

Sample payload

Payload field description

Auto refund webhook version: (2022-09-01)

Sample payload

Dispute webhooks version: (2022-09-01)

Dispute created

Dispute updated

Dispute closed

Payload field description