stripe-payments
Skill4 starsChanged 6 months agoMITView on GitHub
Integrate Stripe payments into the app — products, prices, checkout sessions, webhooks, customer portal, and subscription management. Use when setting up payments from scratch, adding a new product/plan, configuring webhooks, or debugging payment flows.
- Reads credentials
- Installs packages
4 other projects use a version of this.
Adopted by
Most recently taken up by
- sadrmanesh/commerce-agent-skillstheir own version, first seen Nov 16, 2026
- peterbamuhigire/chwezi-dev-enginetheir own version, first seen Nov 15, 2026
- hewi333/Mom-n-Pop-Skillstheir own version, first seen Jun 30, 2026
- cohen-liel/hivemindtheir own version, first seen Mar 17, 2026
Other versions4 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 4
- hewi333/Mom-n-Pop-Skills★ 121same name
- cohen-liel/hivemind★ 108same name
- peterbamuhigire/chwezi-dev-engine★ 31same name
- sadrmanesh/commerce-agent-skills★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository16 other files it gives its agents.
- AGENTS.mdAGENTS.md
- apple-appstore-setupSkill
- eas-mobile-deploymentSkill
- edge-functionsSkill
- frontend-developmentSkill
- google-play-setupSkill
- langfuse-tracingSkill
- mobile-developmentSkill
- posthog-analyticsSkill
- push-notificationsSkill
- revenuecatSkill
- sentry-integrationSkill
- social-auth-setupSkill
- supabase-email-templatesSkill
- template-releaseSkill
- template-upgradeSkill
The file
We split this skill into the rules it gives an agent
2 rules. 0 are common, 2 are distinctive, and 0 are very specific to this project.
0
Common
Most of the 4 edited versions we read keep these.
2
Distinctive
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 14
Never put the Stripe secret key in frontend or mobile code.
- Distinctive: line 50
Create products in the Stripe dashboard or via CLI.
“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Stripe Payments
Stack
- Stripe SDK (server-side): Supabase Edge Functions handle all Stripe API calls
- Stripe.js (client-side): Frontend and mobile use Stripe's hosted checkout or
@stripe/stripe-react-native - Webhooks: Stripe → Edge Function → Supabase DB (source of truth for subscription state)
Never put the Stripe secret key in frontend or mobile code. Only the publishable key goes client-side.
Setup
Install dependencies
# Frontend
cd frontend && npm install @stripe/stripe-js @stripe/react-stripe-js
# Mobile
cd mobile && npx expo install @stripe/stripe-react-nativeEnvironment variables
# supabase/functions/.env.local
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
# frontend/.env.local
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
# mobile/.env.local
EXPO_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...Get keys from dashboard.stripe.com/test/apikeys.
Products and Prices
Create products in the Stripe dashboard or via CLI. Products represent what you sell; prices represent how much and how often.
Stripe Dashboard (manual, recommended for first setup)
- dashboard.stripe.com/products → Add product
- Fill in name, description, image
- Add pricing:
- One-time: flat amount
- Recurring: monthly/annual, amount
- Copy the Price ID (
price_...) — you'll reference this in code
Via Stripe CLI (scriptable)
stripe products create --name="Pro Plan" --description="Full access"
stripe prices create \
--product=prod_xxx \
--unit-amount=999 \
--currency=usd \
--recurring[interval]=monthEdge Function: Create Checkout Session
// supabase/functions/create-checkout/index.ts
import Stripe from "npm:stripe@14";
import { createClient } from "npm:@supabase/supabase-js@2";
const stripe = new Stripe(Deno.env.get("STRIPE_SECRET_KEY")!);
Deno.serve(async (req) => {
const { priceId, userId, returnUrl } = await req.json();
const session = await stripe.checkout.sessions.create({
mode: "subscription", // or "payment" for one-time
line_items: [{ price: priceId, quantity: 1 }],
success_url: `${returnUrl}?session_id={CHECKOUT_SESSION_ID}`,
cancel_url: returnUrl,
metadata: { userId }, // passed back in webhook
allow_promotion_codes: true,
billing_address_collection: "auto",
});
return new Response(JSON.stringify({ url: session.url }));
});Redirect the user to session.url — Stripe handles the entire payment flow.
Edge Function: Webhooks
Webhooks are how Stripe tells your app about payment events. This is the source of truth — never trust client-side "payment successful" redirects.
// supabase/functions/stripe-webhook/index.ts
import Stripe from "npm:stripe@14";
import { createClient } from "npm:@supabase/supabase-js@2";
const stripe = new Stripe(Deno.env.get("STRIPE_SECRET_KEY")!);
const webhookSecret = Deno.env.get("STRIPE_WEBHOOK_SECRET")!;
Deno.serve(async (req) => {
const signature = req.headers.get("stripe-signature")!;
const body = await req.text();
let event: Stripe.Event;
try {
event = stripe.webhooks.constructEvent(body, signature, webhookSecret);
} catch {
return new Response("Invalid signature", { status: 400 });
}
const supabase = createClient(
Deno.env.get("PUBLIC_SUPABASE_URL")!,
Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
);
switch (event.type) {
case "checkout.session.completed": {
const session = event.data.object as Stripe.CheckoutSession;
const userId = session.metadata?.userId;
await supabase.from("subscriptions").upsert({
user_id: userId,
stripe_customer_id: session.customer as string,
stripe_subscription_id: session.subscription as string,
status: "active",
});
break;
}
case "customer.subscription.updated":
case "customer.subscription.deleted": {
const sub = event.data.object as Stripe.Subscription;
await supabase.from("subscriptions")
.update({ status: sub.status })
.eq("stripe_subscription_id", sub.id);
break;
}
}
return new Response(JSON.stringify({ received: true }));
});Key events to handle:
checkout.session.completed— user paid, activate subscriptioncustomer.subscription.updated— plan changed, update statuscustomer.subscription.deleted— cancelled, downgrade accessinvoice.payment_failed— payment failed, notify user
Webhook Setup
Local development
# Install Stripe CLI
brew install stripe/stripe-cli/stripe
# Login
stripe login
# Forward webhooks to local edge function
stripe listen --forward-to http://localhost:54321/functions/v1/stripe-webhook
# Copy the webhook signing secret printed by the CLI → STRIPE_WEBHOOK_SECRET in .env.localProduction
- dashboard.stripe.com/webhooks → Add endpoint
- Endpoint URL:
https://YOUR_PROJECT.supabase.co/functions/v1/stripe-webhook - Events to send:
checkout.session.completed,customer.subscription.updated,customer.subscription.deleted,invoice.payment_failed - Copy Signing secret (
whsec_...) → add to Supabase secrets:
supabase secrets set STRIPE_WEBHOOK_SECRET=whsec_...Customer Portal
Let users manage their subscription (cancel, update payment method, change plan):
// supabase/functions/create-portal-session/index.ts
const session = await stripe.billingPortal.sessions.create({
customer: stripeCustomerId, // from your subscriptions table
return_url: returnUrl,
});
return new Response(JSON.stringify({ url: session.url }));Enable and configure the portal: dashboard.stripe.com/settings/billing/portal
- Set which plans users can switch to
- Enable/disable cancellation
- Configure cancellation flow (survey, retention offers)
Database Schema
create table subscriptions (
id uuid primary key default gen_random_uuid(),
user_id uuid references auth.users not null,
stripe_customer_id text unique,
stripe_subscription_id text unique,
stripe_price_id text,
status text not null default 'inactive', -- active | past_due | canceled | trialing
current_period_end timestamptz,
created_at timestamptz default now(),
updated_at timestamptz default now()
);
-- RLS: users can read their own subscription
alter table subscriptions enable row level security;
create policy "users read own" on subscriptions for select using (auth.uid() = user_id);Test Cards
| Card | Scenario |
4242 4242 4242 4242 | Successful payment |
4000 0025 0000 3155 | Requires 3D Secure |
4000 0000 0000 9995 | Declined |
4000 0000 0000 0341 | Attaches successfully but payment always fails |
Any future expiry, any CVC, any postal code.
Go Live Checklist
- Switch from
sk_test_tosk_live_keys in Supabase secrets - Switch publishable key to
pk_live_in frontend/mobile env - Create new webhook endpoint pointing to production (test and live webhooks are separate)
- Verify products/prices exist in live mode (test mode data doesn't carry over)
- Test a real payment with a real card
- Enable Radar fraud rules: dashboard.stripe.com/radar/rules
Gotchas
Webhook signature verification fails — The webhook secret for local CLI (whsec_... from stripe listen) is different from the production dashboard secret. Use the right one per environment.
Missing SUPABASE_SERVICE_ROLE_KEY — Webhook handler must use the service role key to bypass RLS when writing subscription data. The publishable key won't work.
Duplicate webhook events — Stripe can deliver the same event more than once. Use upsert instead of insert, or check for existing records before writing.
Subscription not activating — Webhook is not reaching the function. Check Stripe dashboard → Webhooks → Recent deliveries for errors.
Apple/Google take 30% cut on mobile — If your app sells digital goods or subscriptions through the mobile app, Apple and Google require you to use their in-app purchase system (not Stripe). Stripe is fine for web checkout. This is the "App Store tax" — plan around it.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

