> ## 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.

# Implementation Guide

> Use Cashfree UPI Reserve Pay to block funds once on a customer's UPI account and debit multiple times, ideal for EMIs, usage-based billing, and subscriptions.

UPI Reserve Pay uses Single Block Multi Debit (SBMD) to allow you to block a maximum amount once from your customer's account and then debit multiple times against that blocked amount. This feature is ideal for EMIs, usage-based billing, and subscription services.

## Key benefits

* **One-time authorisation**: Customer provides approval once for multiple future debits
* **Flexible charging**: Debit multiple amounts until the blocked limit is reached or the mandate expires
* **Fund management**: Release unused blocked funds back to customers when needed

## Workflow overview

The UPI Reserve Pay SBMD workflow involves the following steps:

1. **Create subscription for mandate setup**
   * You initialise the subscription with customer and plan details
   * Subscription is created in `INITIALISED` state

2. **Raise authorisation to get customer approval**
   * You raise the authorisation request for blocking the amount
   * Customer approves the blocked amount via UPI
   * On success, subscription moves to `ACTIVE` state
   * Cashfree sends `SUBSCRIPTION_AUTH_STATUS` webhook

3. **Raise charge to debit funds**
   * You raise charges against the blocked amount (partial or multiple)
   * Payment is processed and status is sent via webhook:
     * `SUBSCRIPTION_PAYMENT_SUCCESS`
     * `SUBSCRIPTION_PAYMENT_FAILED`

4. **Get mandate details**
   * You fetch all charges and remaining limit using subscription ID

5. **Refund individual charge**
   * You can refund an individual charge
   * Notification of refund status is sent via `SUBSCRIPTION_REFUND_STATUS` webhook

6. **Manage mandate**
   * You can unblock unused debits and release funds back to the customer

## Implementation steps

UPI Reserve Pay extends the [Subscription APIs](/docs/payments/subscription/introduction) with SBMD-specific parameters for fund blocking. Follow these steps to implement the feature:

<Note>All API examples belong to version 2025-01-01.</Note>

### Quick reference

| Step                   | SBMD requirement                                | API reference                                                                                                     |
| :--------------------- | :---------------------------------------------- | :---------------------------------------------------------------------------------------------------------------- |
| 1. Create subscription | Add `"category": "SBMD"` in `subscription_meta` | [Create Subscription API](/docs/api-reference/payments/latest/subscription/create-subscription)                        |
| 2. Raise authorisation | Set `"payment_type": "AUTH"`                    | [Raise Payment API](/docs/api-reference/payments/latest/subscription/raise-a-charge-or-create-an-auth)                 |
| 3. Raise charges       | Set `"payment_type": "CHARGE"`                  | [Raise Payment API](/docs/api-reference/payments/latest/subscription/raise-a-charge-or-create-an-auth)                 |
| 4. Get mandate details | No SBMD-specific changes                        | [Fetch Payments API](/docs/api-reference/payments/latest/subscription/fetch-details-of-all-payments-of-a-subscription) |
| 5. Refund charges      | No SBMD-specific changes                        | [Create Refund API](/docs/api-reference/payments/latest/subscription/create-a-refund)                                  |
| 6. Manage mandate      | Only `CANCEL` action supported                  | [Manage Subscription API](/docs/api-reference/payments/latest/subscription/manage-subscription)                        |

### Step 1: Create subscription

Create a subscription to set up the mandate for blocking funds. UPI Reserve Pay requires setting the subscription category to `SBMD`.

**API Endpoint:** `POST https://api.cashfree.com/pg/subscriptions`

**Sandbox URL:** `https://sandbox.cashfree.com/pg/subscriptions`

<Tip>
  **SBMD-specific requirement**

  Add `"category": "SBMD"` in the `subscription_meta` object to enable fund blocking:

  ```json theme={"dark"}
  {
    "subscription_meta": {
      "return_url": "https://example.com/return",
      "notification_channel": ["EMAIL", "SMS"],
      "category": "SBMD"  // Required for UPI Reserve Pay
    }
  }
  ```

  For complete request parameters and response structure, see [Create Subscription API](/docs/api-reference/payments/latest/subscription/create-subscription).
</Tip>

<Accordion title="View complete SBMD request example">
  ```json Request theme={"dark"}
  {
    "subscription_id": "subscription_001",
    "customer_details": {
      "customer_name": "John Doe",
      "customer_email": "john@example.com",
      "customer_phone": "9799002505",
      "customer_bank_code": "HDFC",
      "customer_bank_account_type": "SAVINGS"
    },
    "plan_details": {
      "plan_name": "plan12345",
      "plan_type": "ON_DEMAND",
      "plan_currency": "INR",
      "plan_max_amount": 1000.00
    },
    "authorization_details": {
      "authorization_amount": 0,
      "authorization_amount_refund": true,
      "payment_methods": ["upi"]
    },
    "subscription_meta": {
      "return_url": "https://bit.ly/4glEd0W",
      "notification_channel": ["EMAIL", "SMS"],
      "category": "SBMD"
    },
    "subscription_expiry_time": "2026-01-01T23:00:08+05:30",
    "subscription_note": "UPI Reserve Pay subscription",
    "subscription_tags": {
      "psp_note": "Fund blocking for recurring payments"
    }
  }
  ```
</Accordion>

After you create the subscription, it will be in the `INITIALISED` state, ready for customer authorisation.

### Step 2: Raise authorisation

Raise an authorisation request for customers to approve the fund blocking. The key requirement for SBMD is setting `payment_type` to `AUTH`.

**API Endpoint:** `POST https://api.cashfree.com/pg/subscriptions/pay`

**Sandbox URL:** `https://sandbox.cashfree.com/pg/subscriptions/pay`

<Tip>
  **SBMD-specific requirement**

  Set `"payment_type": "AUTH"` in your request to initiate the authorisation flow:

  ```json theme={"dark"}
  {
    "subscription_id": "subscription_001",
    "payment_id": "auth_payment_001",
    "payment_remarks": "Fund blocking authorisation",
    "payment_type": "AUTH",  // Required for authorisation
    "payment_method": {
      "upi": {
        "channel": "link"  // Use "link", "qrcode", or "collect"
      }
    }
  }
  ```

  For complete request parameters and response structure, see [Raise Payment API](/docs/api-reference/payments/latest/subscription/raise-a-charge-or-create-an-auth).
</Tip>

<Accordion title="View UPI channel options">
  **Available UPI channels:**

  * `link`: Payment link that redirects to UPI apps
  * `qrcode`: QR code for scanning with UPI apps
  * `collect`: Direct UPI collect request (requires `upi_id`)

  **Example for UPI collect:**

  ```json theme={"dark"}
  {
    "payment_method": {
      "upi": {
        "channel": "collect",
        "upi_id": "john.doe@bank"
      }
    }
  }
  ```
</Accordion>

After the customer completes the authorisation, you'll receive a `SUBSCRIPTION_AUTH_STATUS` webhook notification.

#### SUBSCRIPTION\_AUTH\_STATUS webhook

<Accordion title="Authorisation success notification">
  ```json Webhook Example theme={"dark"}
  {
    "data": {
      "payment_id": "auth_payment_001",
      "cf_payment_id": "49988825",
      "cf_txn_id": "4213159266",
      "cf_order_id": "4519691525",
      "subscription_id": "subscription_001",
      "cf_subscription_id": "23639858",
      "payment_type": "AUTH",
      "authorization_details": {
        "authorization_amount": 1000.00,
        "authorization_amount_refund": false,
        "approve_by_time": "",
        "authorization_reference": "cce92d335be0467693c020xxxxx[at]xxxx",
        "authorization_time": "2025-08-07T10:34:23+05:30",
        "authorization_status": "SUCCESS",
        "payment_id": "auth_payment_001",
        "payment_method": {
          "upi": {
            "channel": "link",
            "upi_id": "9910000000@ybl",
            "upi_instrument": "",
            "upi_instrument_number": "",
            "upi_payer_account_number": "",
            "upi_payer_ifsc": ""
          }
        },
        "payment_group": "upi"
      },
      "payment_amount": 1000.00,
      "payment_currency": "INR",
      "payment_schedule_date": "",
      "payment_initiated_date": "2025-08-07T10:33:56+05:30",
      "payment_remarks": "Authorisation request",
      "retry_attempts": 0,
      "payment_status": "SUCCESS",
      "payment_gateway_details": {
        "gateway_name": "CASHFREE",
        "gateway_subscription_id": "23639858",
        "gateway_payment_id": "49988825"
      }
    },
    "event_time": "2025-08-07T10:34:23+05:30",
    "type": "SUBSCRIPTION_AUTH_STATUS"
  }
  ```
</Accordion>

### Step 3: Raise charges

After successful authorisation, you can debit amounts from the blocked funds. Set `payment_type` to `CHARGE` for debit requests.

**API Endpoint:** `POST https://api.cashfree.com/pg/subscriptions/pay`

**Sandbox URL:** `https://sandbox.cashfree.com/pg/subscriptions/pay`

<Tip>
  **SBMD-specific requirement**

  Set `"payment_type": "CHARGE"` to debit from blocked funds:

  ```json theme={"dark"}
  {
    "subscription_id": "subscription_001",
    "payment_id": "charge_payment_001",
    "payment_amount": 100,
    "payment_schedule_date": "2025-09-26T12:40:12+05:30",
    "payment_remarks": "Monthly charge",
    "payment_type": "CHARGE"  // Required for debiting
  }
  ```

  For complete request parameters and response structure, see [Raise Payment API](/docs/api-reference/payments/latest/subscription/raise-a-charge-or-create-an-auth).
</Tip>

You'll receive webhook notifications for each charge attempt:

#### SUBSCRIPTION\_PAYMENT\_SUCCESS webhook

<Accordion title="Charge success notification">
  ```json Webhook Example theme={"dark"}
  {
    "data": {
      "payment_id": "charge_payment_001",
      "cf_payment_id": "49914526",
      "cf_txn_id": "4212435861",
      "cf_order_id": "4518936510",
      "subscription_id": "subscription_001",
      "cf_subscription_id": "23601811",
      "payment_type": "CHARGE",
      "authorization_details": {
        "authorization_amount": 1000.00,
        "authorization_amount_refund": false,
        "approve_by_time": "",
        "authorization_reference": "427b608f83ad4cbdb6d472xxxxx[at]xxxx",
        "authorization_time": "2025-08-07T05:53:22+05:30",
        "authorization_status": "ACTIVE",
        "payment_id": "charge_payment_001",
        "payment_method": {
          "upi": {
            "channel": "link",
            "upi_id": "8100000000@ybl",
            "upi_instrument": "",
            "upi_instrument_number": "",
            "upi_payer_account_number": "",
            "upi_payer_ifsc": ""
          }
        },
        "payment_group": "upi"
      },
      "payment_amount": 100.00,
      "payment_currency": "INR",
      "payment_schedule_date": "",
      "payment_initiated_date": "2025-08-07T05:52:21+05:30",
      "payment_remarks": "Monthly subscription charge",
      "retry_attempts": 0,
      "failure_details": {
        "failure_reason": null
      },
      "payment_status": "SUCCESS",
      "payment_gateway_details": {
        "gateway_name": "CASHFREE",
        "gateway_subscription_id": "23601811",
        "gateway_payment_id": "49914526"
      }
    },
    "event_time": "2025-08-07T05:53:21+05:30",
    "type": "SUBSCRIPTION_PAYMENT_SUCCESS"
  }
  ```
</Accordion>

#### SUBSCRIPTION\_PAYMENT\_FAILED webhook

<Accordion title="Charge failure notification">
  ```json Webhook Example theme={"dark"}
  {
    "data": {
      "payment_id": "charge_payment_002",
      "cf_payment_id": "49585655",
      "cf_txn_id": "4212555720",
      "cf_order_id": "4519061918",
      "subscription_id": "subscription_001",
      "cf_subscription_id": "22393526",
      "payment_type": "CHARGE",
      "authorization_details": {
        "authorization_amount": 1000.00,
        "authorization_amount_refund": false,
        "approve_by_time": "",
        "authorization_reference": "a7d6101a7d9340269f070dxxxxx[at]xxxx",
        "authorization_time": "2025-07-25T22:37:53+05:30",
        "authorization_status": "ACTIVE",
        "payment_id": "charge_payment_002",
        "payment_method": {
          "upi": {
            "channel": "link",
            "upi_id": "9910000000@ybl",
            "upi_instrument": "",
            "upi_instrument_number": "",
            "upi_payer_account_number": "",
            "upi_payer_ifsc": ""
          }
        },
        "payment_group": "upi"
      },
      "payment_amount": 500.00,
      "payment_currency": "INR",
      "payment_schedule_date": "2025-08-07T12:00:00+05:30",
      "payment_initiated_date": "2025-08-06T05:02:41+05:30",
      "payment_remarks": null,
      "retry_attempts": 0,
      "failure_details": {
        "failure_reason": "DEBIT FAILED | Insufficient Funds In Customer (Remitter) Account"
      },
      "payment_status": "FAILED",
      "payment_gateway_details": {
        "gateway_name": "CASHFREE",
        "gateway_subscription_id": "22393526",
        "gateway_payment_id": "49585655"
      }
    },
    "event_time": "2025-08-07T10:24:45+05:30",
    "type": "SUBSCRIPTION_PAYMENT_FAILED"
  }
  ```
</Accordion>

### Step 4: Get mandate details

Retrieve information about all payments made against a subscription and the remaining blocked amount.

**API Endpoint:** `GET https://api.cashfree.com/pg/subscriptions/{subscription_id}/payments`

**Sandbox URL:** `https://sandbox.cashfree.com/pg/subscriptions/{subscription_id}/payments`

<Note>
  SBMD subscriptions use the same API as regular subscriptions. For complete response structure and parameters, see [Fetch Payments API](/docs/api-reference/payments/latest/subscription/fetch-details-of-all-payments-of-a-subscription).

  To get individual payment details, use [Fetch Payment API](/docs/api-reference/payments/latest/subscription/fetch-details-of-a-single-payment).
</Note>

### Step 5: Refund individual charges

Refund specific charges using the subscription refund APIs. SBMD refunds work the same as regular subscription refunds.

**Create Refund:** `POST https://api.cashfree.com/pg/subscriptions/{subscription_id}/refunds`

**Sandbox URL:** `https://sandbox.cashfree.com/pg/subscriptions/{subscription_id}/refunds`

**Get Refund Status:** `GET https://api.cashfree.com/pg/subscriptions/{subscription_id}/refunds/{refund_id}`

**Sandbox URL:** `https://sandbox.cashfree.com/pg/subscriptions/{subscription_id}/refunds/{refund_id}`

<Note>
  For complete API documentation and examples, see:

  * [Create Refund API](/docs/api-reference/payments/latest/subscription/create-a-refund)
  * [Get Refund API](/docs/api-reference/payments/latest/subscription/fetch-details-of-a-refund)
</Note>

### Step 6: Manage mandate

Release unused blocked funds back to the customer using the manage subscription API.

**API Endpoint:** `POST https://api.cashfree.com/pg/subscriptions/{subscription_id}/manage`

**Sandbox URL:** `https://sandbox.cashfree.com/pg/subscriptions/{subscription_id}/manage`

<Warning>
  **SBMD limitation**

  Only the `CANCEL` action is supported for SBMD subscriptions. Other management actions like `PAUSE` are not available.

  ```json theme={"dark"}
  {
    "subscription_id": "subscription_001",
    "action": "CANCEL"
  }
  ```

  For complete API documentation, see [Manage Subscription API](/docs/api-reference/payments/latest/subscription/manage-subscription).
</Warning>

## Subscription webhooks

Cashfree sends webhook notifications for various subscription events during the SBMD lifecycle.

### SUBSCRIPTION\_STATUS\_CHANGED

This webhook is sent when a subscription's status changes during the lifecycle.

<Accordion title="Subscription status change notification">
  ```json Webhook Example theme={"dark"}
  {
    "data": {
      "subscription_details": {
        "cf_subscription_id": "23639356",
        "subscription_id": "subscription_001",
        "subscription_status": "BANK_APPROVAL_PENDING",
        "subscription_expiry_time": "2055-08-07T10:30:46",
        "subscription_first_charge_time": null,
        "subscription_tags": null,
        "next_schedule_date": null
      },
      "customer_details": {
        "customer_name": null,
        "customer_email": "john@example.com",
        "customer_phone": "9900000000"
      },
      "plan_details": {
        "plan_id": "subscription_001",
        "plan_name": "6Msuj2mttuf2F5P1FYVSet",
        "plan_type": "ON_DEMAND",
        "plan_max_cycles": 0,
        "plan_recurring_amount": null,
        "plan_max_amount": 1000.00,
        "plan_interval_type": null,
        "plan_intervals": null,
        "plan_currency": "INR",
        "plan_note": null,
        "plan_status": null
      },
      "authorization_details": {
        "authorization_amount": 1000.00,
        "authorization_amount_refund": false,
        "approve_by_time": "2025-09-06T10:30:47",
        "authorization_reference": "6ba74ac2b047424da95591xxxxx[at]xxxx",
        "authorization_time": "2025-08-07T10:31:36",
        "authorization_status": "PENDING",
        "payment_id": "49988270",
        "payment_method": {
          "upi": {
            "channel": "link",
            "upi_id": "9910000000@ybl",
            "upi_instrument": "",
            "upi_instrument_number": "",
            "upi_payer_account_number": "",
            "upi_payer_ifsc": ""
          }
        },
        "payment_group": "upi"
      },
      "payment_gateway_details": {
        "gateway_name": "CASHFREE",
        "gateway_subscription_id": "23639356",
        "gateway_plan_id": "subscription_001",
        "gateway_auth_id": "6ba74ac2b047424da95591xxxxx[at]xxxx"
      }
    },
    "event_time": "2025-08-07T10:31:35+05:30",
    "type": "SUBSCRIPTION_STATUS_CHANGED"
  }
  ```
</Accordion>

<snippet>snippets/related-topics-loader.mdx</snippet>

<div class="hidden" data-table-of-contents="bottom">
  <p class="mt-4 font-medium flex items-center gap-2 related-docs-heading">
    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" class="w-4 h-4">
      <path d="M3 4h7a2 2 0 0 1 2 2v13a2 2 0 0 0-2-2H3z" />

      <path d="M21 4h-7a2 2 0 0 0-2 2v13a2 2 0 0 1 2-2h7z" />
    </svg>

    <span>Related topics</span>
  </p>

  <ul>
    <li><a href="/docs/api-reference/payments/latest/subscription/create-subscription">Create Subscription API</a></li>
    <li><a href="/docs/api-reference/payments/latest/subscription/raise-a-charge-or-create-an-auth">Raise Payment API</a></li>
    <li><a href="/docs/api-reference/payments/latest/subscription/create-a-refund">Create Refund API</a></li>
    <li><a href="/docs/payments/subscription/introduction">Subscriptions Overview</a></li>
  </ul>
</div>