Proxen pro-backend API
The billing and admin API behind Proxen Pro — buy a plan, read entitlement, and provision a subscription key.
The pro-backend is the service behind Proxen Pro. It owns two HTTP surfaces:
- a public billing API (
/api/v1/billing) that clients call to read the plan catalogue, open a checkout, observe entitlement, and receive a subscription URL once a payment lands; - an admin/back-office API (
/admin) that operators use behind a session cookie, gated by role-based access control.
It is built for a Russian audience with no Stripe. "Buy" is a pluggable payment provider (a deterministic sandbox rail today; RU-friendly hosted rails when configured), and "generate a key" is real panel provisioning — the backend never mints credentials itself.
Quickstart
Walk a full buy → entitlement → subscription flow against the live endpoints.
Authentication
Public-by-userRef billing, signed webhooks, and the panel session cookie +
RBAC model.
Entitlement lifecycle
The state machine that drives Pro access and exactly-once provisioning.
Billing API
Config, checkout, entitlement, and the provider webhook rail.
Base URLs
| Environment | Base URL |
|---|---|
| Production | https://api.proxen.net |
| Local dev | http://localhost:3000 |
The admin panel is mounted under /admin on the same API host; billing
lives under /api/v1/billing. There is no separate admin host — api.proxen.net
serves both. (The Marzneshin subscription panel at panel.proxen.net is a
distinct, third-party system; the pro-backend talks to it server-side but never
exposes it as a Proxen endpoint.)
How a purchase flows
Discover the default plan
GET /api/v1/billing/config returns the defaultPlanId so clients never
hardcode it.
Open a checkout
POST /api/v1/billing/checkout with a plan, a caller-supplied userRef,
and an optional provider. The response carries a rail-specific
instruction (redirect URL, crypto address, Telegram invoice, or manual
steps).
Payment is confirmed
The payment rail calls back to POST /api/v1/billing/webhook/{provider}
(signed, idempotent). In dev/e2e the sandbox rail is confirmed via
POST /api/v1/billing/sandbox/confirm instead.
Entitlement activates and a key is provisioned
On the → active edge the backend provisions a Marzneshin user
exactly once and stores the panel's subscription_url.
Read entitlement + subscription URL
GET /api/v1/billing/entitlement?userRef=… returns the entitlement state,
isProActive, and the subscriptionUrl for the client to import.
This documentation describes the live pro-backend surface. Where a feature is planned but not yet shipped (the admin code-generation API, the real Telegram-Stars / CryptoBot rails), it is clearly marked as planned and is not part of the OpenAPI spec.