71 lines
3.1 KiB
Markdown
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
|