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.

Other providers (Mercado Pago and similar)

The flow is the same — create the charge server-side, fulfill on the webhook, stay idempotent — but verify these against a real payment, because sandboxes differ from production:

• Which object carries which field. A subscription event can arrive with the payer's email empty while the payment object has it. Treat empty as missing (||, not ??) and fetch the object that holds the data.
• Whether the sandbox is usable at all. Some require both parties to be test accounts. A real plan at the minimum amount is a legitimate test.
• The token's prefix. Check that a key stored as "test" is a test key before it charges anyone.
• The cancellation event may not identify the user. Store the provider's customer and subscription ids against your user at sign-up.

Subscription lifecycle (decide before launch)

• Trial: store an explicit trial_ends_at, set when the trial actually starts — not derived from created_at.
• Failed renewal: keep access while the provider is retrying; move to past_due only when it gives up.
• Resubscribe: cancel the previous subscription at the provider.
• Provisioning is idempotent: the second event for the same customer changes nothing — in particular, it does not issue new credentials.
• Conversion tracking fires once, when the account is created — not on every webhook.

Field notes

references/field-notes.md holds 16 payment failures from production apps, each with symptom, cause and what fixed it. Read it before the first real charge. The three that cost the most:

1. The first paying customer got no account, because a field was empty in one object and present in another.
2. Checkout died with a "connection" error that was a trailing newline in the secret key.
3. Trial access was measured from sign-up instead of activation, locking out people who verified late.

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).