For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /nl/docs/web/stripe-payments.md (or send Accept: text/markdown).
Stripe-betalingen toevoegen
Maak een gratis Stripe-account, een product met een terugkerende prijs, een geheime sleutel en de ondertekende webhook die entitlements na checkout verleent.
Walkthrough voor beginners
Vereisten: de app lokaal draaiend (Ship in 5 minuten) en een gemigreerde database voor echte accounts (Database instellen). U heeft een e-mailadres voor het Stripe-account nodig — geen kaart en geen kosten. Alles in deze gids gebeurt in testmodus: nepgeld, testkaartnummers, onbeperkt opnieuw proberen voor het live gaan.
Snelle begrippen: testmodus is Stripe's sandbox — de Test mode-schakelaar op het dashboard houdt elke sleutel, elk product en elke betaling nep totdat u hem uitzet. Een geheime sleutel (sk_test_…) is het wachtwoord van uw server naar Stripe. Een product met een prijs is wat klanten kopen; een price id (price_…) benoemt het in code. Een webhook is Stripe die uw server aanroept wanneer een betaling slaagt of een abonnement wijzigt, en het ondertekenende geheim (whsec_…) bewijst dat de aanroep echt van Stripe komt.
Wat u aanmaakt: een Stripe-account, één product met een terugkerende prijs, een geheime API-sleutel en een webhook-endpoint — ongeveer twintig minuten. Stripe host de checkoutpagina zelf; de kit maakt de sessie server-side aan en redirect, dus er is geen publiceerbare browsersleutel nodig.
Houd de scope in gedachten: deze gids verkoopt alleen webabonnementen. Aankopen in de iOS-/Android-app moeten via Apple- en Google-billing lopen — nooit via Stripe Checkout — en dat is waarom mobiel RevenueCat gebruikt.
Het Stripe-account aanmaken
1. Open stripe.com → Start now en meld u aan met uw e-mail.
2. De onboarding vraagt naar uw bedrijf — in testmodus kunt u elke vraag overslaan en toch de volledige sandbox gebruiken; voltooi de activatie pas voordat u echte betalingen aanneemt.
Verwacht: u landt op het dashboard met de Test mode-schakelaar zichtbaar in de header. Houd hem aan voor alles hieronder — live sleutels horen later in uw productie-geheimopslag, nooit in een env-bestand op een laptop.
De API-sleutels kopiëren
1. Open in het dashboard Developers → API keys.
2. U ziet twee testsleutels: een Publishable key pk_test_… en een gemaskeerde Secret key. Klik op Reveal test key naast de geheime en kopieer de sk_test_…-waarde.
De kit heeft alleen de geheime sleutel nodig: checkoutsessies worden op de server aangemaakt en de gebruiker wordt geredirect naar Stripe's gehoste pagina, dus er komt geen publiceerbare sleutel in env-variabelen. Als een product dat u later bouwt Stripe.js toevoegt, zou u de publiceerbare sleutel client-side gebruiken; de billingflow van de kit doet dat niet.
De sk_test_…-sleutel is een volledige credential voor het sandbox-account: die leeft in apps/web/.env.local of een geheimopslag, nooit in NEXT_PUBLIC_/EXPO_PUBLIC_-variabelen en nooit in Git.
Het product en de prijs aanmaken
1. Ga naar Product catalog → Add product.
2. Noem het naar uw plan — Pro past bij het meegeleverde plan van de kit — geef het een prijs en kies Recurring (bijvoorbeeld maandelijks): de checkout van de kit maakt sessies in subscription-modus, die een terugkerende prijs vereisen, geen eenmalige.
3. Sla op, open het product en kopieer het price id — het begint met price_… (niet prod_…, dat is het product-id).
Het meegeleverde pro-plan toont al een Monthly/Yearly-schakelaar: maandelijks checkt uit met STRIPE_PRICE_ID, en de jaarlijkse optie heeft een tweede terugkerende prijs nodig in STRIPE_PRICE_ID_PRO_YEARLY — zonder die faalt een jaarlijkse checkout met price-unconfigured. Wijzig plannamen, bedragen en wat een aankoop verleent in packages/web-core/src/product-plans.ts — Stripe bewaart de geldkant, het planbestand bewaart de entitlementkant.
Het webhook-endpoint toevoegen
De webhook is wat daadwerkelijk toegang verleent: de kit flipt de entitlement pas nadat een ondertekend Stripe-event arriveert, dus een checkout-redirect alleen bewijst niets.
1. Ga naar Developers → Webhooks → Add endpoint.
2. Endpoint URL: uw publieke URL plus /api/billing/webhook — bijvoorbeeld https://yourdomain.com/api/billing/webhook. De andere billingproviders krijgen hun eigen pad onder die directory; Stripe's ontvanger leeft in de root.
3. Kies onder Select events de events die de kit afhandelt: checkout.session.completed, checkout.session.async_payment_succeeded, checkout.session.async_payment_failed, invoice.paid, invoice.payment_failed, customer.subscription.created, customer.subscription.updated en customer.subscription.deleted.
4. Maak het endpoint aan, open de pagina, klik op Reveal onder Signing secret en kopieer de whsec_…-waarde — elk endpoint heeft zijn eigen geheim.
Lokale ontwikkeling kan Stripe's servers niet ontvangen, dus gebruik in plaats daarvan de Stripe CLI: eenmalig stripe login, dan stripe listen --forward-to localhost:3000/api/billing/webhook in een tweede terminal. Die print een tijdelijke whsec_… — die waarde, niet de dashboardwaarde, gaat in .env.local terwijl stripe listen draait.
De waarden aan de app toevoegen
Zet de regels hieronder in apps/web/.env.local. BILLING_PROVIDER=stripe selecteert de adapter; de andere drie zijn de sleutel, de prijs en het ondertekenende geheim. De provider inschakelen terwijl er een ontbreekt laat het opstarten mislukken en noemt de variabele.
Alle drie de STRIPE_*-waarden zijn server-only — nooit NEXT_PUBLIC_/EXPO_PUBLIC_, nooit gecommit; productie krijgt ze via de geheimmanager van de host (de deploymentgids behandelt Secret Manager). Herstart de devserver na het bewerken.
# apps/web/.env.local
BILLING_PROVIDER=stripe
STRIPE_SECRET_KEY=sk_test_…
STRIPE_PRICE_ID=price_…
STRIPE_WEBHOOK_SECRET=whsec_… # `stripe listen` value locally; endpoint signing secret in production
# STRIPE_PRICE_ID_PRO_YEARLY=price_… # required for the shipped Yearly toggleVerifiëren en problemen oplossen
Start stripe listen --forward-to localhost:3000/api/billing/webhook en laat het draaien, herstart de devserver, open daarna /billing, kies het Pro-plan en voltooi Stripe's gehoste checkout met de testkaart 4242 4242 4242 4242, een toekomstige vervaldatum en een willekeurige CVC.
Verwacht: de app keert terug naar /billing?checkout=success en de entitlement van de workspace flipt actief — de listen-terminal logt de afgeleverde events, en Developers → Webhooks → uw endpoint op het dashboard toont groene leveringen.
Om de ontvanger te oefenen zonder door checkout te klikken, stuurt stripe trigger checkout.session.completed een synthetisch event door de listen-forwarder.
Veelvoorkomende mislukkingen: een 400 op elke levering betekent dat het ondertekenende geheim niet bij dat endpoint past — kopieer whsec_… opnieuw voor het juiste endpoint en werk env bij; stille no-ops betekenen dat BILLING_PROVIDER nog steeds local is; en sk_live_-sleutels vermengd in een testopstelling betekenen dat u sleutels van de verkeerde modus heeft gekopieerd — houd test en live strikt gescheiden.
De kit shipt dezelfde één-contract-adapter voor Lemon Squeezy, Creem, Polar, Whop, Paddle, Dodo en PayPal — zelfde flow, andere console en env-namen — en mobiele aankopen blijven op RevenueCat, niet Stripe.