Developer Documentation

PauseSetu API

Integrate subscription pause infrastructure into your application. Keep mandates alive while billing sleeps.

Base URL

pausesetu-api.onrender.com

Protocol

REST + JSON

Auth

API Key + HMAC

Overview

PauseSetu is middleware infrastructure that sits between your application and payment gateways (Razorpay, Cashfree, PhonePe). When a subscriber wants to take a break, PauseSetu pauses their recurring charge while keeping the underlying bank mandate active. When the pause period ends, billing resumes automatically — no new 2FA, no re-signup, no friction.

The API follows REST conventions. All requests and responses use JSON. Authentication is via SHA-256 hashed API keys for server-to-server calls, and HMAC-SHA256 signed webhooks for event notifications.

Authentication

All API requests require authentication via your API key. Include it in the X-API-Key header. Keys are SHA-256 hashed before storage — PauseSetu never stores your raw key.

# Include your API key in every request
curl -X GET https://pausesetu-api.onrender.com/api/v1/merchant/subscriptions \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json"

Core Endpoints

The PauseSetu API provides endpoints for managing subscriptions, executing pauses and resumes, handling Pro tier upgrades, and retrieving analytics. All endpoints are prefixed with /api/v1.

Method	Endpoint	Description
POST	/subscriptions	Create a new subscription
GET	/subscriptions	List all subscriptions
GET	/subscriptions/{id}	Get subscription details
PUT	/subscriptions/{id}	Update a subscription
DELETE	/subscriptions/{id}	Delete a subscription
POST	/subscriptions/{id}/pause	Pause a subscription
POST	/subscriptions/{id}/resume	Resume a paused subscription
POST	/pro/subscribe	Subscribe to Pro tier
GET	/pro/status	Check Pro subscription status
GET	/analytics/summary	Get spending analytics
GET	/analytics/export/csv	Export data as CSV (Pro)
POST	/merchant/webhooks	Register a webhook endpoint
POST	/ai/parse-date	Parse natural language dates

Pause a Subscription

The pause endpoint transitions a subscription through a five-state machine: ACTIVE → PAUSE_REQUESTED → PAUSED → RESUME_SCHEDULED → ACTIVE. The bank mandate remains active throughout the pause period. When the resume date arrives, billing restarts automatically without requiring new 2FA from the subscriber.

# Pause a subscription for 30 days
curl -X POST https://pausesetu-api.onrender.com/api/v1/subscriptions/{id}/pause \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"pause_days": 30, "reason": "vacation"}'

Response:

{
  "status": "paused",
  "pause_start": "2026-06-21T00:00:00Z",
  "resume_date": "2026-07-21T00:00:00Z",
  "mandate_status": "active",
  "charge": 0,
  "message": "Subscription paused successfully"
}

Webhooks

PauseSetu sends real-time event notifications to your registered webhook URL. All webhook payloads are signed with HMAC-SHA256 using your webhook secret. Verify the X-PauseSetu-Signature header to ensure payload authenticity.

Supported events:

subscription.created

subscription.paused

subscription.resumed

subscription.cancelled

pause.requested

pause.auto_resumed

pro.subscribed

pro.expired

Verifying webhook signatures (Python):

import hmac, hashlib

def verify_signature(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

AI Date Parsing

PauseSetu includes a built-in natural language date parser powered by a two-layer system: local regex for common patterns, with Gemini 2.0 Flash as an intelligent fallback. Supports English, Hindi, and Hinglish inputs — your subscribers can say "pause for 2 weeks" or "15 din ke liye rok do" and PauseSetu will resolve the correct resume date.

# Parse a natural language date
curl -X POST https://pausesetu-api.onrender.com/api/v1/ai/parse-date \
  -H "Content-Type: application/json" \
  -d '{"text": "pause for 2 weeks", "language": "en"}'

# Response
{ "parsed_date": "2026-07-05", "confidence": 0.95, "parser": "regex" }

Error Codes

Code	Meaning
200	Request successful
201	Resource created successfully
400	Bad request — check your request body
401	Unauthorized — invalid or missing API key
403	Forbidden — insufficient permissions or Pro feature required
404	Resource not found
409	Conflict — subscription already in requested state
422	Validation error — check field requirements
429	Rate limited — too many requests
500	Server error — contact support

Rate Limits

API requests are rate limited per API key. Starter plans allow 100 requests per minute. Growth and Enterprise plans have higher limits based on your agreement. When rate limited, the API returns HTTP 429 with a Retry-After header indicating how many seconds to wait before retrying.

Quick Integration

Step 1. Sign up for early access and receive your API key.

Step 2. Connect your Razorpay, Cashfree, or PhonePe account.

Step 3. Add a "Pause" button in your subscriber dashboard that calls our pause endpoint.

Step 4. Register your webhook URL to receive real-time pause and resume notifications.

Ready to integrate?

Join the waitlist for early access and your API key. We'll have you live in under 10 minutes.

Join the Waitlist

Questions about integration? Email us at hello@pausesetu.in