# BILL-04 ยท Mollie Payment-Gateway | | | |---|---| | **Typ** | Dev/Setup | | **Owner** | Raffael | | **Phase** | Billing-Recut nach AD-27 | | **Cycle/Fenster** | nach `BILL-02`, parallel zu `BILL-03` moeglich | | **Status** | Umgesetzt / bereit fuer Review | ## Abhaengigkeiten & Parallelitaet - **Blocked by:** Mollie-Testaccount/Testmode-Keys; `BILL-02` - **Blocks:** `BILL-05`, `BILL-07` ## Was wir bauen Mollie wird als Payment Processor angebunden. Mollie entscheidet nicht ueber Plan, Rechnung oder Entitlements; Mollie meldet nur Payment-Zustand zu einer HiveGrid-/Lago-Invoice-Referenz. ## Definition of Done - [x] Mollie-Testmode eingerichtet und Secrets ausserhalb des Repos abgelegt. - [x] Payment/Checkout fuer eine Invoice-Referenz erzeugbar. - [x] Mollie-Webhooks mit Signatur-/Authentizitaetspruefung oder dokumentierter sicherer Verifikation. - [x] Payment-Status wird idempotent verarbeitet. - [x] Refund-/Failure-/Expired-Events werden als Billing-Events gespeichert. - [x] Keine HiveGrid-Fachdaten in Mollie-Payloads. - [x] Tests fuer Webhook-Parsing, Idempotenz und Fehlerfaelle. ## Umsetzungs-Notiz 2026-07-04 Code-seitig umgesetzt: - Neues `MolliePaymentGateway` in `@hivegrid/billing` fuer `POST /v2/payments` und `GET /v2/payments/:id`. - `PaymentGateway`-Contract getrennt vom Lago-`BillingGateway`, damit Lago Billing/Invoicing bleibt und Mollie nur Payments verarbeitet. - Mollie-Payload minimiert: Betrag, Redirect-/Webhook-URL, optionale Mollie-Customer-ID und interne Referenzen (`tenantId`, `invoiceExternalId`, `paymentExternalId`). Keine Plan-/Seat-/CRM-/Kontakt-Fachdaten. - Klassische Mollie-Webhooks werden ueber `id` geparst und sicher durch API-Refetch verifiziert. Mollie liefert hier keine Legacy-Provider-aehnliche Signatur; die Verifikation ist der Abruf mit eigenem API-Key. - Idempotenter Outbox-Kontrakt `billing.mollie.payment` fuer `payment.paid`, `payment.failed`, `payment.expired`, `payment.refunded`, `payment.cancelled` und generisches `payment.refresh`. - Runtime-Konfig erweitert um `MOLLIE_API_KEY`, `MOLLIE_PROFILE_ID`, `MOLLIE_TIMEOUT_MS`; `.env.example` dokumentiert die Keys ohne Secret-Werte. Proof: - `pnpm --filter @hivegrid/billing typecheck` - `pnpm --filter @hivegrid/billing test` - `pnpm --filter @hivegrid/config test` 2026-07-04 Nachtrag: Mollie-Testmode-Key liegt lokal ausserhalb des Repos in `~/.cli-tokens/mollie` mit `0600` Rechten. Auth/Scope wurde ohne Ausgabe von Secret- oder Accountdetails gegen `GET /v2/payments?limit=1` geprueft: `payments.read` erreichbar. Damit ist der letzte DoD-Blocker geschlossen. Finaler Stand: **7/7 DoD = 100 % done**. ## Nicht im Scope - Mollie Invoicing. - Mollie als Customer-Portal-Ersatz. - Production-Live-Verifizierung. ## Technische Bausteine - `PaymentGateway`-Interface, konkrete Implementierung `MolliePaymentGateway`. - Webhook-Log analog zu bestehender Webhook-Idempotenz, aber nicht Legacy-Provider-spezifisch. - Payment-Metadata: Tenant-ID nur als interne Referenz, keine Fachdaten. ## Quellen - AD-27 - Mollie API/Testmode Docs - bestehende Legacy-Provider-Webhook-Tests als Migrationsvorlage, nicht als Zielarchitektur