Stripe

The Stripe integration is for apps you build with Swarmz, not for billing your Swarmz subscription. Connect it once and the agent can scaffold pricing pages, Checkout sessions, customer portals, and webhook endpoints using your real product catalog and price IDs.

Setup

Stripe is the one integration that doesn't use OAuth. Stripe's OAuth requires a verified Connect platform, so Swarmz uses a simpler path: paste your secret key.

The key is encrypted with TOKEN_ENCRYPTION_KEY and stored as a row in workspace_connections with integration_id = "stripe". The agent retrieves it on demand to call the Stripe API on your behalf.

You can change the key anytime — useful when promoting a project from test mode to live. Click Update key on the Stripe card.

One-click test mode

If you don't want to set up a Stripe account just to play with the integration, click Use test mode setup on the Stripe card. Swarmz issues a sandbox key tied to a shared test catalog (a few sample products and prices). It's enough to scaffold the full Checkout flow end to end. When you're ready to ship, swap to your own sk_live_ key.

What the agent can do

Once connected, tell the agent what billing flow you need and it generates the code with your real product and price IDs:

Add a pricing page with three plans — Free, Pro ($10/mo),
and Business ($25/mo). Use Stripe Checkout for the paid tiers.

The agent will:

1. Read your Stripe catalog via stripe.products.list() and stripe.prices.list().
2. If the prices don't exist, create them with stripe.products.create() and stripe.prices.create().
3. Generate a /api/checkout route that creates a Checkout.Session with the right price ID and the appropriate mode (subscription for recurring, payment for one-time).
4. Generate a /api/webhook route that verifies signatures with your webhook secret and handles checkout.session.completed, invoice.paid, and customer.subscription.deleted.
5. Generate a pricing UI that links each plan's CTA to the Checkout endpoint.

You confirm the plan in the editor, hit Approve, and the code lands.

Setting up live keys

When you're ready to take real payments, swap from test to live:

The split is intentional. Keep your test key as the workspace integration credential so the agent can read your live catalog at edit time and generate code. Keep your live key as a production env var so the deployed app can charge real cards.

In your project's .env:

# Test key (used by the agent for catalog reads + dev runs)
STRIPE_SECRET_KEY=sk_test_51HxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxYz

# Webhook secret from Stripe Dashboard → Developers → Webhooks
STRIPE_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Public key shipped to the browser
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_51HxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxYz

In your production env (Vercel/Netlify):

STRIPE_SECRET_KEY=sk_live_51HxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxYz
STRIPE_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_51HxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxYz

Webhooks

The agent generates webhook handlers that verify Stripe signatures correctly. After it scaffolds the endpoint, set up the webhook in Stripe:

For local testing, use the Stripe CLI:

stripe listen --forward-to localhost:3000/api/webhook

The CLI prints a whsec_ secret to use as STRIPE_WEBHOOK_SECRET in your local env.

Common patterns

The agent reads your catalog, picks the right price IDs, and generates the right Checkout config for each.

Disconnecting

Settings → Integrations → Stripe → Disconnect removes the encrypted secret from workspace_connections. The deployed app keeps working — your production env vars are unchanged. Disconnect only stops the agent from being able to read your catalog or generate new Stripe code.

If you suspect a key has leaked, rotate the key in Stripe first (Stripe Dashboard → API keys → Roll key), then update the new key in Swarmz and your production env.