Manage Subscriptions - EximPe Docs

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.

Check Mandate Status

Verify that the mandate is active before proceeding

Automatic Payments

Recurring payments processed automatically

Modify or Cancel

Update mandate amount/end date or cancel

Adhoc Payment

Trigger a recurring payment for ADHOC subscriptions

View Payments

Fetch all payments associated with a subscription

Sandbox Testing

Simulate payments and fetch PG payments in sandbox

Check Mandate Status

After the customer approves the UPI mandate, use the Get Subscription Mandate Status API to verify that it is active.

Sample Request

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

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

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

Automatic Recurring Payments

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.

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

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

Monitoring Recurring Payments

You can monitor recurring payments through:

Webhooks: Real-time notifications for each successful/failed payment
Payment API: Use the Get Payment endpoint to fetch payment details
Order API: Use the Get Order endpoint to check order status
Subscription Payments API: Use the Get Subscription Payments endpoint to list all payments for a subscription
Subscription Status Webhook: Receive updates about subscription lifecycle events

For webhook implementation details, see the Webhooks section below.

Modify or Cancel Mandate

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

Modify Mandate

To change the billing amount or end date of an active subscription, use the Modify Subscription Mandate API.

Sample Request

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,
    "end_date": "2025-12-31"
  }'

Response

{
  "success": true,
  "message": "Subscription mandate modification request sent successfully",
  "data": {
    "subscription_id": "SUB_xxx",
    "mandate_modified": true,
    "updated_amount": "1500.00",
    "updated_end_date": "2025-12-31",
    "subscription_status": "INITIALIZED"
  }
}

At least one of amount or end_date must be provided to modify the mandate.

Cancel Mandate

To fully stop future debits and revoke the subscription mandate, use the Cancel Subscription Mandate API.

Sample Request

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

{
  "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 API. The subscription must have an active mandate before a payment can be triggered.

This step applies only to ADHOC subscriptions. For standard billing cycle subscriptions (MONTHLY, WEEKLY, DAILY), payments are processed automatically — see Automatic Recurring Payments.

How Adhoc Payments Work

Initiate Payment — Call the recurring payment API with an invoice_display_number and optional amount
Asynchronous Processing — Payments will Made one day after the api is called.
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

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 '{
    "invoice_display_number": "INV-2025-0042",
    "amount": 500.00
  }'

Response

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

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

Constraints

Only ADHOC billing cycle subscriptions are supported
invoice_display_number is mandatory for all recurring payments
If amount is provided, it must not exceed the subscription’s billing_amount
You can optionally pass a transaction_id (max 64 chars); otherwise a REC-prefixed ID is auto-generated

For full request and response schema, see the Trigger Recurring Payment endpoint in API Reference.

View Subscription Payments

Use the Get Subscription 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

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

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

These endpoints are not available in production.

Testing Flow

To test subscription payments in sandbox, follow this sequence:

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

Fetch PG Payments

First, use the Fetch PG Payments API to fetch all payments for a subscription directly from the payment gateway.

Sample Request

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

{
  "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 endpoint in API Reference.

Simulate Payment

Once you have a payment_id with PENDING status from the PG payments response, use the Simulate Payment API to simulate a success or failure for that payment.

Sample Request

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

{
  "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 response. For full request and response schema, see the 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 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 in API Reference.

For general webhook setup, security, and verification, see the Webhooks Integration Guide.

Get Started

Payment Integration

Check Mandate Status

Automatic Payments

Modify or Cancel

Adhoc Payment

View Payments

Sandbox Testing

​Check Mandate Status

​Sample Request

​Response

​Subscription Status Values

​Automatic Recurring Payments

​How Automatic Payments Work

​Monitoring Recurring Payments

​Modify or Cancel Mandate

​Modify Mandate

​Sample Request

​Response

​Cancel Mandate

​Sample Request

​Response

​Trigger Adhoc Recurring Payment

​How Adhoc Payments Work

​Sample Request

​Response

​Constraints

​View Subscription Payments

​Sample Request

​Response

​Sandbox Testing

​Testing Flow

​Fetch PG Payments

​Sample Request

​Response

​Simulate Payment

​Sample Request

​Response

​Webhooks

​Payment Successful Webhook (for Recurring Payments)

​Subscription Status Webhook

Check Mandate Status

Sample Request

Response

Subscription Status Values

Automatic Recurring Payments

How Automatic Payments Work

Monitoring Recurring Payments

Modify or Cancel Mandate

Modify Mandate

Sample Request

Response

Cancel Mandate

Sample Request

Response

Trigger Adhoc Recurring Payment

How Adhoc Payments Work

Sample Request

Response

Constraints

View Subscription Payments

Sample Request

Response

Sandbox Testing

Testing Flow

Fetch PG Payments

Sample Request

Response

Simulate Payment

Sample Request

Response

Webhooks

Payment Successful Webhook (for Recurring Payments)

Subscription Status Webhook