Billing & subscriptions

The Subscription & Billing module owns plans, subscriptions, invoices, and payment orchestration, integrated with Razorpay. Configuration lives under Platform Settings → Billing Configuration.

How billing works

1. A subscription is created during onboarding.
2. The platform creates a matching Razorpay order/subscription via the configured key pair.
3. Invoices are generated for each billing cycle.
4. Razorpay sends webhooks for payment success/failure/cancellations.
5. The platform applies the event to the subscription state.

Configuration

Setting (Billing Configuration)	Purpose
RazorpayKeyId	Public API key
RazorpayKeySecret	Secret key (encrypted)
RazorpayWebhookSecret	Used to verify Razorpay webhooks
RazorpayEnvironment	test or live gateway routing

Environment	Effect
test	Sandbox — no real charges, ideal for trial/onboarding validation
live	Real payment routing for production

Note: Switch RazorpayEnvironment to live only when the storefront is ready for production checkout.

Webhook verification

Payments arrive as webhooks. The platform:

1. Verifies the RazorpayWebhookSecret signature.
2. Maps the event (payment.captured, payment.failed, subscription.cancelled, …) to the invoice.
3. Updates subscription states: pending, succeeded, failed, cancelled, refunded.
4. Records an audit entry for the change.

Invoices

• Invoices are generated automatically each cycle.
• Stored with the subscription and visible on the customer billing dashboard.
• Failed payments surface on the dashboard and via Notification.

States

State	Meaning
pending	Order created, awaiting payment
succeeded	Payment captured, cycle active
failed	Payment declined/error
cancelled	Customer or platform cancelled
refunded	Payment returned

Related

• Customer onboarding — subscription creation at signup
• Platform settings reference — Billing Configuration
• Notification — invoice & payment notifications