house / Stripe Commerce Checkout

---
name: stripe-commerce-checkout
description: Build a Stripe Checkout endpoint with restricted keys, branded sessions, webhooks, and a test-first operating model.
license: MIT
tags: [stripe, commerce, checkout, payments, branding, webhooks]
agents: [claude-code, codex, cursor]
category: payments
metadata:
  version: "1.1.0"
capabilities:
  network: true
  filesystem: readwrite
  tools: [Bash, Read, Edit]
requires-secrets:
  - name: STRIPE_SECRET_KEY
    description: Server-side Stripe restricted or secret key, supplied through the deployment environment.
    required: true
  - name: STRIPE_WEBHOOK_SECRET
    description: Webhook signing secret, supplied through the deployment environment when webhooks are enabled.
    required: false
resources:
  - path: story.md
    type: file
  - path: templates/cloudflare-pages-checkout.js
    type: file
  - path: templates/stripe-app.json
    type: file
---

Stripe Commerce Checkout

Use this skill for a server endpoint that creates Stripe-hosted Checkout Sessions. Start in test mode. Live products, prices, webhooks, and sessions require an explicit current-conversation instruction authorizing the specific live mutation.

Secrets and scope

Supply STRIPE_SECRET_KEY and, where applicable, STRIPE_WEBHOOK_SECRET through the host's secret manager or local environment. Never request them in chat, put them in a repository, pass them on a command line, or print them. Prefer a project-scoped restricted key over an account-wide key.

The Stripe CLI is useful for test-mode provisioning. Keep its credentials separate from application configuration; a CLI login key is not an application secret. Set environment variables in the deployment platform and use .dev.vars or an equivalent ignored local file for local work.

Build the endpoint

1. Decide whether the offer is one-time, subscription, donation, or deposit.
2. Accept only a documented offerId from the browser. Resolve its Stripe Price ID, product display data, quantity, and metadata from a server-side allowlist; never accept amounts, price IDs, product names, quantities, client reference IDs, or arbitrary metadata from the browser.
3. Start from templates/cloudflare-pages-checkout.js; wire its fail-closed authenticated-user adapter to the application's server-side session, then configure its server-side offer map. It creates a Checkout Session using STRIPE_SECRET_KEY and returns { id, url } for the newly created session.
4. Apply non-secret branding through branding_settings. Session branding does not replace account-level legal, receipt, Link, or portal branding; verify those in the Stripe Dashboard.
5. For subscriptions, add a verified webhook and a user-return reconciliation path. The webhook remains the source of truth; reconciliation is only a fast path after a user returns from Checkout.
6. Verify a new test-mode session after every endpoint or branding change. Existing session URLs are not a reliable test of a new deployment.

Webhooks and portal

Verify the Stripe signature using STRIPE_WEBHOOK_SECRET before changing entitlement or subscription state. Make handlers idempotent. On a Checkout return, retrieve the session server-side and verify that its client reference or metadata belongs to the authenticated user; never trust a browser-submitted customer or subscription ID.

Billing Portal branding is account-level, unlike Checkout Session branding. A distinct product may need a distinct Stripe account if the portal must have separate global branding.

Stripe App route

Stripe does not offer an API that mints new API keys. If installed accounts need a project-scoped key, use a reviewed Stripe App configuration such as templates/stripe-app.json, request the narrowest permissions possible, and let the account owner approve the install. Do not automate credential creation outside Stripe's supported flow.

Safety rules

• Default all mutations to test mode.
• Treat a configured live key as configuration, not authorization.
• Never expose a secret key or webhook secret in client code, logs, commits, or reports.
• Validate server-side ownership before granting access after Checkout.
• Report secret names and test evidence, never secret values.

Why

Payments code should make the safe path the default and make the expensive path impossible to mistake for a dry run.

How

Validate offers on the server, use environment-provided restricted keys, test Checkout before live mode, and verify webhook ownership before granting anything. The account dashboard still owns account-wide branding.

Related

Use Cloudflare Commerce Deploy for delivery and Clerk + Cloudflare Commerce Bootstrap for the larger app shape.