08 — Billing (Packages)

Overview

Model: one-off purchases of event packages (Endkunden) or annual subscriptions (Reseller); see 15-packages-design.md for details.
Tables: packages, event_packages, tenant_packages, package_purchases (see 04-data-model-migrations.md and 15-packages-design.md).
Providers: Stripe (server-side checkout + webhooks for Einmalkäufe/Subscriptions), PayPal (Orders API + webhooks); store receipts and metadata.
Idempotency: purchase intents keyed by provider_id; purchase writes idempotent (check existing before create); retries safe via DB transactions.
Limits: Enforce package selection at event creation; check event-specific limits (e.g. max_photos) during usage; tenant limits for reseller event count.
SaaS Aspects: Trial periods (14 days for first reseller subscription), subscription status updates, GDPR compliance (no PII in logs/metadata, privacy consent required), cancellation links to provider dashboards.

Multi-step SPA: Package Selection → Auth (Login/Register, conditional for unauthenticated) → Payment (Stripe Elements or PayPal Buttons toggle) → Success.
Persistence: sessionStorage for state (wizardData, currentStep, timestamp with 30min TTL); restores on reload/refresh without data loss.
No reloads: Inertia.js router.post for auth/payment, onSuccess advances step client-side.
Package Details: Enhanced UI with features list (Check icons), SaaS info (annual billing, trial notice, reseller benefits, cancellation policy).
Error Handling: Backend validation errors (422) displayed via Inertia onError; frontend try-catch for API calls, toasts for user feedback.
Localization: react-i18next with /public/lang/de/en/marketing.json (e.g., payment options, errors, trial texts).

Endpoints:
- POST /api/packages: purchase (validates package_id, type, payment_method; handles free/paid).
- POST /api/packages/create-payment-intent: Stripe client_secret for card payments.
- POST /api/packages/complete-purchase: Finalizes after payment (creates PackagePurchase/TenantPackage; supports stripe/paypal provider_id).
- POST /api/packages/paypal-create: Creates PayPal Order (OrdersCreateRequest with custom_id metadata: tenant_id/package_id).
- POST /api/packages/paypal-capture: Captures Order (OrdersCaptureRequest; idempotent check, trial logic if first reseller).
Free Packages: Direct DB assignment (no payment).
Paid: Stripe PaymentIntent or PayPal Order; completePurchase in transaction.
Trial Logic: For reseller_subscription, if no active packages, set expires_at = now()->addDays(14); else full year.
Multi-Tenancy: Tenant middleware isolates data; metadata includes tenant_id.

SDK: paypal/paypal-server-sdk (composer require); Sandbox/LiveEnvironment based on config/services.php.
Flow: Frontend PayPalButtons createOrder (fetch /api/packages/paypal-create) → onApprove captureOrder (fetch /api/packages/paypal-capture) → completePurchase.
Webhooks: Dedicated PayPalWebhookController.php (route POST /api/paypal/webhook/verify, no auth).
- Verification: VerifyWebhookSignature with headers/webhook_id.
- Events: PAYMENT.CAPTURE.COMPLETED (process idempotent purchase, trial activation), BILLING.SUBSCRIPTION.CANCELLED (deactivate TenantPackage, update status to 'cancelled').
- Idempotency: Check provider_id before processing.
Config: services.php with client_id/secret/sandbox; webhook_id for verification.

SDK: stripe/stripe-php; config/services.php secret key.
Flow: Elements for card input → confirmCardPayment with client_secret → completePurchase on success.
Subscriptions: For reseller, createSubscription (setup in handlePaidPurchase); webhooks for invoice.paid (renew), customer.subscription.deleted (cancel).
Metadata: tenant_id/package_id/type for all intents/subscriptions.

Validation: Laravel Requests (e.g., package_id exists, privacy_consent); 422 JSON errors for API.
Auth: Sanctum for API; middleware('auth:sanctum', 'tenant') on purchase endpoints.
GDPR: No PII in sessionStorage/metadata; privacy consent checkbox in RegisterForm; logs anonymized (tenant_id only).
Cancellations: Success step links to provider dashboard (e.g., Stripe Customer Portal, PayPal Manage Subscriptions) based on purchase.provider.

Feature Tests: tests/Feature/PurchaseTest.php (unauth redirects, free/paid flows, Stripe/PayPal mocks, errors, trial/renewal logic, idempotency).
E2E: Playwright for wizard steps (auth without reload, persistence on refresh, payment toggles).
Coverage: Auth errors (duplicate email, wrong pass), payment failures (no assignment), limits exceeded (403).

Migrations: Add trial_days to packages if configurable; webhook routes in api.php (without auth middleware).
Monitoring: Log payment events (success/fail); alert on webhook verification fails.
Legal: Update Privacy/AGB for payment providers; receipts via email (views/emails/purchase.blade.php).