Stripe yapılandırması ve webhook'lar

Kurulum ve yapılandırma

Herhangi bir adımdan önce, Başlamadan önce ve Terminal temelleri bölümlerini okuyun. Bu talimatlar, supastack monorepo'nun tamamını VS Kodunda açtığınızı varsayar; kök package.json dosyası depo kökünü işaretler. pnpm komutlarında çalışma alanı paketi bir uygulama veya paylaşılan kod klasörüdür; Üründe çalışma alanı, ekibin veri taşıyıcısı ve güvenlik sınırıdır. corepack pnpm --filter ... komutlar kökünden çalıştırılırken monorepodan bir paket seçer. Yalnızca senkronize edilmiş bir mobil veya masaüstü klasörü açtıysanız, Web arka ucunu, Docker kurulumunu veya kök komut dosyalarını içermez: arka ucu bu monorepodan veya erişilebilir bir barındırılan sunucudan çalıştırın ve platform klasörünün kendi komut dosyalarını kullanın. Ortam değişkeni, yerel bir .env dosyasında veya barındırma kontrol panelinizde depolanan adlandırılmış bir ayardır; İlgili uygulamayı değiştirdikten sonra yeniden başlatın ve sunucu sırlarını NEXT_PUBLIC_ ve EXPO_PUBLIC_ değerlerinin dışında tutun.

1. Ödeme ekranını öğrenirken apps/web/.env.local'yi açın ve BILLING_PROVIDER=local'yi koruyun.

2. Gerçek bir entegrasyon için, tek bir sağlayıcıda test modu ürünleri oluşturun, ardından sunucu anahtarlarını ve webhook sırrını Web ana bilgisayarının özel ortam ayarlarına ekleyin. Web kancası, ödeme, yenileme veya iptal sonrasında faturalandırma hizmetinin uygulamanıza gönderdiği imzalı bir mesajdır; uç nokta yolu bu kılavuzun kod örneğinde listelenmiştir.

3. Web'i corepack pnpm --filter @supastack/web dev ile başlatın ve yalnızca sanal alanı test edin. Beklenen: Doğrulanmış bir web kancası, oturum açılmış çalışma alanının yetkilerini günceller; Yalnızca ödeme sayfasını açmak erişim izni vermez.

Entegrasyon sırasında korumalı alan/test kimlik bilgilerini kullanın. BILLING_PROVIDER'yi ve sağlayıcının yalnızca sunucuya özel sırlarını yapılandırın: şerit → STRIPE_SECRET_KEY, STRIPE_PRICE_ID, STRIPE_WEBHOOK_SECRET; limon suyu → LEMONSQUEEZY_API_KEY, LEMONSQUEEZY_STORE_ID, LEMONSQUEEZY_VARIANT_ID, LEMONSQUEEZY_WEBHOOK_SECRET; creem → CREEM_API_KEY, CREEM_PRODUCT_ID, CREEM_WEBHOOK_SECRET (korumalı alan için CREEM_TEST_MODE=true); kutupsal → POLAR_ACCESS_TOKEN, POLAR_PRODUCT_ID, POLAR_WEBHOOK_SECRET (POLAR_SERVER); vay → WHOP_API_KEY, WHOP_PLAN_ID, WHOP_WEBHOOK_SECRET; kürek → 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). Fiyat/ürün, amaçlanan yinelenen aboneliği temsil etmelidir.

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

Kopyalanacak komutlar

Bir komutun hangi klasörde çalıştığını görmek için yorumları takip edin. İki terminal etiketlenmişse, iki terminal penceresi açın ve ikincisini kullanırken ilk komutu çalışır durumda tutun.

corepack pnpm --filter @supastack/web dev

Uygulama iş akışı

Webhook uç noktasını yapılandırırken docs/real-provider-smoke.md içindeki yaşam döngüsü olay listesini izleyin. İmza doğrulaması, uç noktanın eşleşen webhook sırrını gerektirir. Tek başına checkout yönlendirmesi asla erişim vermemelidir.

Sunucu eylem sınırındaki yetkilendirme, ücretli işe izin verilip verilmeyeceğine karar verir. Tekrarlanan olayları güvenli işleyin ve müşteri/abonelik kayıtlarını doğru çalışma alanına sınırlayın. Web checkout, yerel satın alımlardan ayrı kalır.

Bir planın sağladığı anahtar, yüzeyler arasında paylaşılan ürün sözlüğüdür: src/product-plans.ts dosyasındaki ProductPlan.entitlement, bir plan ödenirken deftere yazılan küçük harfli makine anahtarını bildirir (kit, pro ve ömür boyu 'ai.reference-task'ı gönderir; src/billing-runtime.ts bunu BFF'ye iletir). Aynı anahtar, bir CMS girişinin zorunlu_entitlement alanı ve EntitlementGate bileşeninin entitlementKey prop eşitlik karşılaştırmasıyla karşılaştırılır - 'ai.reference-task' üzerinde kapılanan bir giriş, bu izni tutan herhangi bir çalışma alanının kilidini açarken, hiçbir planın vermediği bir anahtar herkes için kilitli kalır.

Doğrulama ve sorun giderme

Bir web kancası reddedilirse, sağlayıcı kontrol panelindeki tam sanal alan URL'yi ve imzalama sırrını sunucu ayarlarıyla karşılaştırın ve sağlayıcının isteklerin localhost'ye iletilmesini gerektirip gerektirmediğini kontrol edin. Ödeme çalışıyor ancak erişim kilitli kalıyorsa webhook sonucunu ve plandaki yetki anahtarını inceleyin. Bu yerel kılavuzu takip ederken asla canlı ödeme kimlik bilgileriyle test etmeyin.

Sanal ortamda etkinleştirme, güncellemeler, iptal, geçersiz imzalar ve tekrarlanan olayları test edin. İşleme sonrası kalıcı erişim durumunu inceleyin. Tüketilmemiş checkout oturumu oluşturmak yalnızca bağlanabilirliği kanıtlar, yaşam döngüsü tamamlanmasını değil.