UPI Reserve Pay Guide

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:

Create subscription for mandate setup
- You initialise the subscription with customer and plan details
- Subscription is created in INITIALISED state
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
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
Get mandate details
- You fetch all charges and remaining limit using subscription ID
Refund individual charge
- You can refund an individual charge
- Notification of refund status is sent via SUBSCRIPTION_REFUND_STATUS webhook
Manage mandate
- You can unblock unused debits and release funds back to the customer

Implementation steps

UPI Reserve Pay extends the Subscription APIs with SBMD-specific parameters for fund blocking. Follow these steps to implement the feature:

All API examples belong to version 2025-01-01.

Quick reference

Step	SBMD requirement	API reference
1. Create subscription	Add `"category": "SBMD"` in `subscription_meta`	Create Subscription API
2. Raise authorisation	Set `"payment_type": "AUTH"`	Raise Payment API
3. Raise charges	Set `"payment_type": "CHARGE"`	Raise Payment API
4. Get mandate details	No SBMD-specific changes	Fetch Payments API
5. Refund charges	No SBMD-specific changes	Create Refund API
6. Manage mandate	Only `CANCEL` action supported	Manage Subscription API

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

SBMD-specific requirementAdd "category": "SBMD" in the subscription_meta object to enable fund blocking:

{
  "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.

View complete SBMD request example

Request

{
  "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"
  }
}

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

SBMD-specific requirementSet "payment_type": "AUTH" in your request to initiate the authorisation flow:

{
  "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.

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:

{
  "payment_method": {
    "upi": {
      "channel": "collect",
      "upi_id": "john.doe@bank"
    }
  }
}

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

SUBSCRIPTION_AUTH_STATUS webhook

Authorisation success notification

Webhook Example

{
  "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"
}

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

SBMD-specific requirementSet "payment_type": "CHARGE" to debit from blocked funds:

{
  "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.

You’ll receive webhook notifications for each charge attempt:

SUBSCRIPTION_PAYMENT_SUCCESS webhook

Charge success notification

Webhook Example

{
  "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"
}

SUBSCRIPTION_PAYMENT_FAILED webhook

Charge failure notification

Webhook Example

{
  "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"
}

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

SBMD subscriptions use the same API as regular subscriptions. For complete response structure and parameters, see Fetch Payments API.To get individual payment details, use Fetch Payment API.

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}

For complete API documentation and examples, see:

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

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

{
  "subscription_id": "subscription_001",
  "action": "CANCEL"
}

For complete API documentation, see Manage Subscription API.

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.

Subscription status change notification

Webhook Example

{
  "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"
}

Payments

Payment Gateway

Checkout

International Payments

Flowwise

RiskShield

Subscription

Other Products

Developer updates

Implementation Guide

Key benefits

Workflow overview

Implementation steps

Quick reference

Step 1: Create subscription

Step 2: Raise authorisation

SUBSCRIPTION_AUTH_STATUS webhook

Step 3: Raise charges

SUBSCRIPTION_PAYMENT_SUCCESS webhook

SUBSCRIPTION_PAYMENT_FAILED webhook

Step 4: Get mandate details

Step 5: Refund individual charges

Step 6: Manage mandate

Subscription webhooks

SUBSCRIPTION_STATUS_CHANGED

​Key benefits

​Workflow overview

​Implementation steps

​Quick reference

​Step 1: Create subscription

​Step 2: Raise authorisation

​SUBSCRIPTION_AUTH_STATUS webhook

​Step 3: Raise charges

​SUBSCRIPTION_PAYMENT_SUCCESS webhook

​SUBSCRIPTION_PAYMENT_FAILED webhook

​Step 4: Get mandate details

​Step 5: Refund individual charges

​Step 6: Manage mandate

​Subscription webhooks

​SUBSCRIPTION_STATUS_CHANGED

Key benefits

Workflow overview

Implementation steps

Quick reference

Step 1: Create subscription

Step 2: Raise authorisation

SUBSCRIPTION_AUTH_STATUS webhook

Step 3: Raise charges

SUBSCRIPTION_PAYMENT_SUCCESS webhook

SUBSCRIPTION_PAYMENT_FAILED webhook

Step 4: Get mandate details

Step 5: Refund individual charges

Step 6: Manage mandate

Subscription webhooks

SUBSCRIPTION_STATUS_CHANGED