Revenue Recovery

When a recurring renewal declines, recovering that decline (dunning) means deciding when to retry, which connector to retry on, and what retry curve to use per BIN / MCC / time-of-day. MVS Pay does not build that orchestration. Per ADR-011, retry timing and connector selection are handed off to Hyperswitch Revenue Recovery (a first-class Juspay feature as of router v1.123.1). MVS keeps the parts it owns end-to-end: subscription state, billing line items, invoice generation, and the operator-facing recovery-plan UI.

The result is a thin brokering surface. mvs-pay-extensions proxies three Hyperswitch recovery resources, and a single signed webhook flows the other way to advance local BillingSubscription state. Nothing in MVS schedules a retry, picks a connector, or models a BIN curve.

Division of ownership

The seam is deliberately drawn so that MVS never re-implements dunning intelligence, and Hyperswitch never holds the system-of-record subscription state.

The rationale (from ADR-011) is that the retry decision is exactly where Hyperswitch’s >20 signals live — BIN issuer profile, MCC-specific curves, time-of-day windows, cross-connector decline correlation, velocity throttles. The “hybrid” option (MVS schedules, Hyperswitch executes) was rejected for precisely this reason: splitting the decision from the execution loses the value of the native engine.

The two-way seam

The handoff is bidirectional and the two directions have different trust models.

MVS → Hyperswitch (the proxy)

The route handler is apps/mvs-pay-extensions/src/routes/revenue-recovery.ts, mounted at /v1/revenue-recovery (see apps/mvs-pay-extensions/src/app.ts). It exposes three resources, each a thin proxy over the typed Hyperswitch client (services/hyperswitch-client.ts, the revenueRecovery namespace):

The plan body is validated with Zod before it leaves MVS (planInputSchema in routes/revenue-recovery.ts):

1
const planInputSchema = z.object({
2
  merchantId: z.string().min(1),
3
  retryBudget: z.number().int().nonnegative(),
4
  startAfter: z.object({
5
    value: z.number().int().positive(),
6
    unit: z.enum(["minutes", "hours"]),
7
  }),
8
  maxRetries: z.number().int().min(1).max(10),
9
  cadence: z.enum(["aggressive", "moderate", "conservative"]),
10
});

So MVS owns the shape of the plan (budget, start-after window, max retries ≤ 10, and a cadence preset), but Hyperswitch owns what those presets mean in terms of actual retry spacing and connector choice. The proxy is honest about its passthrough nature: the client typed the Hyperswitch responses as unknown (request<unknown>(...) in services/hyperswitch-client.ts), so the GET /plan and GET /stats payloads are returned verbatim from the router — MVS does not re-model them.

Registering the callback (subscription-platform)

POST /v1/revenue-recovery/subscription-platform tells Hyperswitch where to send outcome events. The body carries merchantId, webhookUrl, and a webhookSecret (≥ 16 chars):

1
const subscriptionPlatformInputSchema = z.object({
2
  merchantId: z.string().min(1),
3
  webhookUrl: z.string().url(),
4
  webhookSecret: z.string().min(16),
5
});

The client remaps these to Hyperswitch’s snake_case wire fields (webhook_url, webhook_secret) when calling /account/{merchant_id}/recovery/subscription_platform. That webhookSecret is what the inbound handler uses to HMAC-verify callbacks — it mirrors the payment_response_hash_key pattern used by the main webhook ingest at routes/webhooks-hyperswitch.ts.

Inbound: the outcome webhook

The ingest is apps/mvs-pay-extensions/src/routes/webhooks-revenue-recovery.ts, mounted at /webhooks/revenue-recovery alongside the main /webhooks/hyperswitch ingest. Both share the same global rate-limit envelope (bucketKey: () => "global-revenue-recovery") and are signature-verified inside the handler rather than via internal-secret auth (see app.ts).

Verification

The handler reads the raw body and accepts either an SHA-512 or SHA-256 HMAC, in x-webhook-signature-512 / x-webhook-signature-256 respectively, compared in constant time:

1
const verified =
2
  (sig512 && verifySignature(rawBody, sig512, secret, "sha512")) ||
3
  (sig256 && verifySignature(rawBody, sig256, secret, "sha256"));

If HYPERSWITCH_WEBHOOK_SECRET is unset the handler returns 503 not_configured (it does not silently accept). A signature mismatch returns 401 signature_invalid.

Mapping an event to a subscription

The payload carries a content.object with an outcome and a locator. MVS maps the event to a BillingSubscription using, in order of preference:

1. subscription_id → matched against BillingSubscription.id
2. hyperswitch_mandate_id → matched against BillingSubscription.hyperswitchMandateId (the unique mandate column)

If neither is present, or no subscription matches, the handler acks with { ok: true, ignored: ... } rather than erroring — this stops Hyperswitch from retrying a dead event. The ack/ignore branches are logged at warn.

The dunning state machine (MVS side)

This is the part MVS owns. The webhook is the single writer of three columns on BillingSubscription (added in migration 20261001000000_phase4_revenue_recovery):

computeTransition(...) derives the new state purely from the inbound outcome and the final flag. Hyperswitch is the timing authority, so MVS only records the latest attempt — it never schedules the next one.

Concretely, from computeTransition:

A terminal failed (final: true) flips the subscription to UNPAID. This is the highest-risk transition in the whole feature.

Persistence and idempotency

The update writes all three columns plus the conditional status transition. On a DB failure the handler returns 500 persistence_failed (so Hyperswitch will retry the delivery). Note the handler does not dedupe on event_id — a re-delivered failed event will increment recoveryAttemptCount again. The count is therefore best read as “attempts MVS observed,” not a guaranteed exact match of Hyperswitch’s internal counter.

The feature flag

ADR-011 states the native option is “live behind a feature flag, so the cost of trying it is bounded — if it underperforms MVS-side dunning, we can roll the flag back, keep the SDK contract, and swap the implementation underneath.”

Surfaces

The feature is reachable from three layers, each a thin pass-through to the one below it.

The Next.js API route (apps/mvs-pay/app/api/revenue-recovery/route.ts) wraps the SDK for the dashboard: GET ?merchantId= reads the plan and POST writes it; stats live at the symmetric /api/revenue-recovery/stats. All of these are behind the org-session auth (getPaymentsContext) and ultimately resolve to the same mvs-pay-extensions proxy.

Operating notes for the new owner

Related reading

• ADR-011: Hand off dunning to Hyperswitch Revenue Recovery — the decision and rejected alternatives.
• ADR-007: Native Hyperswitch bias — the broader stance.
• Routing & Smart Retries — the related retry/connector-selection surface and is_auto_retries_enabled.
• Subscriptions & Billing — the BillingSubscription lifecycle this feature drives.
• SDK — the revenueRecovery namespace contract.
• Payment Lifecycle — the underlying payment-intent state machine.