Skip to content
supastack
Browse documentation
WebNext.js

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 /docs/web/setup-payments.md (or send Accept: text/markdown).

Set up payments

Pick a billing adapter and wire its signed webhook to entitlements.

Ask about this guide
Open in

Setup and configuration

Before any step, read Before you start and Terminal basics. These instructions assume you opened the full supastack monorepo in VS Code; its root package.json marks the repository root. In pnpm commands, a workspace package is an app or shared-code folder; in the product, a workspace is a team's data container and security boundary. corepack pnpm --filter ... selects one package from the monorepo while commands run from its root. If you opened only a synced mobile or desktop folder, it does not contain the Web backend, Docker setup, or root scripts: run the backend from this monorepo or a reachable hosted server, and use the platform folder's own scripts. An environment variable is a named setting stored in a local .env file or your hosting dashboard; restart the relevant app after changing it, and keep server secrets out of NEXT_PUBLIC_ and EXPO_PUBLIC_ values.

1. Open apps/web/.env.local and keep BILLING_PROVIDER=local while learning the checkout screen.

2. For a real integration, create test-mode products in one provider, then add its server keys and webhook secret to the Web host's private environment settings. A webhook is a signed message the billing service sends to your app after checkout, renewal, or cancellation; the endpoint path is listed in this guide's code example.

3. Start Web with corepack pnpm --filter @supastack/web dev and test only the sandbox. Expected: a verified webhook updates the signed-in workspace's entitlement; opening a checkout page alone does not grant access.

Use sandbox/test credentials while integrating. Configure BILLING_PROVIDER plus the provider's server-only secrets: 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 for the 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). The price/product must represent the intended recurring subscription.

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

Commands to copy

Follow the comments to see which folder a command runs in. If two terminals are labeled, open two terminal windows and keep the first command running while you use the second.

corepack pnpm --filter @supastack/web dev

Implementation workflow

Follow the lifecycle event list in docs/real-provider-smoke.md when configuring the webhook endpoint. Signature verification requires the endpoint's matching webhook secret. A checkout redirect alone must never grant access.

The entitlement at the server action boundary decides whether paid work is permitted. Process repeated events safely and scope customer/subscription records to the correct workspace. Web checkout remains separate from native purchases.

The key a plan grants is product vocabulary shared across surfaces: ProductPlan.entitlement in src/product-plans.ts declares the lowercase machine key written into the ledger while a plan is paid (the kit ships 'ai.reference-task' on pro and lifetime; src/billing-runtime.ts passes it to the BFF). The same key is what a CMS entry's required_entitlement field and the EntitlementGate component's entitlementKey prop equality-compare against — an entry gated on 'ai.reference-task' unlocks for any workspace holding that grant, while a key no plan grants stays locked for everyone.

Verification and troubleshooting

If a webhook is rejected, compare the exact sandbox URL and signing secret in the provider dashboard with the server settings, and check whether that provider requires forwarding requests to localhost. If checkout works but access stays locked, inspect the webhook result and the entitlement key on the plan. Never test with live payment credentials while following this local guide.

Test activation, updates, cancellation, invalid signatures, and repeated events in the sandbox. Inspect persisted access state after processing. Creating an unconsumed checkout session proves connectivity only, not lifecycle fulfillment.

If you want to continue setup, read Set up email.

Frequently asked questions

14 questions

What is supastack?

supastack is a modular foundation for building AI-powered SaaS products. It brings together common infrastructure so you can focus on product-specific features.

Does it support web and mobile?

Yes. supastack includes Next.js and Expo apps as starting points for web and mobile experiences.

What authentication is included?

Better Auth covers email OTP, magic-link, and social sign-in; email/password stays available at the API layer and through the Auth.js credentials engine for products that need it. Personal workspaces are provisioned with the account so product records stay scoped from day one.

How does it support AI?

supastack includes configurable multi-provider AI, usage tracking, budgets, and encrypted bring-your-own-key support.

How are subscriptions handled?

For products built on the kit, Stripe billing, subscriptions, and entitlements form the paid-access foundation. Provider secrets stay server-only.

Where does my product-specific code live?

Product-specific features remain in a separate codebase while the product configures and integrates supastack’s foundation modules.

How does supastack pricing work?

The kit is a one-time purchase with lifetime updates: One Platform at $249 (temporary launch price, $100 off the regular $349) — your pick of Next.js (Web), Expo (iOS & Android), or Tauri (macOS & Windows Desktop) — or the All Platforms Bundle at $499 (temporary launch price, $100 off the regular $599) with every platform and the full monorepo, plus $75 per extra developer seat. No kit subscription. Checkout on this site delivers your license key by email, with repository access via GitHub invite.

How do workspaces scope my data?

User-owned records are scoped by workspaceId. Identity, entitlements, AI usage, billing events, and audit entries stay inside the personal workspace boundary.

How do background jobs work?

Trigger.dev is the explicit job runtime. The JobRunner contract only promises enqueue, status, and cancel—workflow semantics stay Trigger.dev-specific and explicit.

How is email different from outreach?

Transactional email covers product workflows such as completion notices. Cold outreach and campaigns are product concerns outside this kit’s email module.

How do mobile purchases work?

Mobile includes native purchases and restore through RevenueCat, with access verified by your server. Configure the store accounts and complete device testing before release. Web billing remains separate.

Where do AI provider keys live?

Bring-your-own-key credentials are encrypted and stay server-only. Keys are redacted from logs; usage and budgets remain visible at the workspace level.

Which payment methods does checkout accept?

The Stripe-hosted checkout accepts cards and can also offer Alipay and WeChat Pay once those wallets are enabled on the Stripe account — handy for buyers in China. Wallet authorizations confirm asynchronously, so the license page updates as soon as the payment clears.

Can I get a refund?

After you've got access to the repository, supastack is yours forever, so it cannot be refunded. But rest assured, you get the complete source code with lifetime updates to build and ship unlimited products for yourself or clients. You just cannot resell the code or redistribute the repository as a starter kit or template.

EN
Theme