Payments

Payments

This skill turns an app into a SaaS that actually collects money — and does it without the classic bugs (fulfilling on the client redirect, double-granting access, unverified webhooks).

Analogy: the checkout redirect is the customer saying "I'll pay." The webhook is the bank confirming the money arrived. You ship the product when the bank confirms, not when the customer promises. Trusting the redirect is shipping on a promise.

The Stripe MCP split (read this first)

A Stripe MCP may be available (mcp__stripe__*). It is control-plane only: it creates products, prices, and payment links, and reads/updates subscriptions and customers. It cannot create Checkout Sessions or process webhooks.

So the architecture is hybrid:

• Delegate the catalog to the MCP — use it to create products, prices, and one-off payment links (the lowest-effort path for an MVP).
• Embed the integration code — Checkout Session creation, the webhook handler, and fulfillment must live in your shipped code, because the MCP can't do them.

If no MCP is present, create the catalog by hand in the Stripe dashboard or via the SDK; everything else below is identical.

Backend delegation: if you're on InsForge (see the data-modeling skill), its insforge / insforge-cli skills wire Stripe checkout, subscriptions, the customer portal, and the webhook handler for you — let them own the plumbing. The rules below still hold regardless (fulfill only on the webhook, verify the signature, stay idempotent); InsForge automates the wiring, it doesn't change what "correct" means. On Vercel/Node you write the handler yourself as shown. Never block on a missing skill.

Discovery (max 3 questions, only if unknown)

1. One-time payments, subscriptions, or both?
2. Do you want the fastest path (hosted Checkout) or a fully custom in-page card form (Elements)?
3. What's the backend for the webhook — Vercel functions, a Node server, or a BaaS?

Step 1 — Pick the integration

• Default: Stripe Checkout (hosted). Fastest, PCI-lightest. Reach for Elements only when you need a custom in-page card form.
• Zero-backend MVP: a Payment Link (creatable via mcp__stripe__create_payment_link) needs no code at all.

Step 2 — The correct flow (Checkout → webhook → fulfill)

1. Create the Checkout Session server-side (e.g. /api/checkout): pass mode: 'subscription' (or 'payment'), the price ID, success_url, cancel_url, and client_reference_id = your app's user id. Redirect the browser to session.url. The secret key never touches the client.
2. Fulfill ONLY on the checkout.session.completed webhook — never on the success redirect. A user can hit success_url without paying; the webhook is the source of truth.
3. Verify the webhook signature: stripe.webhooks.constructEvent(rawBody, sig, endpointSecret). On Vercel you must read the raw body (disable body parsing) or verification fails.
4. Make fulfillment idempotent — Stripe retries webhooks; key on event.id or the subscription id so double-delivery doesn't double-grant access.
5. Store stripe_customer_id and stripe_subscription_id on the user row.

Step 3 — Subscribe to the events that matter

• checkout.session.completed → provision access.
• customer.subscription.updated / .deleted → plan change / cancel.
• invoice.paid / invoice.payment_failed → renewals and dunning.

Step 4 — Self-serve billing

Use the Customer Portal: create a Billing Portal Session server-side and redirect. Let Stripe handle upgrades, cancels, and card updates instead of building billing UI.

Step 5 — Test before going live

stripe listen --forward-to localhost:3000/api/webhook and stripe trigger checkout.session.completed. Never ship without a real end-to-end webhook test.

Pricing model defaults

• 3 tiers (anchor / target / premium), middle one flagged "Most popular."
• Charge per value metric (seats, usage, projects), not per feature.
• Offer monthly + annual (annual ≈ 2 months free) to cut churn.
• Stripe is the catalog source of truth — set prices there, reference the IDs in code.

Output

Deliver: the integration choice, the /api/checkout and /api/webhook handlers with signature verification + idempotent fulfillment, the customer-portal redirect, the lifecycle-event handling, and the pricing tiers.

Reference

stripe-samples (checkout-single-subscription, subscription-use-cases, accept-a-payment ~800-900⭐ each, active), Stripe Customer Portal + Build-subscriptions docs, Stripe MCP (stripe/ai ~1.6k⭐), InsForge Stripe integration (agentic-native, via insforge skills).