Zahlungen einrichten

Einrichtung und Konfiguration

Lesen Sie vor jedem Schritt Bevor Sie beginnen und Terminal-Grundlagen. Bei diesen Anweisungen wird davon ausgegangen, dass Sie das vollständige Supastack-Monorepo in VS Code geöffnet haben. Sein Stamm package.json markiert den Repository-Stamm. In pnpm-Befehlen ist ein Arbeitsbereichspaket eine App oder ein Ordner mit gemeinsam genutztem Code. Im Produkt ist ein Arbeitsbereich der Datencontainer und die Sicherheitsgrenze eines Teams. corepack pnpm --filter ... wählt ein Paket aus dem Monorepo aus, während Befehle von seinem Stammverzeichnis aus ausgeführt werden. Wenn Sie nur einen synchronisierten Mobil- oder Desktop-Ordner geöffnet haben, enthält dieser weder das Web-Backend, Docker-Setup noch Root-Skripte: Führen Sie das Backend von diesem Monorepo oder einem erreichbaren gehosteten Server aus und verwenden Sie die eigenen Skripte des Plattformordners. Eine Umgebungsvariable ist eine benannte Einstellung, die in einer lokalen .env-Datei oder Ihrem Hosting-Dashboard gespeichert ist; Starten Sie die entsprechende App neu, nachdem Sie sie geändert haben, und halten Sie Servergeheimnisse von den Werten NEXT_PUBLIC_ und EXPO_PUBLIC_ fern.

1. Öffnen Sie apps/web/.env.local und behalten Sie BILLING_PROVIDER=local beim Lernen des Checkout-Bildschirms.

2. Für eine echte Integration erstellen Sie Produkte im Testmodus bei einem Anbieter und fügen dann dessen Serverschlüssel und Webhook-Geheimnis zu den privaten Umgebungseinstellungen des Webhosts hinzu. Ein Webhook ist eine signierte Nachricht, die der Abrechnungsdienst nach dem Auschecken, Erneuern oder Stornieren an Ihre App sendet. Der Endpunktpfad ist im Codebeispiel dieses Handbuchs aufgeführt.

3. Starten Sie Web mit corepack pnpm --filter @supastack/web dev und testen Sie nur die Sandbox. Erwartet: Ein verifizierter Webhook aktualisiert die Berechtigung des angemeldeten Arbeitsbereichs; Das alleinige Öffnen einer Checkout-Seite gewährt keinen Zugriff.

Verwenden Sie während der Integration Sandbox- oder Test-Zugangsdaten. Konfigurieren Sie BILLING_PROVIDER und die serverseitigen Secrets des Anbieters: stripe → STRIPE_SECRET_KEY, STRIPE_PRICE_ID, STRIPE_WEBHOOK_SECRET; lemonsqueezy → LEMONSQUEEZY_API_KEY, LEMONSQUEEZY_STORE_ID, LEMONSQUEEZY_VARIANT_ID, LEMONSQUEEZY_WEBHOOK_SECRET; creem → CREEM_API_KEY, CREEM_PRODUCT_ID, CREEM_WEBHOOK_SECRET (CREEM_TEST_MODE=true für die Sandbox); polar → POLAR_ACCESS_TOKEN, POLAR_PRODUCT_ID, POLAR_WEBHOOK_SECRET (POLAR_SERVER); whop → WHOP_API_KEY, WHOP_PLAN_ID, WHOP_WEBHOOK_SECRET; paddle → PADDLE_API_KEY, PADDLE_PRICE_ID, PADDLE_WEBHOOK_SECRET (PADDLE_ENVIRONMENT); dodo → DODO_PAYMENTS_API_KEY, DODO_PRODUCT_ID, DODO_PAYMENTS_WEBHOOK_KEY (DODO_PAYMENTS_ENVIRONMENT); paypal → PAYPAL_CLIENT_ID, PAYPAL_CLIENT_SECRET, PAYPAL_PLAN_ID, PAYPAL_WEBHOOK_ID (PAYPAL_ENVIRONMENT). Der Preis oder das Produkt muss dem vorgesehenen wiederkehrenden Abonnement entsprechen.

Webhook endpoint: /api/billing/webhook (stripe), /api/billing/webhook/lemonsqueezy, /api/billing/webhook/creem, /api/billing/webhook/polar, /api/billing/webhook/whop, /api/billing/webhook/paddle, /api/billing/webhook/dodo, /api/billing/webhook/paypal
Checkout endpoint: /api/billing/checkout
Portal endpoint: /api/billing/portal

Befehle zum Kopieren

Befolgen Sie die Kommentare, um zu sehen, in welchem Ordner ein Befehl ausgeführt wird. Wenn zwei Terminals gekennzeichnet sind, öffnen Sie zwei Terminalfenster und lassen Sie den ersten Befehl laufen, während Sie den zweiten verwenden.

corepack pnpm --filter @supastack/web dev

Implementierungsablauf

Folgen Sie beim Konfigurieren des Webhook-Endpunkts der Liste der Lifecycle-Ereignisse in docs/real-provider-smoke.md. Für die Signaturprüfung ist das zugehörige Webhook-Secret des Endpunkts erforderlich. Eine Checkout-Weiterleitung darf allein niemals Zugriff gewähren.

Die Berechtigung an der serverseitigen Aktionsgrenze entscheidet, ob kostenpflichtige Arbeit zulässig ist. Verarbeiten Sie wiederholte Ereignisse sicher und ordnen Sie Kunden- und Abonnementdatensätze dem richtigen Workspace zu. Web-Checkout bleibt von nativen Käufen getrennt.

Der von einem Plan gewährte Schlüssel ist ein produktübergreifender Produktbegriff: ProductPlan.entitlement in src/product-plans.ts legt den kleingeschriebenen maschinenlesbaren Schlüssel fest, der während eines kostenpflichtigen Plans ins Ledger geschrieben wird (das Kit liefert 'ai.reference-task' für pro und lifetime mit; src/billing-runtime.ts übergibt ihn an den BFF). Derselbe Schlüssel wird mit dem Feld required_entitlement eines CMS-Eintrags und der entitlementKey-Prop von EntitlementGate verglichen — ein Eintrag mit dem Gate 'ai.reference-task' wird für jeden Workspace mit dieser Berechtigung freigeschaltet; ein Schlüssel, den kein Plan gewährt, bleibt für alle gesperrt.

Überprüfung und Fehlerbehebung

Wird ein Webhook abgelehnt, vergleichen Sie die genaue Sandbox-URL und das Signaturgeheimnis im Anbieter-Dashboard mit den Servereinstellungen. Prüfen Sie, ob der Anbieter eine Weiterleitung von Anfragen an localhost benötigt. Funktioniert der Checkout, bleibt der Zugriff aber gesperrt, prüfen Sie das Webhook-Ergebnis und den Berechtigungsschlüssel des Tarifs. Verwenden Sie für diesen lokalen Leitfaden niemals Live-Zahlungsdaten.

Testen Sie Aktivierung, Änderungen, Kündigung, ungültige Signaturen und wiederholte Ereignisse in der Sandbox. Prüfen Sie nach der Verarbeitung den gespeicherten Zugriffszustand. Eine Checkout-Sitzung zu erstellen, die nicht abgeschlossen wird, belegt nur die Verbindung, nicht die vollständige Abwicklung des Lifecycle.