Disimula – A Party Game of Secret Missions

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.

FreeFiestaCreador
Players per game61230
Themesthe free variantsthe whole catalogthe whole catalog
Printable cards (PDF)no, online onlyyesyes
Custom card backs (photo, design)noyesyes
Own mission sets per game02unlimited
Games in play at once13 with a subscription10 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

ProductPrice (EUR, tax included)Type
Fiesta pass4.99one-off, one game
3 Fiesta passes11.99one-off
Creador pass (+ AI credits)9.99one-off, one game
Fiesta → Creador upgrade5.00one-off, raises one game
Fiesta yearly19.99 / yearsubscription
Creador yearly (+ monthly AI credits)39.99 / yearsubscription
10 AI credits2.99one-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 BillingSchedule when 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 a credit_transaction ledger.

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.

Payment and webhook flow

Checkout

  1. POST /billing/checkout {product} creates a Paddle transaction with the user's id in custom_data and returns its checkout URL.
  2. That URL is Paddle's default payment link, which points back at the app's /pagar page, where Paddle.js opens the checkout overlay. /pagar is the only page whose CSP allows Paddle's scripts and frames.
  3. 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_event and handled once, so Paddle's retries are harmless.

Then:

EventEffect
transaction.completedgives 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 approvalthe payment's unused passes are HELD: visible, but unusable
adjustment.* approvedunused passes revoked, credits taken back; partial refunds take back only their share
adjustment.* rejectedheld 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_limit carries limit, tier and allowed, 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.

The new game wizard: themes outside the Free plan stay visible, marked with the plan that unlocks them

The plan panel of a free game: what it allows now, and the two passes that would raise it, with their prices

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).