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

3.1 KiB

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

  • Mollie-Testmode eingerichtet und Secrets ausserhalb des Repos abgelegt.
  • Payment/Checkout fuer eine Invoice-Referenz erzeugbar.
  • Mollie-Webhooks mit Signatur-/Authentizitaetspruefung oder dokumentierter sicherer Verifikation.
  • Payment-Status wird idempotent verarbeitet.
  • Refund-/Failure-/Expired-Events werden als Billing-Events gespeichert.
  • Keine HiveGrid-Fachdaten in Mollie-Payloads.
  • 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