Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/BILL-04.md
T
2026-07-08 16:15:37 +02:00

71 lines
3.1 KiB
Markdown

# 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