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

# Manage Subscriptions

> Check mandate status, manage recurring payments, modify or cancel mandates, test in sandbox, and view subscription payments.

<Note>
  This guide covers how to manage subscriptions after creation — including checking mandate status, managing recurring payments, modifying or cancelling mandates, and viewing payment history.

  This version features automatic recurring payments. Once a mandate is active, the payment gateway automatically processes recurring debits and sends webhook notifications with the subscription ID for each payment.
</Note>

<CardGroup cols={3}>
  <Card title="Check Mandate Status" icon="clock" href="#check-mandate-status">
    Verify that the mandate is active before proceeding
  </Card>

  <Card title="Automatic Payments" icon="rotate" href="#automatic-recurring-payments">
    Recurring payments processed automatically
  </Card>

  <Card title="Modify or Cancel" icon="edit" href="#modify-or-cancel-mandate">
    Update mandate amount/end date or cancel
  </Card>

  <Card title="Adhoc Payment" icon="credit-card" href="#trigger-adhoc-recurring-payment">
    Trigger a recurring payment for ADHOC subscriptions
  </Card>

  <Card title="View Payments" icon="list" href="#view-subscription-payments">
    Fetch all payments associated with a subscription
  </Card>

  <Card title="Sandbox Testing" icon="flask" href="#sandbox-testing">
    Simulate payments and fetch PG payments in sandbox
  </Card>
</CardGroup>

## Check Mandate Status

After the customer approves the UPI mandate, use the [**Get Subscription Mandate Status**](https://docs.eximpe.com/api-reference/v2/subscriptions/mandate-status) API to verify that it is active.

### Sample Request

```json theme={null}
curl -X GET "https://api-pacb.eximpe.com/pg/subscriptions/SUB7989707770/mandate_status/" \
  -H "X-Client-ID: <your-client-id>" \
  -H "X-Client-Secret: <your-client-secret>" \
  -H "X-Merchant-ID: <your-merchant-id>" \
  -H "X-API-Version: 2.0.0"
```

### Response

```json theme={null}
{
  "success": true,
  "message": "Subscription mandate status fetched successfully",
  "data": {
    "subscription_id": "SUB_xxx",
    "mandate_is_active": true,
    "status": "ACTIVE",
    "amount": 1000,
    "mandate_start_date": "2026-04-10T00:00:00+05:30",
    "mandate_end_date": "2027-04-10T23:59:59+05:30"
  }
}
```

Only proceed with subscription management when `mandate_is_active` is `true`.

### Subscription Status Values

A subscription can have the following statuses:

| Status      | Description                                                                           |
| ----------- | ------------------------------------------------------------------------------------- |
| `PENDING`   | Subscription created but mandate not yet approved by customer                         |
| `ACTIVE`    | Subscription mandate is active and recurring payments will be processed automatically |
| `PAUSED`    | Subscription temporarily paused, no recurring payments will be processed              |
| `CANCELLED` | Subscription mandate cancelled, no further payments will be processed                 |
| `EXPIRED`   | Subscription reached its end date                                                     |
| `FAILED`    | Subscription mandate creation or activation failed                                    |

<Note>
  **Active Subscriptions**: Only subscriptions with `ACTIVE` status will have automatic recurring payments processed. Monitor the subscription status via webhooks to track lifecycle changes.
</Note>

## Automatic Recurring Payments

<Note>
  The recurring payments are processed automatically by the payment gateway based on the billing cycle defined in the standing instruction. You don't need to manually trigger recurring payments via API.
</Note>

Once the subscription mandate is active, the payment gateway will automatically debit the customer's payment method according to the billing cycle you configured (e.g., MONTHLY, WEEKLY, DAILY) in the `standing_instruction` block.

### How Automatic Payments Work

1. **Mandate Activation**: After the customer approves the mandate, it becomes active
2. **Scheduled Debit**: On each billing date, the payment gateway automatically debits the specified amount
3. **Webhook Notification**: Upon successful payment, you'll receive a webhook notification with the payment details

### Monitoring Recurring Payments

You can monitor recurring payments through:

1. **Webhooks**: Real-time notifications for each successful/failed payment
2. **Payment API**: Use the [Get Payment](https://docs.eximpe.com/api-reference/v2/payment/get) endpoint to fetch payment details
3. **Order API**: Use the [Get Order](https://docs.eximpe.com/api-reference/v2/order/get) endpoint to check order status
4. **Subscription Payments API**: Use the [Get Subscription Payments](https://docs.eximpe.com/api-reference/v2/subscriptions/payments) endpoint to list all payments for a subscription
5. **Subscription Status Webhook**: Receive updates about subscription lifecycle events

For webhook implementation details, see the [Webhooks](#webhooks) section below.

## Modify or Cancel Mandate

<Note>
  **Production Only**: Cancel mandate and modify mandate operations are only supported in production environment. These features are not available in test/sandbox environments.
</Note>

### Modify Mandate

To change the billing amount of an active subscription, use the [**Modify Subscription Mandate**](https://docs.eximpe.com/api-reference/v2/subscriptions/modify-mandate) API.

#### Sample Request

```json theme={null}
curl -X POST "https://api-pacb.eximpe.com/pg/subscriptions/SUB7989707770/modify_mandate/" \
  -H "Content-Type: application/json" \
  -H "X-Client-ID: <your-client-id>" \
  -H "X-Client-Secret: <your-client-secret>" \
  -H "X-Merchant-ID: <your-merchant-id>" \
  -H "X-API-Version: 2.0.0" \
  -d '{
    "amount": 1500.00
  }'
```

#### Response

```json theme={null}
{
  "success": true,
  "message": "Subscription mandate modification request sent successfully",
  "data": {
    "subscription_id": "SUB_xxx",
    "mandate_modified": true,
    "updated_amount": "1500.00",
    "subscription_status": "INITIALIZED"
  }
}
```

<Note>
  The `amount` field is required to modify the mandate.
</Note>

### Cancel Mandate

To fully stop future debits and revoke the subscription mandate, use the [**Cancel Subscription Mandate**](https://docs.eximpe.com/api-reference/v2/subscriptions/cancel-mandate) API.

#### Sample Request

```json theme={null}
curl -X POST "https://api-pacb.eximpe.com/pg/subscriptions/SUB7989707770/cancel_mandate/" \
  -H "X-Client-ID: <your-client-id>" \
  -H "X-Client-Secret: <your-client-secret>" \
  -H "X-Merchant-ID: <your-merchant-id>" \
  -H "X-API-Version: 2.0.0"
```

#### Response

```json theme={null}
{
  "success": true,
  "message": "Subscription mandate cancel request sent successfully",
  "data": {
    "subscription_id": "SUB_xxx",
    "mandate_cancelled": true,
    "subscription_status": "CANCELLED"
  }
}
```

The subscription will be marked as `CANCELLED` on success.

## Trigger Adhoc Recurring Payment

For **ADHOC** subscriptions, recurring payments are not automatic — you must trigger each charge via the [**Trigger Recurring Payment**](https://docs.eximpe.com/api-reference/v2/subscriptions/recurring-payment) API. The subscription must have an active mandate before a payment can be triggered.

<Info>
  This step applies only to **ADHOC** subscriptions. For standard billing cycle subscriptions (MONTHLY, WEEKLY, DAILY), payments are processed automatically — see [Automatic Recurring Payments](#automatic-recurring-payments).
</Info>

### How Adhoc Payments Work

1. **Initiate Payment** — Call the recurring payment API with an optional `amount`
2. **Asynchronous Processing** — Payments will Made one day after the api is called.
3. **Webhook Delivery** — The payment outcome (`SUCCESS`, `FAILED`, or `CANCELLED`) is delivered via webhook, at which point the order and payment records are created in the system

### Sample Request

```json theme={null}
curl -X POST "https://api-pacb.eximpe.com/pg/subscriptions/SUB_xxx/recurring_payment/" \
  -H "Content-Type: application/json" \
  -H "X-Client-ID: <your-client-id>" \
  -H "X-Client-Secret: <your-client-secret>" \
  -H "X-Merchant-ID: <your-merchant-id>" \
  -H "X-API-Version: 2.0.0" \
  -d '{
    "amount": 500.00
  }'
```

### Response

```json theme={null}
{
  "success": true,
  "message": "Recurring payment triggered successfully",
  "data": {
    "subscription_id": "sub_abc123",
    "payment_id": "REC-sub_abc123-a1b2c3d4",
    "payment_amount": 500.00,
    "status": "success",
    "message": "ADHOC recurring payment initiated successfully"
  }
}
```

<Note>
  A `success` response means the payment was **initiated**, not captured. The actual payment outcome arrives asynchronously via webhooks (`SUBSCRIPTION_PAYMENT_SUCCESS`, `SUBSCRIPTION_PAYMENT_FAILED`, or `SUBSCRIPTION_PAYMENT_CANCELLED`).
</Note>

### Constraints

* Only **ADHOC** billing cycle subscriptions are supported
* If `amount` is provided, it must not exceed the subscription's `billing_amount`

For full request and response schema, see the [**Trigger Recurring Payment**](https://docs.eximpe.com/api-reference/v2/subscriptions/recurring-payment) endpoint in API Reference.

## View Subscription Payments

Use the [**Get Subscription Payments**](https://docs.eximpe.com/api-reference/v2/subscriptions/payments) API to fetch all payments associated with a subscription from the internal system. This is available for **all payment gateways** and **all environments** (including production).

### Sample Request

```json theme={null}
curl -X GET "https://api-pacb.eximpe.com/pg/subscriptions/SUB_xxx/payments/" \
  -H "X-Client-ID: <your-client-id>" \
  -H "X-Client-Secret: <your-client-secret>" \
  -H "X-Merchant-ID: <your-merchant-id>" \
  -H "X-API-Version: 2.0.0"
```

### Response

```json theme={null}
{
  "success": true,
  "message": "Subscription payments fetched successfully",
  "data": [
    {
      "payment_id": "dpr_abc123",
      "order_id": "ord_xyz789",
      "reference_id": "SUBPAY-sub123-cf456",
      "amount": 1000.00,
      "currency": "INR",
      "status": "CAPTURED",
      "payment_type": "RECURRING",
      "mop_type": "UPI",
      "bank_ref_num": "BANK123456",
      "status_message": null,
      "created_at": "2025-03-20T10:30:00Z",
      "payment_completed_at": "2025-03-20T10:30:05Z"
    }
  ]
}
```

The response returns an array of all payment records for the subscription, including details such as the payment status, amount, mode of payment, and timestamps. Use this to build payment history views, reconcile billing records, or track installment statuses.

For full response field descriptions, see the [**Get Subscription Payments**](https://docs.eximpe.com/api-reference/v2/subscriptions/payments) endpoint in API Reference.

## Sandbox Testing

The following endpoints are available only in **sandbox/UAT environments**. Use them to test subscription payment flows without processing real transactions.

<Warning>These endpoints are not available in production.</Warning>

### Testing Flow

To test subscription payments in sandbox, follow this sequence:

1. **Fetch PG Payments** — List all payments from the payment gateway for the subscription
2. **Identify pending payments** — Find payments with `PENDING` status in the response
3. **Simulate Payment** — Pass the `payment_id` of a pending payment to simulate `SUCCESS` or `FAILED`

### Fetch PG Payments

First, use the [**Fetch PG Payments**](https://docs.eximpe.com/api-reference/v2/subscriptions/pg-payments) API to fetch all payments for a subscription directly from the payment gateway.

#### Sample Request

```json theme={null}
curl -X GET "https://api-pacb.eximpe.com/pg/subscriptions/SUB_xxx/pg_payments/" \
  -H "X-Client-ID: <your-client-id>" \
  -H "X-Client-Secret: <your-client-secret>" \
  -H "X-Merchant-ID: <your-merchant-id>" \
  -H "X-API-Version: 2.0.0"
```

#### Response

```json theme={null}
{
  "success": true,
  "message": "PG payments fetched successfully",
  "data": [
    {
      "payment_id": "pay_abc123",
      "status": "PENDING"
    },
    {
      "payment_id": "pay_def456",
      "status": "SUCCESS"
    }
  ]
}
```

From the response, identify payments with `PENDING` status. Use their `payment_id` in the next step to simulate a payment outcome.

For full response schema, see the [**Fetch PG Payments**](https://docs.eximpe.com/api-reference/v2/subscriptions/pg-payments) endpoint in API Reference.

### Simulate Payment

Once you have a `payment_id` with `PENDING` status from the PG payments response, use the [**Simulate Payment**](https://docs.eximpe.com/api-reference/v2/subscriptions/simulate-payment) API to simulate a success or failure for that payment.

#### Sample Request

```json theme={null}
curl -X POST "https://api-pacb.eximpe.com/pg/subscriptions/SUB_xxx/simulate_payment/" \
  -H "Content-Type: application/json" \
  -H "X-Client-ID: <your-client-id>" \
  -H "X-Client-Secret: <your-client-secret>" \
  -H "X-Merchant-ID: <your-merchant-id>" \
  -H "X-API-Version: 2.0.0" \
  -d '{
    "payment_status": "SUCCESS",
    "payment_id": "pay_abc123"
  }'
```

#### Response

```json theme={null}
{
  "success": true,
  "message": "Payment simulation triggered successfully",
  "data": {
    "payment_id": "pay_abc123",
    "payment_status": "SUCCESS"
  }
}
```

The `payment_status` field accepts `SUCCESS` or `FAILED`. The `payment_id` should be a pending payment obtained from the [Fetch PG Payments](#fetch-pg-payments) response.

For full request and response schema, see the [**Simulate Payment**](https://docs.eximpe.com/api-reference/v2/subscriptions/simulate-payment) endpoint in API Reference.

***

## Webhooks

EximPe sends webhook notifications for both subscription lifecycle events and recurring payment events. Configure webhooks to receive real-time updates.

### Payment Successful Webhook (for Recurring Payments)

For each automatic recurring payment, you'll receive a **Payment Successful** webhook. This webhook includes the `subscription_id` field, allowing you to track which subscription the payment belongs to.

**Key Fields in Payment Webhook:**

* `subscription_id`: The unique identifier of the subscription
* `order_id`: The order ID for this specific payment
* `payment_id`: The payment transaction ID
* `amount`: The amount charged
* `status`: Payment status (SUCCESS)

For complete webhook payload details, see the [**Payment Successful Webhook**](https://docs.eximpe.com/api-reference/v2/webhooks/payment-successful) in API Reference.

### Subscription Status Webhook

The **Subscription Status** webhook is triggered when a subscription status changes or subscription information is updated. This allows you to track subscription lifecycle events and update your billing records accordingly.

**Common Subscription Events:**

* `PENDING` → `ACTIVE`: Mandate created and activated successfully
* `ACTIVE` → `PAUSED`: Subscription temporarily paused
* `PAUSED` → `ACTIVE`: Subscription resumed
* `ACTIVE` → `CANCELLED`: Subscription cancelled by merchant or customer
* `ACTIVE` → `EXPIRED`: Subscription reached its end date
* `PENDING` → `FAILED`: Mandate creation or activation failed

**Status Transitions:**

* New subscriptions start with `PENDING` status
* Once mandate is approved, status changes to `ACTIVE`
* Subscriptions can be paused/resumed or cancelled at any time
* Subscriptions automatically expire when `payment_end_date` is reached

For detailed webhook payload specifications, event types, and implementation details, refer to the [**Subscription Status Webhook**](https://docs.eximpe.com/api-reference/v2/webhooks/subscription-status) in API Reference.

<Note>
  For general webhook setup, security, and verification, see the [**Webhooks Integration Guide**](/integration-guide/v2/web-integration/webhooks).
</Note>