Platform Billing — Behavior

State machine — platform_billing_subscriptions.status

platform_billing_status enum: active | past_due | cancelled (libs/db/src/lib/schema/enums.ts:192).

On every cancelled transition, organizations.platform_tier flips to lite in the same DB transaction.

State machine — platform_billing_transactions.status

transaction_status enum (shared with per-org payments): pending | completed | failed | cancelled. (refund_pending and refunded exist in the enum but are not used here today.)

Checkout flow (detailed)

PlatformBillingController.createCheckout → PlatformBillingService.createCheckoutSession (platform-billing.service.ts:126):

1. Role check — owner only. (:136)
2. Free tier guard — refuses tier='lite' (price=0 has no checkout). (:142)
3. Per-org advisory lock — pg_advisory_xact_lock(hashtext('platform-billing:checkout:<orgId>')) (:155). Two parallel POST /checkout calls serialise.
4. Reuse window — look up pending charges < 10 minutes old. If one matches the target tier and carries a paymentPageUrl in metadata, return it (Cardcom URLs are valid ~30min).
5. Stale cancel — mark any pending rows for other tiers as cancelled so the owner can’t accidentally pay for the wrong tier from a stale tab.
6. Cardcom call — CardcomProvider.createPaymentPage with ChargeAndCreateToken operation; reads PLATFORM_BILLING_* env directly via getPlatformCredentials().
7. Empty processId guard — :247 — Cardcom must return a LowProfileId; we refuse to persist a row with an empty provider_transaction_id (would corrupt every join).
8. Insert the pending row with metadata = { tier, orgId, paymentPageUrl }.

Webhook flow

PlatformBillingWebhookController.handleCardcomWebhook (platform-billing-webhook.controller.ts:38):

1. Reject if body lacks LowProfileId.
2. Trust nothing in the body — call adapter.getTransactionStatus(credentials, processId) to ask Cardcom for the truth.
3. Branch:
   • verification.status='completed' → handlePaymentCompleted with { ...body, verification: rawResponse } so both shapes are available for token extraction (platform-billing.service.ts:65).
   • verification.status='failed' → handlePaymentFailed.
   • Otherwise (Cardcom hasn’t finalised) → return { status: 'deferred' }; reconciler will revisit.

The handler is wrapped in a single DB transaction with SELECT … FOR UPDATE LIMIT 1 on the txn row (platform-billing.service.ts:296). State machine guards refuse any source state that isn’t pending (idempotency).

Three converging paths

All three converge on handlePaymentCompleted / handlePaymentFailed. State-machine guards make the operation idempotent regardless of which path wins.

Renewal cron

PlatformBillingRecurringService.sweep — 0 2 * * * (platform-billing-recurring.service.ts:98).

Selector (:117):

WHERE status != 'cancelled'
  AND current_period_end IS NOT NULL
  AND current_period_end <= now + 1h         -- CHARGE_LEAD_TIME_MS (negative)
ORDER BY current_period_end ASC
LIMIT 100

Per sub:

On markFailed:

• failed_payment_count += 1.
• If new count ≥ 3 → sub cancelled, org → lite, cancelReason='max-failed-payments'.
• Otherwise → sub past_due, lastFailedAt=now.
• A failed platform_billing_transactions row is inserted with amount=0 for telemetry.

Cancellation

Permissions

Idempotency

Edge cases

Side effects

There is no email on platform-billing events (FIT-tier; would be a nice-to-have). The owner sees status changes via the dashboard.