Disimula – Payments, plans and upgrade hooks
Per-game tiers, passes, yearly plans and AI credits sold through Paddle as merchant of record, with signed idempotent webhooks, refund holds and in-context upgrade prompts.
The model: plans belong to games
Most party-game organizers play a few times a year, so a monthly subscription would be the wrong default. In Disimula every game has a tier, and an organizer gets tiers for their games in three ways: free, with a pass (one game, for good), or with a yearly subscription.
| Free | Fiesta | Creador | |
|---|---|---|---|
| Players per game | 6 | 12 | 30 |
| Themes | the free variants | the whole catalog | the whole catalog |
| Printable cards (PDF) | no, online only | yes | yes |
| Custom card backs (photo, design) | no | yes | yes |
| Own mission sets per game | 0 | 2 | unlimited |
| Games in play at once | 1 | 3 with a subscription | 10 with a subscription |
These are rows in a tier_limit table and settings in billing_setting, so admins can change them
from the app (globally, or per user) without a deploy.
Products
| Product | Price (EUR, tax included) | Type |
|---|---|---|
| Fiesta pass | 4.99 | one-off, one game |
| 3 Fiesta passes | 11.99 | one-off |
| Creador pass (+ AI credits) | 9.99 | one-off, one game |
| Fiesta → Creador upgrade | 5.00 | one-off, raises one game |
| Fiesta yearly | 19.99 / year | subscription |
| Creador yearly (+ monthly AI credits) | 39.99 / year | subscription |
| 10 AI credits | 2.99 | one-off |
Rules that keep it fair
- A game's tier only goes up. A pass applied to a game stays with it for good.
- An unused pass expires after
PASS_VALID_DAYS(365); a draft deleted unplayed gives its pass back. - A draft created under a subscription that ended goes back to free; games already started keep their tier.
- Players and themes are fixed when the game is created, so raising a game's tier later unlocks printing and custom backs, not more players.
- AI credits come in two buckets: the monthly ones of a Creador subscription (expire, refilled hourly
by
BillingSchedulewhen due) and purchased ones (never expire). Spending takes the expiring ones first; a refund goes back to the bucket it came from. Every change is in acredit_transactionledger.
A switch for launching
None of this applies until an admin sets ENFORCED to 1. Until then every new game is Creador
(source ADMIN), as are the games created before plans existed. That let the whole billing system
ship "dark" and be tried end to end before any limit applied to anyone.
Paddle as merchant of record
Paddle Billing is the seller: it charges the customer, issues the invoice (with their VAT number if they give one), collects and pays VAT in every country, and pays out monthly. The app only has to know what was paid, by whom. That removes VAT registration and invoicing from a one-person project.
Checkout
POST /billing/checkout {product}creates a Paddle transaction with the user's id incustom_dataand returns its checkout URL.- That URL is Paddle's default payment link, which points back at the app's
/pagarpage, where Paddle.js opens the checkout overlay./pagaris the only page whose CSP allows Paddle's scripts and frames. - Discount codes are Paddle's own, typed in its checkout. The app's own promo codes are a different thing (below).
The browser never tells the backend what was paid.
Webhooks: the source of truth
The webhook endpoint is the only one open to the internet without Access (a Bypass policy for that exact path), and a WAF rule only lets Paddle's published IP addresses reach it. Every notification must:
- carry a valid
Paddle-Signature(HMAC with the destination's secret); - be at most 5 minutes old, so a captured request cannot be replayed later;
- be new: each event id is stored in
payment_eventand handled once, so Paddle's retries are harmless.
Then:
| Event | Effect |
|---|---|
transaction.completed | gives the passes and credits; payment records what was given, for refunds |
subscription.* | starts, renews, cancels (kept until the end of the period) or ends a subscription |
adjustment.* pending approval | the payment's unused passes are HELD: visible, but unusable |
adjustment.* approved | unused passes revoked, credits taken back; partial refunds take back only their share |
adjustment.* rejected | held passes released |
Every webhook is counted by outcome as a metric, and payments that need a hand (paid but no user in
custom_data, for instance, when someone pays from outside the app) are logged and counted on the
billing dashboard. As a last resort an admin can give passes by hand.
Customer self-service
- Purchases page: what the user bought, newest first, with refunds.
- Invoices and subscription: a link to Paddle's customer portal (
GET /billing/portal), where they download invoices, update the card or cancel.
Sandbox first
Everything was built against Paddle's sandbox (dev always uses it: PADDLE_SANDBOX=true), with
test cards and the webhook simulator. Locally, a cloudflared quick tunnel gives Paddle a public URL
to reach the laptop. /pagar warns when the public token's prefix (test_ / live_) does not match
the environment, the most common setup mistake.
Promo codes
Separate from Paddle discounts: POST /billing/redeem with a code that gives passes, a
subscription and/or credits. Each user redeems a code once; a code may run out, expire or be switched
off. A batch creates one random single-use code per guest, for events.
Upgrade hooks ("ganchos de pago")
The limits are enforced in the backend, but the UI turns each one into an in-context, explained upgrade rather than a dead end:
- New game wizard. Locked themes stay visible with a "🔒 Fiesta" chip and what unlocks them; the player count and photo options show their tier limit, with a link to Plans and the price.
- Tier panel on every game. What the game can do now, where its tier comes from (free, subscription, pass), and a "Use a pass (n)" / "Get a pass" button that raises that game in place.
- Printable cards and custom backs. Free games can still be played online; printing and photo backs show the lock and the upgrade path.
- AI generation. The credit cost is shown before asking; not enough credits links to Plans (credit packs or Creador).
- Every 402.
plan_limitcarrieslimit,tierandallowed, so any blocked action (players, catalog, own sets, printable cards, custom back, active games) gets a precise message in the user's language: what was hit, on which plan, and what that plan allows. - Thank-you page confirms what was bought within seconds of the webhook, so the loop back to the game is immediate.


Admin and reporting
plans.write gives the billing panel: totals (all time, last 30 days), by product and month, top
spenders, passes by state, active subscriptions, credits sold and spent, promo codes redeemed, plus
paged lists of payments, refunds and raw Paddle events with filters. The same numbers feed the
Disimula billing dashboard in Grafana (see observability).