---
id: howto-tenant-package-not-active
title: How-to – Zahlung erfolgreich, Paket nicht aktiv
sidebar_label: 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 in `docs/process/changes/*` (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`.