> ## Documentation Index
> Fetch the complete documentation index at: https://www.cashfree.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscription Webhooks

> Subscribe to Cashfree Subscription webhooks so your server reacts whenever a mandate is authorised, a charge succeeds, or a refund is processed.

Below are the various events that can be sent to your webhook endpoint. These webhooks will be triggered if the merchant has integrated our newer Subscription API.

<Note>
  If the merchant added the webhook under the 2023-08-01 version, they will receive the same version of the webhook for older subscriptions as well.
</Note>

* `SUBSCRIPTION_STATUS_CHANGE`
* `SUBSCRIPTION_AUTH_STATUS`
* `SUBSCRIPTION_PAYMENT_NOTIFICATION_INITIATED`
* `SUBSCRIPTION_PAYMENT_SUCCESS`
* `SUBSCRIPTION_PAYMENT_FAILED`
* `SUBSCRIPTION_PAYMENT_CANCELLED`
* `SUBSCRIPTION_REFUND_STATUS`

## `SUBSCRIPTION_STATUS_CHANGE`

Whenever a subscription is created it goes to initialised state and customer is expected to authorise it. The list of statuses where this webhook will get triggered are:

* ACTIVE
* ON\_HOLD
* COMPLETED
* CUSTOMER\_CANCELLED
* CUSTOMER\_PAUSED
* EXPIRED
* LINK\_EXPIRED
* BANK\_APPROVAL\_PENDING

<Accordion title="SUBSCRIPTION_STATUS_CHANGE Event Payload">
  ```javascript theme={"dark"}
  {
      "data": {
          "subscription_details": {
              "cf_subscription_id": "123456",
              "subscription_id": "Demo_Subscription",
              "subscription_status": "ACTIVE",
              "subscription_expiry_time": "2024-01-14T23:00:08+05:30",
              "subscription_first_charge_time": "2024-01-10T23:00:08+05:30"
          },
          "customer_details": {
              "customer_name": "john",
              "customer_email": "john@dummy.com",
              "customer_phone": "9908730221"
          },
          "plan_details": {
              "plan_id": "plan12345",
              "plan_name": "Plan Name",
              "plan_type": "ON_DEMAND",
              "plan_max_cycles": 10,
              "plan_recurring_amount": 100.00,
              "plan_max_amount": 1000.00,
              "plan_currency": "INR",
              "plan_note": "Note",
              "plan_status": "ACTIVE"
          },
          "authorization_details": {
              "authorizationAmount": 100,
              "authorizationAmountRefund": true,
              "approveByTime": "2022-02-09T18:04:34+05:30",
              "authorizationReference": "6595231908096894505959",
              "authorizationTime": "2022-08-03T16:09:51",
              "authorizationStatus": "SUCCESS",
              "paymentId": "123",
              "paymentMethod": "DEBIT_CARD",
              "instrumentId": "hsdg9"
          },
          "payment_gateway_details": {
              "gateway_name": "CASHFREE",
              "gateway_subscription_id": "Demo_Subscription",
              "gateway_plan_id": "plan12345",
              "gateway_auth_id": "6595231908096894505959"
          }
      },
      "event_time": "2023-01-03T11:16:10+05:30",
      "type": "SUBSCRIPTION_STATUS_CHANGE"
  }
  ```
</Accordion>

## SUBSCRIPTION\_AUTH\_STATUS

The event is triggered when the checkout is completed by the customer for success and failed cases.

<Accordion title="SUBSCRIPTION_STATUS_CHANGE Event Payload">
  ```javascript theme={"dark"}
  {
      "data": {
          "payment_id": "12345",
          "cf_payment_id": "67890",
          "cf_txn_id": "789012",
          "cf_order_id": 98765,
          "subscription_id": "sub12345",
          "cf_subscription_id": "sub67890",
          "payment_type": "DEBIT_CARD",
          "authorization_details": {
              "authorization_amount": 100,
              "authorization_amount_refund": true,
              "approve_by_time": "2024-07-20T16:09:50+05:30",
              "authorization_reference": "6595231908096894505959",
              "authorization_time": "2024-07-20T16:09:51",
              "authorization_status": "ACTIVE",
              "payment_id": "123",
              "payment_method": "DEBIT_CARD",
              "instrument_id": "hsdg9"
          },
          "payment_amount": 200.75,
          "payment_schedule_date": "2024-07-20",
          "payment_initiated_date": "2024-07-20",
          "payment_remarks": "auth payment",
          "retry_attempts": 0,
          "failureDetails": null,
          "payment_status": "SUCCESS",
          "payment_gateway_details": {
              "gateway_name": "CASHFREE",
              "gateway_subscription_id": "Demo_Subscription",
              "gateway_payment_id": "payment12345"
          }
      },
      "event_time": "2024-07-20T11:16:10+05:30",
      "type": "SUBSCRIPTION_AUTH_STATUS"
  }
  ```
</Accordion>

## SUBSCRIPTION\_PAYMENT\_NOTIFICATION\_INITIATED

This webhook is used to inform the merchant that we have sent a notification of payment to the customer.

<Accordion title="SUBSCRIPTION_PAYMENT_NOTIFICATION_INITIATED event payload">
  ```javascript theme={"dark"}
  {
      "data": {
          "payment_id": "12345",
          "cf_payment_id": "67890",
          "cf_txn_id": "789012",
          "cf_order_id": 98765,
          "subscription_id": "sub12345",
          "cf_subscription_id": "sub67890",
          "payment_type": "DEBIT_CARD",
          "authorization_details": {
              "authorization_amount": 100,
              "authorization_amount_refund": true,
              "approve_by_time": "2024-07-20T16:09:50+05:30",
              "authorization_reference": "6595231908096894505959",
              "authorization_time": "2024-07-20T16:09:51",
              "authorization_status": "PENDING",
              "payment_id": "123",
              "payment_method": "DEBIT_CARD",
              "instrument_id": "hsdg9"
          },
          "payment_amount": 200,
          "payment_schedule_date": "2024-07-20",
          "payment_initiated_date": "2024-07-20",
          "payment_remarks": "payment",
          "retry_attempts": 0,
          "failureDetails": null,
          "payment_status": "INITIALIZED",
          "payment_gateway_details": {
              "gateway_name": "CASHFREE",
              "gateway_subscription_id": "Demo_Subscription",
              "gateway_payment_id": "payment12345"
          }
      },
      "event_time": "2024-07-20T11:16:10+05:30",
      "type": "SUBSCRIPTION_PAYMENT_NOTIFICATION_INITIATED"
  }
  ```
</Accordion>

## SUBSCRIPTION\_PAYMENT\_SUCCESS

This notification is sent whenever a successful payment is processed for an active subscription.

<Accordion title="SUBSCRIPTION_PAYMENT_SUCCESS event payload">
  ```javascript theme={"dark"}
  {
      "data": {
          "payment_id": "12345",
          "cf_payment_id": "67890",
          "cf_txn_id": "789012",
          "cf_order_id": 98765,
          "subscription_id": "sub12345",
          "cf_subscription_id": "sub67890",
          "payment_type": "DEBIT_CARD",
          "authorization_details": {
              "authorization_amount": 100,
              "authorization_amount_refund": true,
              "approve_by_time": "2024-07-20T16:09:50+05:30",
              "authorization_reference": "6595231908096894505959",
              "authorization_time": "2024-07-20T16:09:51",
              "authorization_status": "ACTIVE",
              "payment_id": "123",
              "payment_method": "DEBIT_CARD",
              "instrument_id": "hsdg9"
          },
          "payment_amount": 200,
          "payment_schedule_date": "2024-07-20",
          "payment_initiated_date": "2024-07-20",
          "payment_remarks": "payment",
          "retry_attempts": 0,
          "failureDetails": null,
          "payment_status": "SUCCESS",
          "payment_gateway_details": {
              "gateway_name": "CASHFREE",
              "gateway_subscription_id": "Demo_Subscription",
              "gateway_payment_id": "payment12345"
          }
      },
      "event_time": "2024-07-20T11:16:10+05:30",
      "type": "SUBSCRIPTION_PAYMENT_SUCCESS"
  }
  ```
</Accordion>

## SUBSCRIPTION\_PAYMENT\_FAILED

This notification is sent whenever payment processing fails for an active subscription.

<Accordion title="SUBSCRIPTION_PAYMENT_FAILED event payload">
  ```javascript theme={"dark"}
  {
      "data": {
          "payment_id": "12345",
          "cf_payment_id": "67890",
          "cf_txn_id": "789012",
          "cf_order_id": 98765,
          "subscription_id": "sub12345",
          "cf_subscription_id": "sub67890",
          "payment_type": "DEBIT_CARD",
          "authorization_details": {
              "authorization_amount": 100,
              "authorization_amount_refund": true,
              "approve_by_time": "2024-07-18T16:09:50+05:30",
              "authorization_reference": "6595231908096894505959",
              "authorization_time": "2024-07-18T16:09:51",
              "authorization_status": "ACTIVE",
              "payment_id": "123",
              "payment_method": "DEBIT_CARD",
              "instrument_id": "hsdg9"
          },
          "payment_amount": 200,
          "payment_schedule_date": "2024-07-20",
          "payment_initiated_date": "2024-07-20",
          "payment_remarks": "payment",
          "retry_attempts": 0,
          "failureDetails": {
              "failureReason": "Insufficient balance"
          },
          "payment_status": "FAILED",
          "payment_gateway_details": {
              "gateway_name": "CASHFREE",
              "gateway_subscription_id": "Demo_Subscription",
              "gateway_payment_id": "payment12345"
          }
      },
      "event_time": "2024-07-20T11:16:10+05:30",
      "type": "SUBSCRIPTION_PAYMENT_FAILED"
  }
  ```
</Accordion>

## SUBSCRIPTION\_PAYMENT\_CANCELLED

This notification is sent whenever payment processing is cancelled by user for an active subscription.

<Accordion title="SUBSCRIPTION_PAYMENT_CANCELLED event payload">
  ```javascript theme={"dark"}
  {
      "data": {
          "payment_id": "12345",
          "cf_payment_id": "67890",
          "cf_txn_id": "789012",
          "cf_order_id": 98765,
          "subscription_id": "sub12345",
          "cf_subscription_id": "sub67890",
          "payment_type": "DEBIT_CARD",
          "authorization_details": {
              "authorization_amount": 100,
              "authorization_amount_refund": true,
              "approve_by_time": "2024-07-18T16:09:50+05:30",
              "authorization_reference": "6595231908096894505959",
              "authorization_time": "2024-07-18T16:09:51",
              "authorization_status": "ACTIVE",
              "payment_id": "123",
              "payment_method": "DEBIT_CARD",
              "instrument_id": "hsdg9"
          },
          "payment_amount": 200,
          "payment_schedule_date": "2024-07-20",
          "payment_initiated_date": "2024-07-20",
          "payment_remarks": "payment",
          "retry_attempts": 0,
          "failureDetails": {
              "failureReason": "Subscription is not active"
          },
          "payment_status": "CANCELLED",
          "payment_gateway_details": {
              "gateway_name": "CASHFREE",
              "gateway_subscription_id": "Demo_Subscription",
              "gateway_payment_id": "payment12345"
          }
      },
      "event_time": "2024-07-20T11:16:10+05:30",
      "type": "SUBSCRIPTION_PAYMENT_CANCELLED"
  }
  ```
</Accordion>

## SUBSCRIPTION\_REFUND\_STATUS

This event is triggered whenever a refund status of a transaction will be success, failed, or cancelled.

<Accordion title="SUBSCRIPTION_REFUND_STATUS event payload">
  ```javascript theme={"dark"}
  {
      "data": {
          "payment_id": "pay8643",
          "cf_payment_id": "863782648",
          "refund_id": "refund2",
          "cf_refund_id": "ref_212",
          "refund_amount": 100,
          "refund_note": "test",
          "refund_speed": "INSTANT",
          "refund_status": "SUCCESS",
          "failure_details": null,
          "payment_gateway_details": {
              "gateway_name": "CASHFREE",
              "gateway_payment_id": "pay8643",
              "gateway_refund_id": "refund2"
          }
      },
      "event_time": "2023-01-03T11:16:10+05:30",
      "type": "SUBSCRIPTION_REFUND_STATUS"
  }
  ```
</Accordion>