fotospiel-app/docs/ops/howto-tenant-package-not-active.md

id, title, sidebar_label

id	title	sidebar_label
howto-tenant-package-not-active	How-to – Zahlung erfolgreich, Paket nicht aktiv	Zahlung ok, Paket nicht aktiv

Dieses How‑to beschreibt, wie du vorgehst, wenn ein Tenant meldet: „Zahlung war erfolgreich, aber mein Paket ist nicht aktiv / Galerie bleibt limitiert.“

1. Informationen vom Tenant einsammeln

Bevor du nachschaust:

• Tenant‑ID oder Tenant‑Slug.
• Betroffenes Paket (Name oder Beschreibung, z.B. „Pro‑Paket 79 €“).
• Zeitpunkt der Zahlung (Datum/Uhrzeit, ggf. Screenshot).
• Ggf. Auszug aus der Paddle‑Bestätigung (ohne vollständige Kartendaten!).

Diese Infos erlauben dir, die korrekte Transaktion sowohl in Paddle als auch im Backend zu finden.

2. Paddle-Status prüfen

1. Im Paddle‑Dashboard:
   • Suche nach E‑Mail, Tenant‑Name oder dem vom Tenant genannten Transaktions‑Identifier.
   • Stelle sicher, dass die Zahlung dort als „completed“/„paid“ markiert ist.
2. Notiere:
   • Paddle‑Transaction‑ID und ggf. Checkout‑ID.
   • Status (paid/processing/failed/cancelled).

Wenn Paddle die Zahlung nicht als erfolgreich zeigt, ist dies primär ein Finance‑/Customer‑Topic – ggf. mit Customer Support klären, ob eine neue Zahlung oder Klärung mit dem Kunden notwendig ist.

3. Backend-Status prüfen

Mit bestätigter Zahlung in Paddle:

1. checkout_sessions:
   • Suche nach Sessions des Tenants (tenant_id) mit dem betroffenen package_id:
     • Achte auf status (erwartet completed) und provider = paddle.
     • Prüfe provider_metadata auf paddle_last_event, paddle_status, paddle_checkout_id.
   • Wenn du die Session über Paddle‑Metadaten finden möchtest:
     • paddle_checkout_id aus dem Webhook/Provider‑Metadata oder transaction_id verwenden.
2. package_purchases:
   • Prüfe, ob ein Eintrag für (tenant_id, package_id) mit passender Provider‑Referenz existiert:
     • z.B. provider = 'paddle', provider_id = Transaction‑ID.
3. tenant_packages:
   • Prüfe, ob es einen aktiven Eintrag für (tenant_id, package_id) gibt:
     • active = 1, expires_at in der Zukunft.

4. Webhook-/Verarbeitungsstatus untersuchen

Wenn checkout_sessions noch nicht auf completed steht oder tenant_packages nicht aktualisiert wurden:

1. Logs prüfen:
   • storage/logs/laravel.log und ggf. billing‑Channel.
   • Suche nach Einträgen von PaddleWebhookController / CheckoutWebhookService rund um den Zahlungszeitpunkt.
2. Typische Ursachen:
   • Webhook nicht zugestellt (Netzwerk/SSL).
   • Webhook konnte die Session nicht auflösen ([CheckoutWebhook] Paddle session not resolved).
   • Idempotenz‑Lock (Paddle lock busy) hat dazu geführt, dass Event nur teilweise verarbeitet wurde.

5. Korrektur-Schritte

5.1 Automatischer Replay (empfohlen)

1. Im Paddle‑Dashboard:
   • Den betreffenden transaction.*‑Event finden.
   • Webhook‑Replay auslösen.
2. In den Logs beobachten:
   • Ob CheckoutWebhookService::handlePaddleEvent() diesmal die Session findet und CheckoutAssignmentService::finalise() ausführt.
3. Nochmal checkout_sessions und tenant_packages prüfen:
   • Session sollte auf completed stehen, Paket aktiv sein.

5.2 Manuelle Korrektur (Notfall)

Nur anwenden, wenn klare Freigabe vorliegt und Paddle die Zahlung eindeutig als erfolgreich listet.

1. tenant_packages aktualisieren:
   • Entweder neuen Eintrag anlegen oder bestehenden für (tenant_id, package_id) so setzen, dass:
     • active = 1,
     • purchased_at und expires_at zu Paddle‑Daten passen.
2. package_purchases ergänzen:
   • Sicherstellen, dass die Zahlung als Zeile mit provider = 'paddle', provider_id = Transaction‑ID und passender price existiert (für spätere Audits).
3. Konsistenz prüfen:
   • Admin UI für Tenant öffnen und prüfen, ob Limits/Paketstatus jetzt korrekt angezeigt werden.
4. Dokumentation:
   • Den Vorgang im Ticket oder als bd-Issue (falls wiederkehrend) dokumentieren.

6. Kommunikation mit dem Tenant

• Sobald der Backend‑Status korrigiert ist:
  • Kurz bestätigen, dass das Paket aktiv ist und welche Auswirkungen das hat (z.B. neue Limits, verlängerte Galerie).
• Falls Paddle die Zahlung nicht als erfolgreich führt:
  • Ehrlich kommunizieren, dass laut Zahlungsprovider noch keine endgültige Zahlung vorliegt und welche Optionen es gibt (z.B. neue Zahlung, Klärung mit Bank/Kreditkarte).

Dieses How‑to sollte dem Support/On‑Call helfen, den gängigsten Billing‑Fehlerfall strukturiert abzuarbeiten. Für tiefere Ursachenanalysen siehe docs/ops/billing-ops.md.