Before you start: create a Stripe account and grab your test keys from the Stripe Dashboard > Developers > API keys. You’ll also need a product and price ID for whatever you’re selling.
Three Paths
- AI Chat (Fastest)
- Stripe SDK (Manual)
- Stripe Elements
Ask the project AI to set it up:The AI adds env var references, installs the SDK, creates the API route, and updates the pricing page. Review before deploy.
Step 1: Add Env Vars
You need two keys, and you’ll add a third once webhooks are set up.Get your keys from Stripe
Stripe Dashboard > Developers > API keys. Start with test mode:
sk_test_...— secret key (server-side only)pk_test_...— publishable key (client-side OK)
Add them as env vars in Hiveku
See Configure Environment Variables. Use these names:
STRIPE_SECRET_KEY— server-side onlyNEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY— client-side OK
Step 2: Install the SDK
In your terminal:Step 3: Create a Checkout Session
Server-side route that creates a Stripe Checkout session:price_xxx ID from Stripe Dashboard > Products > click your product > Pricing.
Step 4: Redirect from the Buy Button
Client-side, when the user clicks “Buy”:Step 5: Set Up a Stripe Webhook
Enter your endpoint URL
Use the Hiveku URL of your webhook route:Or your custom domain if configured.
Select events to listen for
Common choices:
checkout.session.completed— one-time purchases and subscription startspayment_intent.succeeded— any successful paymentcustomer.subscription.updated— plan changes, cancellationscustomer.subscription.deleted— subscription ended
Step 6: Handle the Webhook
Server-side route that validates the signature and processes events:Test It End-to-End
Use Stripe test cards
Checkout accepts these in test mode:
4242 4242 4242 4242— successful payment4000 0000 0000 0002— generic decline4000 0000 0000 9995— insufficient funds
Check Stripe Dashboard
Payments > Test data should show the successful payment. The webhook endpoint’s Recent attempts log shows your endpoint returning 200.
Go Live
When you’re ready to accept real payments:- In Stripe Dashboard, toggle from Test mode to Live mode
- Copy the live
sk_live_...andpk_live_...keys - Update your Hiveku env vars (use different values per environment if you want staging on test, production on live)
- Re-create the webhook in live mode — live webhooks are separate from test webhooks and have a new signing secret
- Update
STRIPE_WEBHOOK_SECRETto the live value - Do a small real-money test (then refund yourself)
Troubleshooting
Webhook signature verification fails
Webhook signature verification fails
You’re almost certainly parsing the body before verifying. Use
await req.text() and pass that string to constructEvent. Also make sure STRIPE_WEBHOOK_SECRET is set correctly and matches the mode (test vs live) you’re operating in."No such price: price_xxx"
"No such price: price_xxx"
Product IDs differ between test and live modes. A price created in test mode doesn’t exist in live mode — you need to recreate products/prices in live mode, or use Stripe’s Products API to copy them over.
Redirect URL invalid
Redirect URL invalid
success_url and cancel_url must be fully-qualified URLs (including https://). /success won’t work — use ${origin}/success or hardcode the full URL.CORS errors on the Buy button fetch
CORS errors on the Buy button fetch
Webhook fires but handler doesn't run
Webhook fires but handler doesn't run
Check the deployment log for errors in the webhook handler. Common causes: typo in env var name, SDK version mismatch, an unhandled async throw. Also check that the event type you’re testing is in your
switch — Stripe logs the event type it sent, and you can see it in the Webhooks dashboard.What’s Next?
Environment Variables
Manage your Stripe keys per environment
Serverless Guide
More on API routes and webhook patterns