Subscription Management

Manage your Rach Payments subscription plan, check current usage, and upgrade when you hit plan limits.

Plans at a Glance

Plan	Price	Customer Wallets	Transactions/month	Webhooks	Support
Starter	$13/mo	5	1,000	—	Community
Professional	$42/mo	50	10,000	✓	24/7 Priority
Business	$129/mo	Unlimited	100,000	✓	Dedicated manager
Enterprise	Custom	Unlimited	Unlimited	✓	24/7 dedicated team

Annual billing saves 15% compared to monthly.

---

Endpoints

GET /api/v1/subscription/current

Returns your active plan, feature flags, limits, and real-time usage counters for the current month.

Authentication: JWT Bearer (X-Authorization: Bearer <token>)

JavaScript

const res = await fetch('https://api.rachfinance.com/api/v1/subscription/current', {
  headers: { 'X-Authorization': `Bearer ${token}` }
});
const sub = await res.json();

console.log(`Plan: ${sub.plan.name}`);
console.log(`Wallets: ${sub.usage.wallet_addresses_used} / ${sub.limits.max_wallet_addresses === -1 ? '∞' : sub.limits.max_wallet_addresses}`);
console.log(`Transactions this month: ${sub.usage.transactions_this_month}`);

Python

import requests

res = requests.get(
    'https://api.rachfinance.com/api/v1/subscription/current',
    headers={'X-Authorization': f'Bearer {token}'}
)
sub = res.json()
print(sub['plan']['name'], sub['usage'])

cURL

curl https://api.rachfinance.com/api/v1/subscription/current \
  -H "X-Authorization: Bearer $TOKEN"

Response (200 OK)

{
  "plan": {
    "name": "business",
    "duration": "annual",
    "status": "active",
    "expiry": "2026-12-20T00:00:00Z"
  },
  "limits": {
    "max_wallet_addresses": -1,
    "max_transactions_per_month": 100000,
    "market_data": "advanced"
  },
  "features": {
    "webhooks": true,
    "sms": true,
    "priority_processing": true,
    "custom_branding": true,
    "multi_user": true,
    "white_label": true
  },
  "usage": {
    "wallet_addresses_used": 12,
    "transactions_this_month": 843
  }
}

TIP

max_wallet_addresses: -1 and max_transactions_per_month: -1 both mean unlimited. Use limits to drive upgrade prompts in your dashboard before customers hit a wall.

---

GET /api/v1/subscription/plans

Lists all plans with pricing, features, and limits. No authentication required — safe to call from a public pricing page.

cURL

curl https://api.rachfinance.com/api/v1/subscription/plans

Response (200 OK)

{
  "plans": [
    {
      "id": "starter",
      "name": "Starter",
      "price_monthly": 13,
      "price_annual": 156,
      "description": "Perfect for side projects and small businesses",
      "limits": {
        "max_wallet_addresses": 5,
        "max_transactions_per_month": 1000
      },
      "features": [
        "Up to 1,000 transactions/month",
        "5 wallet addresses",
        "Basic market data access",
        "Standard crypto payment gateway",
        "Email notifications",
        "Community support"
      ]
    },
    {
      "id": "professional",
      "name": "Professional",
      "price_monthly": 42,
      "price_annual": 504,
      "description": "For growing businesses scaling globally",
      "limits": {
        "max_wallet_addresses": 50,
        "max_transactions_per_month": 10000
      },
      "features": [
        "Up to 10,000 transactions/month",
        "50 wallet addresses",
        "Advanced market data & analytics",
        "SMS + Email + Webhook notifications",
        "Priority support (24/7)",
        "Custom branding",
        "Multi-user access"
      ]
    },
    {
      "id": "business",
      "name": "Business",
      "price_monthly": 129,
      "price_annual": 1548,
      "description": "For established businesses with high volume",
      "limits": {
        "max_wallet_addresses": -1,
        "max_transactions_per_month": 100000
      },
      "features": [
        "Up to 100,000 transactions/month",
        "Unlimited wallet addresses",
        "White-label solution",
        "AI insights",
        "Dedicated account manager"
      ]
    },
    {
      "id": "enterprise",
      "name": "Enterprise",
      "price_monthly": null,
      "price_annual": null,
      "description": "Custom solutions for large-scale operations",
      "limits": {
        "max_wallet_addresses": -1,
        "max_transactions_per_month": -1
      },
      "features": [
        "Unlimited everything",
        "Custom infrastructure",
        "On-premise deployment",
        "Custom SLA & compliance"
      ]
    }
  ]
}

---

POST /api/v1/subscription/upgrade

Changes your plan immediately. Limits are enforced from the next API call.

Authentication: JWT Bearer

Request body:

Field	Type	Required	Values
plan	string	Yes	starter, professional, business, enterprise
duration	string	Yes	monthly, annual

JavaScript

const res = await fetch('https://api.rachfinance.com/api/v1/subscription/upgrade', {
  method: 'POST',
  headers: {
    'X-Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ plan: 'professional', duration: 'annual' })
});
const result = await res.json();
console.log(result.message, result.plan, result.expiry);

cURL

curl -X POST https://api.rachfinance.com/api/v1/subscription/upgrade \
  -H "X-Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"plan":"professional","duration":"annual"}'

Response (200 OK)

{
  "message": "Subscription updated successfully",
  "plan": "professional",
  "status": "active",
  "expiry": "2027-06-20T00:00:00Z"
}

---

POST /api/v1/subscription/crypto-checkout

Pay for a plan upgrade with crypto. Creates a payment session identical to the checkout gateway — on payment confirmation the system auto-upgrades the plan.

Request body:

Field	Type	Required	Description
plan	string	Yes	Target plan: starter, professional, business, enterprise
duration	string	No	monthly or annual (default: annual)
network	string	No	Preferred payment network (e.g. BSC)
currency	string	No	Preferred token (e.g. USDT)

Response: Same shape as POST /api/v1/checkout/create.

---

Plan Enforcement

Every time a gated API is called, the system:

1. Checks the business's plan_status and plan_expiry.
2. If expired → 402 Payment Required.
3. If limit exceeded → 403 Forbidden with a machine-readable code.

Error	Code	What triggered it
402	—	Plan expired or cancelled
403	WALLET_LIMIT_EXCEEDED	POST /api/v1/wallet/customers when at cap
402	TRANSACTION_LIMIT_EXCEEDED	POST /api/v1/checkout/create when monthly cap reached

Handling these in your integration:

const res = await fetch('/api/v1/wallet/customers', { ... });

if (res.status === 402) {
  // Subscription expired — show renewal CTA
  showRenewalBanner();
} else if (res.status === 403) {
  const body = await res.json();
  if (body.code === 'WALLET_LIMIT_EXCEEDED') {
    // Hit wallet cap — show upgrade prompt
    showUpgradePlan(currentPlan, 'wallet limit');
  }
}

Proactive checks

Before creating a customer wallet, call GET /api/v1/subscription/current and compare usage.wallet_addresses_used to limits.max_wallet_addresses. This lets you show an upgrade prompt before the user hits the wall, rather than after.

---

Webhook Availability

Webhooks (deposit notifications from Deposit Monitoring and completed checkouts) are only dispatched on Professional and above plans.

Plan	Webhooks
Starter	— (polling only)
Professional	✓
Business	✓
Enterprise	✓

If your plan does not include webhooks, use GET /api/v1/checkout/verify/{sessionId} to poll for payment status instead.

---

Admin Endpoints

These endpoints require an admin JWT and are used for managing individual business subscriptions from the platform dashboard.

GET /admin/businesses/:id/subscription

Returns the full subscription state for any business.

PUT /admin/businesses/:id/subscription

Sets a business's plan and duration directly. Useful for manual upgrades, custom Enterprise deals, or extending existing subscriptions.

Request body: Same as POST /api/v1/subscription/upgrade.

Response: Plan details + limits + feature flags.