fix(payments): Comgate first checkout activation and failure policy

Persist pending payment_checkout_sessions at Comgate checkout creation
so webhooks can resolve userId/planType on first purchase. Align
payment.failed to past_due (matching GoPay). Document Comgate secrets in
AGENTS.md and update payments README to reflect the real provider.

Co-authored-by: Jakub Doboš <kubo6472@users.noreply.github.com>

Author: cursoragent

AGENTS.md

@@ -304,6 +304,9 @@ TOTP_ENCRYPTION_KEY     — AES-256-GCM encryption key for TOTP secrets
 VAPID_PRIVATE_KEY       — generated with web-push generate-vapid-keys
 GOPAY_CLIENT_ID / GOPAY_CLIENT_SECRET / GOPAY_GOID — GoPay OAuth + merchant goId (draft; see `packages/payments/README.md`)
 GOPAY_API_BASE          — optional; default sandbox `https://gw.sandbox.gopay.com/api` (prod `https://gate.gopay.cz/api`)
+COMGATE_MERCHANT / COMGATE_SECRET — Comgate merchant credentials (draft; see `packages/payments/README.md`)
+COMGATE_API_BASE        — optional; default `https://payments.comgate.cz`
+COMGATE_COUNTRY         — optional; default `CZ` (Comgate hosted gateway country)
 RSS_SECRET              — 32+ random chars used only to sign/tokenize personal account RSS URLs (`/api/feed/:userId/:token` and `/api/account/rss`); not required for the public feed endpoint (`/api/feed/public`)
 VMP_API_PIPELINE_SECRET — shared with media-pipeline for `POST /api/admin/videos/:id/pipeline-status` HLS availability callbacks
 REPLICATION_TARGET_URL — full URL to Deno ingest (`/api/internal/replication/ingest` on api-node)

packages/api/src/paymentProcessor.ts

@@ -1203,6 +1203,21 @@ export async function handleCheckout(request: any, env: any, corsHeaders: any) {
       );
     }
     if (session.checkoutUrl) {
+      if (apiProvider === 'comgate') {
+        const refId = String(session.metadata?.refId ?? '').trim();
+        const orderId = String(session.orderId ?? '').trim();
+        if (refId && orderId) {
+          await db
+            .prepare(
+              `INSERT INTO payment_checkout_sessions (
+                id, user_id, provider, plan_type, checkout_token, provider_checkout_id, status,
+                created_at, updated_at
+              ) VALUES (?, ?, 'comgate', ?, ?, ?, 'pending', CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)`,
+            )
+            .bind(crypto.randomUUID(), user.sub, planType, refId, orderId)
+            .run();
+        }
+      }
       return jsonResponse(
         {
           checkoutUrl: session.checkoutUrl,
@@ -1654,7 +1669,6 @@ export async function handleComgateWebhook(request: any, env: any, corsHeaders:
           headers: { 'Content-Type': 'application/x-www-form-urlencoded', ...corsHeaders },
         });
       }
-      // Look for existing subscription by transId or refId
       const existing = await db
         .prepare(
           `SELECT user_id, plan_type FROM subscriptions
@@ -1663,8 +1677,28 @@ export async function handleComgateWebhook(request: any, env: any, corsHeaders:
         )
         .bind(subscriptionId, purchaseId || subscriptionId)
         .first();
-      const userId = String(existing?.user_id ?? '').trim();
-      const planType = normalizePlanType(String(existing?.plan_type ?? 'monthly'));
+
+      let userId = String(existing?.user_id ?? '').trim();
+      let planType = normalizePlanType(String(existing?.plan_type ?? 'monthly'));
+      let pendingSessionId: string | null = null;
+
+      if (!userId) {
+        const pending = await db
+          .prepare(
+            `SELECT id, user_id, plan_type FROM payment_checkout_sessions
+             WHERE provider = 'comgate' AND status = 'pending'
+               AND (checkout_token = ? OR provider_checkout_id = ?)
+             LIMIT 1`,
+          )
+          .bind(purchaseId || subscriptionId, subscriptionId)
+          .first();
+        if (pending?.user_id) {
+          userId = String(pending.user_id).trim();
+          planType = normalizePlanType(String(pending.plan_type ?? planType));
+          pendingSessionId = String(pending.id ?? '').trim() || null;
+        }
+      }
+
       if (userId) {
         await upsertSubscriptionRow(db, {
           userId,
@@ -1675,6 +1709,19 @@ export async function handleComgateWebhook(request: any, env: any, corsHeaders:
           providerCustomerId: userId,
           currentPeriodEnd: periodEndIsoForPlan(planType),
         });
+        if (pendingSessionId) {
+          await db
+            .prepare(
+              `UPDATE payment_checkout_sessions
+               SET status = 'completed',
+                   provider_subscription_id = ?,
+                   completed_at = CURRENT_TIMESTAMP,
+                   updated_at = CURRENT_TIMESTAMP
+               WHERE id = ? AND status = 'pending'`,
+            )
+            .bind(subscriptionId, pendingSessionId)
+            .run();
+        }
         try {
           await syncSubscriptionNewsletter(db, userId, 'active', env);
         } catch (brevoErr) {
@@ -1695,7 +1742,7 @@ export async function handleComgateWebhook(request: any, env: any, corsHeaders:
         await db
           .prepare(
             `UPDATE subscriptions
-             SET status = 'cancelled', updated_at = CURRENT_TIMESTAMP
+             SET status = 'past_due', updated_at = CURRENT_TIMESTAMP
              WHERE provider = 'comgate' AND provider_subscription_id = ?`,
           )
           .bind(subscriptionId)
@@ -1710,7 +1757,7 @@ export async function handleComgateWebhook(request: any, env: any, corsHeaders:
             });
           }
           try {
-            await revokeOfflineLicensesForUser(db, existing.user_id, 'subscription_cancelled');
+            await revokeOfflineLicensesForUser(db, existing.user_id, 'subscription_past_due');
           } catch (offlineErr) {
             console.error('[comgate webhook] offline revoke failed', {
               userId: existing.user_id,

packages/payments/README.md

@@ -66,11 +66,33 @@ From [GoPay docs](https://doc.gopay.cz/#android-a-ios) (also tracked in [#442](h
 
 This draft therefore never promises native Apple/Google Pay; checkout always redirects to `gw_url`.
 
+## Comgate draft behaviour
+
+1. **Checkout** — `POST /api/payments/payment` creates a Comgate payment with `initRecurring=true` and returns a `redirect` URL. A pending row in `payment_checkout_sessions` (keyed by `refId` / `transId`) stores the user and plan until the webhook fires.
+2. **Webhook** — Comgate sends **POST** callbacks with a `secret` field. The Worker verifies the secret, re-fetches status via `/v1.0/status`, and resolves the paying user from the pending checkout session (first purchase) or an existing subscription row (renewals).
+3. **Cancel** — `POST /v1.0/cancel` on the stored `provider_subscription_id` (Comgate `transId`).
+4. **Failed renewal** — maps to `past_due` (same grace-period policy as GoPay), not immediate cancellation.
+
+### Comgate admin_settings (no hardcoded prices)
+
+| Key | Purpose |
+|---|---|
+| `comgate_monthly_price` / `comgate_yearly_price` / `comgate_club_price` | Plan amounts in **major** units (e.g. `199` = 199 CZK) |
+| `comgate_currency` | ISO currency, default `CZK` |
+
+Worker secrets / vars:
+
+| Name | Purpose |
+|---|---|
+| `COMGATE_MERCHANT` / `COMGATE_SECRET` | Merchant credentials |
+| `COMGATE_API_BASE` | Optional; default `https://payments.comgate.cz` |
+| `COMGATE_COUNTRY` | Optional; default `CZ` |
+| `API_URL` | Used to build webhook URL → `{API_URL}/api/payments/webhook/comgate` |
+
 ## Adding a provider
 
 1. Add `src/providers/<id>/index.ts` exporting `createXProvider(config): PaymentProvider`.
 2. Register in `src/registry.ts` `PROVIDER_FACTORIES`.
 3. Wire config in the API composition root (`packages/api/src/paymentProviders.ts`).
 4. Add webhook route `/api/payments/webhook/<id>` or dispatch by path.
-
-Comgate remains a registered stub — enable in settings only after a real implementation lands.
+5. For redirect providers without embeddable user metadata (Comgate), persist a pending `payment_checkout_sessions` row at checkout creation so webhooks can resolve the paying user.