Build Stripe Integration in Lovable | Prompt Kit

TL;DR

The one-paragraph version before you dive in.

Paste the starter prompt below into Lovable Build mode and get a complete Stripe integration — checkout, customer portal, and a webhook handler that actually works in Deno. The two gotchas that break every other guide: you must read the request body with req.text() not req.json(), and you must call constructEventAsync not constructEvent. Both are non-negotiable in Deno Edge Functions. A documented build ran this entire flow in under 10 credits in one session.

Setup checklist

Complete these steps in Lovable before pasting the starter prompt — takes about 5 minutes.

Cloud tab settings

Database

Stores customers, payments, subscriptions, and the webhook_events idempotency log. The starter prompt creates all four tables via migration.

1Click the + button next to Preview to open the Cloud tab
2Click Database — the starter prompt creates all tables via migration
3After the migration runs, verify the UNIQUE index on payments.stripe_payment_intent_id and webhook_events.id exist in Cloud tab → Database → Indexes

Auth

Most checkouts attach to a signed-in user. The create-checkout-session function reads the caller's user ID from the Authorization header.

1Cloud tab → Users & Auth
2Enable Email sign-in (default — already on)
3Users who checkout should be signed in first — the /pricing page Buy CTAs redirect to /login if not authenticated

Edge Functions

Four Edge Functions handle checkout session creation, customer portal, webhook verification, and ensure-stripe-customer on signup.

1Cloud tab → Edge Functions — leave empty; the starter prompt and follow-ups generate all four functions
2After generating stripe-webhook, register the webhook endpoint in Stripe Dashboard → Developers → Webhooks
3Add STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET to Cloud tab → Secrets (see Secrets section) before any Stripe-related prompt

Secrets (Cloud tab → Secrets)

STRIPE_SECRET_KEY

Purpose: All Stripe API calls (create checkout session, customer portal, PaymentIntent) are authenticated with this key.

Where to get it: https://dashboard.stripe.com/apikeys — use the API Key icon in the Lovable chat input or paste directly in Cloud tab → Secrets. NEVER paste the secret key into a chat message — chat messages are logged and the key can be recovered later.

STRIPE_WEBHOOK_SECRET

Purpose: Used in constructEventAsync to verify that webhook events came from Stripe, not a third party spoofing your endpoint.

Where to get it: https://dashboard.stripe.com/webhooks → click your webhook endpoint → copy the Signing secret (whsec_...). Each endpoint has its own signing secret — test and live endpoints have different secrets.

RESEND_API_KEY

Purpose: Sends custom-branded receipt emails after successful payment if you prefer them over Stripe's built-in receipts.

Where to get it: https://resend.com/api-keys — create a key with Send access. Only needed for follow-up #7 (custom branded receipts).

Preflight checklist

You're in a fresh Lovable project, or you have an existing Lovable app that you want to add payments to
You have a Stripe account — go to https://dashboard.stripe.com/register to create one; activation (for live charges) requires tax ID and bank account but test mode works immediately
You have created at least one Stripe Product and Price in the Stripe Dashboard (Products → Add product → Add price). Note the Price ID (price_xxx) — you'll need it in create-checkout-session
You're on Pro $25/mo — the documented tomokat build ran under 10 credits, but budget 80-150 for iteration on the webhook async/raw-body issues that most builders hit

The starter prompt — paste this first

Copy this. Paste it into Lovable Agent Mode (the default chat at the bottom-left of the editor). Hit send.

lovable-agent-mode.txt

~30-50 credits

Add a complete Stripe payment integration to this Lovable app. Stack assumptions: React + Vite + TypeScript + Tailwind + shadcn/ui already scaffolded, React Router for routes, Supabase JS client against Lovable Cloud.

## Database schema (create one migration)

Create four tables in the public schema:

1. `customers` — id (uuid pk references auth.users(id) on delete cascade), stripe_customer_id (text unique), email (text), default_payment_method (text), created_at (timestamptz default now()).

2. `payments` — id (uuid pk default gen_random_uuid()), user_id (uuid not null references auth.users(id)), stripe_payment_intent_id (text unique not null), amount_cents (int not null), currency (text not null default 'usd'), status (text not null default 'pending' check (status in ('pending','succeeded','failed','refunded'))), description (text), created_at (timestamptz default now()), updated_at (timestamptz default now()).

3. `subscriptions` — id (uuid pk default gen_random_uuid()), user_id (uuid not null references auth.users(id)), stripe_subscription_id (text unique not null), stripe_price_id (text), status (text not null check (status in ('trialing','active','past_due','canceled','incomplete','incomplete_expired'))), current_period_start (timestamptz), current_period_end (timestamptz), cancel_at_period_end (bool default false), created_at (timestamptz default now()).

4. `webhook_events` — id (text pk — this is the Stripe event.id, e.g. evt_xxx, providing natural idempotency), type (text not null), processed_at (timestamptz default now()), payload (jsonb).

Create a UNIQUE index on payments.stripe_payment_intent_id (already UNIQUE from the column definition, but be explicit).

Enable RLS on all four tables.
- customers: SELECT for auth.uid() = id; INSERT/UPDATE via service-role (webhook).
- payments: SELECT for auth.uid() = user_id; no user INSERT/UPDATE (webhook handles these).
- subscriptions: SELECT for auth.uid() = user_id; no user INSERT/UPDATE.
- webhook_events: SELECT for admin only via has_role('admin') function.

Create SECURITY DEFINER function `has_role(p_role text)` returns boolean: RETURN (auth.jwt() ->> 'app_metadata')::jsonb ->> 'role' = p_role;

## Layout and pages

Create or add to the existing AppLayout a set of payment-related routes:

- /pricing (Pricing.tsx) — show three pricing tier cards using shadcn Card component. Each card: tier name, price per month, 3-5 feature bullets, and a Buy button. The Buy button calls the create-checkout-session Edge Function with the tier's price_id and mode='subscription' (or 'payment' for one-time). Redirect to the returned checkout_url. If the user is not signed in, the Buy button routes to /login?redirect=/pricing instead. For now, hardcode three price_ids as constants at the top of the file.

- /payment-success (PaymentSuccess.tsx) — reads ?session_id= from the URL. Shows a loading spinner, then polls the payments table every 2 seconds (up to 30s) waiting for a row with status='succeeded' to appear (the webhook will write it). Once found, shows a checkmark animation (Framer Motion scale from 0 to 1 with spring), a receipt summary (amount, description), and a link to /account/billing. If 30s elapse without a row, show 'Your payment is being processed — check your email for a receipt.'

- /payment-canceled (PaymentCanceled.tsx) — simple page: 'You canceled checkout. No charge was made.' with a 'Try again' button linking back to /pricing.

- /account/billing (AccountBilling.tsx) — auth-gated. Shows: current subscription plan (query subscriptions table) with status badge, current_period_end date, cancel_at_period_end warning if true. List of recent payments (last 10, query payments table). A 'Manage billing' button that calls the customer-portal Edge Function and opens the returned URL in a new tab.

## Edge Function: ensure-stripe-customer

Create supabase/functions/ensure-stripe-customer/index.ts. The function accepts {user_id, email} in the body. It:
1. Checks customers.stripe_customer_id for this user_id — if it exists, return {stripe_customer_id} immediately.
2. If not, calls stripe.customers.create({email, metadata: {supabase_user_id: user_id}}).
3. Upserts into customers (id=user_id, stripe_customer_id, email) using the service-role key.
4. Returns {stripe_customer_id}.

## Edge Function: create-checkout-session

Create supabase/functions/create-checkout-session/index.ts. The function:
1. Reads the caller's user ID from the Authorization header (await supabase.auth.getUser()).
2. Calls ensure-stripe-customer (via supabase.functions.invoke) to get or create the stripe_customer_id.
3. Creates a Stripe Checkout Session: mode from request body ('payment' or 'subscription'), line_items with price_id, customer=stripe_customer_id, success_url='/payment-success?session_id={CHECKOUT_SESSION_ID}', cancel_url='/payment-canceled'.
4. Returns {checkout_url: session.url}.

## Edge Function: customer-portal

Create supabase/functions/customer-portal/index.ts. The function reads the caller's stripe_customer_id from the customers table, creates a Stripe BillingPortal Session with return_url='/account/billing', and returns {portal_url: session.url}.

## Edge Function: stripe-webhook

Create supabase/functions/stripe-webhook/index.ts. This is the most critical function — follow these rules exactly:

1. Read the raw body: `const rawBody = await req.text()` — DO NOT use `await req.json()` anywhere before signature verification.
2. Get the signature header: `const sig = req.headers.get('stripe-signature')`.
3. Call the async verification: `const event = await stripe.webhooks.constructEventAsync(rawBody, sig, Deno.env.get('STRIPE_WEBHOOK_SECRET'))` — this MUST be `constructEventAsync` (async), NOT `constructEvent` (sync). Deno's SubtleCrypto is async; the sync version will throw 'SubtleCryptoProvider cannot be used in a synchronous context'.
4. Idempotency: INSERT into webhook_events (id=event.id, type=event.type, payload=event as JSON). If the insert fails with a UNIQUE constraint violation on id, return 200 immediately — this event was already processed.
5. Switch on event.type:
   - 'checkout.session.completed': create a payments row (user_id from session.metadata or customer lookup, stripe_payment_intent_id, amount_cents, status='succeeded') OR update subscription status.
   - 'invoice.paid': ensure subscription status is 'active'.
   - 'customer.subscription.updated': update subscriptions row (status, current_period_start, current_period_end, cancel_at_period_end).
   - 'customer.subscription.deleted': set subscriptions.status = 'canceled'.
6. Return 200 immediately after processing — Stripe retries on any non-200 or responses over 5 seconds.

## Key components

PricingCard (accepts tier name, price, features array, price_id, mode; renders shadcn Card with Buy button), PortalButton (calls customer-portal Edge Function on click, opens URL in new tab), PaymentStatus (polling component in /payment-success — polls payments table, shows spinner then success animation), ReceiptList (table of recent payments with amount, date, status badge).

## Styling

Light mode for /pricing (price legibility is better on white). Use shadcn Card for tier cards. Highlight the recommended tier with ring-2 ring-primary. Add a subtle Stripe badge ('Powered by Stripe') in the footer of /pricing. /payment-success uses a centered layout with large checkmark animation.

What this prompt generates

Creates one SQL migration with 4 tables (customers, payments, subscriptions, webhook_events), RLS policies, and UNIQUE indexes for idempotency
Generates /pricing with 3 tier cards and working Buy buttons calling create-checkout-session
Creates /payment-success with polling until webhook writes the payment row, /payment-canceled, and /account/billing with portal button
Builds all 4 Edge Functions: ensure-stripe-customer, create-checkout-session, customer-portal, and stripe-webhook with correct raw body + constructEventAsync
Creates PricingCard, PortalButton, PaymentStatus, and ReceiptList components

Paste into: Lovable Agent Mode (the default chat at the bottom-left of the editor)

Expected output

What Lovable will generate after the starter prompt runs successfully.

Files

supabase/migrations/0001_payments_schema.sql

4 tables + RLS + has_role() + UNIQUE indexes for idempotency

src/components/PricingCard.tsx

Tier card with price, features, and Buy button

src/components/PortalButton.tsx

Opens Stripe billing portal in new tab

src/components/PaymentStatus.tsx

Polls payments table, shows spinner then success animation

src/components/ReceiptList.tsx

Table of recent payments with status badges

src/pages/Pricing.tsx

Three tier cards with Buy buttons

src/pages/PaymentSuccess.tsx

Polls for payment row, shows checkmark on success

src/pages/PaymentCanceled.tsx

Graceful cancel with try-again CTA

src/pages/AccountBilling.tsx

Subscription status, recent payments, Stripe portal button

supabase/functions/ensure-stripe-customer/index.ts

Creates Stripe Customer on first checkout if not exists

supabase/functions/create-checkout-session/index.ts

Creates Stripe Checkout Session and returns URL

supabase/functions/customer-portal/index.ts

Creates Stripe Billing Portal session and returns URL

supabase/functions/stripe-webhook/index.ts

Raw body + constructEventAsync + idempotent event processing

Routes

/pricing

Three tier cards with working Stripe checkout

/payment-success

Polls for payment confirmation, shows checkmark

/payment-canceled

Graceful cancel page with try-again

/account/billing

Subscription status, payment history, portal button

DB Tables

customers

Column	Type	Notes
id	uuid primary key references auth.users(id)	—
stripe_customer_id	text unique	—
email	text	—
default_payment_method	text	—

RLS: SELECT for auth.uid() = id; write via service-role webhook

payments

Column	Type	Notes
id	uuid primary key	—
user_id	uuid not null references auth.users(id)	—
stripe_payment_intent_id	text unique not null	—
amount_cents	int not null	—
status	text check in (pending,succeeded,failed,refunded)	—

RLS: SELECT for user_id = auth.uid(); no user write

subscriptions

Column	Type	Notes
id	uuid primary key	—
user_id	uuid not null references auth.users(id)	—
stripe_subscription_id	text unique not null	—
status	text check in (trialing,active,past_due,canceled,incomplete,incomplete_expired)	—
cancel_at_period_end	bool default false	—

RLS: SELECT for user_id = auth.uid(); no user write

webhook_events

Column	Type	Notes
id	text primary key	Stripe event.id — natural idempotency key
type	text not null	—
processed_at	timestamptz default now()	—
payload	jsonb	—

RLS: Admin SELECT only via has_role('admin')

Components

PricingCard

Tier card with price, feature list, and Buy button that calls create-checkout-session

PortalButton

Calls customer-portal, opens returned URL in new tab

PaymentStatus

Polls payments table until succeeded row appears, then shows success animation

ReceiptList

Recent payments table with amount, date, status chip

Follow-up prompts

Paste these into Agent Mode one by one, in order, after the starter prompt finishes.

Add STRIPE_SECRET_KEY to Cloud Secrets the right way

Stripe secret key securely stored in Cloud Secrets — required before any Stripe Edge Function will work

~0 credits — just a careful click

prompt

Before running any prompt that references Stripe, add your Stripe secret key to Cloud Secrets securely.

In the Lovable chat input, look for the API Key icon (lock icon with a key, to the left of the message input). Click it. A secure form appears with 'Key name' and 'Key value' fields. Enter STRIPE_SECRET_KEY as the name and paste your Stripe secret key (sk_test_... for testing, sk_live_... for production) as the value. Click Save.

Alternatively, go directly to Cloud tab → Secrets → New Secret.

NEVER paste the secret key directly into a chat message. Chat messages are logged by Lovable for quality and debugging purposes, which means a pasted secret could be recovered later. The API Key icon form writes directly to Secrets without logging the value.

Repeat this process for STRIPE_WEBHOOK_SECRET once you set up the webhook endpoint in Stripe Dashboard. The test webhook secret and live webhook secret are different — update this secret when you switch from test to live mode.

When to use: Immediately, before running any other follow-up prompt in this kit

Build create-checkout-session with ensure-stripe-customer

Working Stripe checkout that creates or reuses a Stripe Customer and generates a hosted Checkout URL

~25-35 credits

prompt

Implement the create-checkout-session Edge Function at supabase/functions/create-checkout-session/index.ts.

The function should:
1. Parse the request body for {price_id, mode} where mode is 'payment' or 'subscription'.
2. Get the caller's user ID: const { data: { user } } = await supabase.auth.getUser(authHeader).
3. If no user, return 401 {error: 'Not authenticated'}.
4. Call ensure-stripe-customer: const { data: { stripe_customer_id } } = await supabase.functions.invoke('ensure-stripe-customer', { body: { user_id: user.id, email: user.email } }).
5. Create a Stripe Checkout Session: await stripe.checkout.sessions.create({ customer: stripe_customer_id, mode, line_items: [{price: price_id, quantity: 1}], success_url: `${origin}/payment-success?session_id={CHECKOUT_SESSION_ID}`, cancel_url: `${origin}/payment-canceled`, metadata: { user_id: user.id } }).
6. Return {checkout_url: session.url}.

In Pricing.tsx, update each PricingCard's Buy button onClick to:
const { data } = await supabase.functions.invoke('create-checkout-session', { body: { price_id: tier.price_id, mode: tier.mode } });
window.location.href = data.checkout_url;

Show a loading spinner on the button while the request is in flight.

When to use: After STRIPE_SECRET_KEY is in Cloud Secrets

Build stripe-webhook with raw body + async verification + idempotency

Stripe webhook with the two mandatory Deno fixes (raw body + async verify) and idempotency via webhook_events table

~40-55 credits

prompt

Implement the stripe-webhook Edge Function at supabase/functions/stripe-webhook/index.ts. This is the most error-prone part of any Stripe integration — follow these steps exactly.

The function:
1. `const rawBody = await req.text()` — this is the raw bytes Stripe signed. Never replace this with req.json().
2. `const sig = req.headers.get('stripe-signature')` — this is the signature header Stripe sends.
3. `const event = await stripe.webhooks.constructEventAsync(rawBody, sig, Deno.env.get('STRIPE_WEBHOOK_SECRET'))` — async version only. If you see 'SubtleCryptoProvider cannot be used in a synchronous context', you used constructEvent instead of constructEventAsync.
4. Idempotency check: try { await supabase.from('webhook_events').insert({id: event.id, type: event.type, payload: event}) } catch (e) { if (e.code === '23505') return new Response('Already processed', {status: 200}); throw e; }
5. Switch on event.type:
   - 'checkout.session.completed': look up user_id from event.data.object.metadata.user_id. INSERT into payments: {user_id, stripe_payment_intent_id: event.data.object.payment_intent, amount_cents: event.data.object.amount_total, status: 'succeeded'}. If mode='subscription', INSERT into subscriptions with event.data.object.subscription.
   - 'invoice.paid': UPDATE subscriptions SET status='active' WHERE stripe_subscription_id = event.data.object.subscription.
   - 'customer.subscription.updated': UPDATE subscriptions SET status, current_period_start, current_period_end, cancel_at_period_end WHERE stripe_subscription_id = event.data.object.id.
   - 'customer.subscription.deleted': UPDATE subscriptions SET status='canceled'.
6. return new Response('OK', {status: 200}) — return 200 fast. Stripe retries any non-200.

Use the Supabase client with the service-role key (Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')) for all database writes in this function — the webhook request has no user auth header.

When to use: After create-checkout-session works; then register the webhook endpoint in Stripe Dashboard

Register the webhook endpoint and test end-to-end

Stripe webhook endpoint registration and a complete end-to-end test flow

~10 credits — mostly Stripe Dashboard work and test card verification

prompt

Before the webhook can receive events, register it in Stripe Dashboard.

For testing without deploying:
1. In Stripe Dashboard → Developers → Webhooks → Add endpoint.
2. Endpoint URL: your Lovable preview URL + /api/stripe-webhook (e.g. https://your-project.lovable.app/api/stripe-webhook). Lovable preview URLs are HTTPS and publicly accessible — webhook callbacks work.
3. Select events to listen to: checkout.session.completed, invoice.paid, customer.subscription.updated, customer.subscription.deleted.
4. Click Add endpoint. Copy the Signing secret (whsec_...) that appears — this is your STRIPE_WEBHOOK_SECRET for the test endpoint.
5. Add STRIPE_WEBHOOK_SECRET to Cloud tab → Secrets.

For production: after deploying to a custom domain, create a SEPARATE webhook endpoint pointing at your production URL with its own signing secret. Update STRIPE_WEBHOOK_SECRET to the production value.

Test the flow:
1. Go to /pricing and click a Buy button.
2. Use Stripe test card: 4242 4242 4242 4242, expiry 12/34, CVC 123, any ZIP.
3. Complete checkout — Stripe redirects to /payment-success.
4. In Stripe Dashboard → Events, confirm checkout.session.completed fired.
5. In Cloud tab → Database → SQL Editor: SELECT * FROM payments ORDER BY created_at DESC LIMIT 1 — should show a succeeded row.
6. In /account/billing, confirm the subscription or payment appears.

When to use: Immediately after stripe-webhook is deployed

Add customer portal for self-serve billing management

Self-serve billing portal so users can manage their subscription without contacting support

~18-25 credits

prompt

Implement the customer-portal Edge Function at supabase/functions/customer-portal/index.ts.

The function:
1. Gets the caller's user ID from the Authorization header.
2. Queries customers.stripe_customer_id for that user. If null, calls ensure-stripe-customer first.
3. Creates a Stripe Billing Portal Session: await stripe.billingPortal.sessions.create({ customer: stripe_customer_id, return_url: `${origin}/account/billing` }).
4. Returns {portal_url: session.url}.

In AccountBilling.tsx, the PortalButton onClick:
const { data } = await supabase.functions.invoke('customer-portal');
window.open(data.portal_url, '_blank');

The Stripe portal lets users: view invoices, update payment method, cancel subscription, download receipts. Zero custom billing UI needed for these tasks.

Note: Stripe Billing Portal must be enabled in Stripe Dashboard → Settings → Billing → Customer portal. Toggle it on and configure what actions you want to allow (cancellation, plan changes, payment method updates).

When to use: After stripe-webhook works — this is zero-touch billing support

Switch to live mode

Live Stripe mode configured with separate production webhook endpoint and signing secret

~10 credits — mostly Stripe Dashboard configuration

prompt

When you're ready to accept real money, switch from Stripe test mode to live mode.

1. In Stripe Dashboard, complete account activation: Dashboard → Settings → Account details → provide your legal business name, address, and bank account for payouts.

2. In Stripe Dashboard, switch to Live mode (toggle top-left of Dashboard).

3. Copy your live secret key (sk_live_...) from Dashboard → Developers → API keys.

4. In Lovable: Cloud tab → Secrets → STRIPE_SECRET_KEY → update to sk_live_... value.

5. In Stripe Dashboard (Live mode) → Developers → Webhooks → Add endpoint. Add a NEW endpoint for your production URL. Copy the new Signing secret. Update STRIPE_WEBHOOK_SECRET in Cloud Secrets to this live signing secret. The test endpoint and live endpoint have DIFFERENT signing secrets — mixing them up is the #1 go-live mistake.

6. Test with your own real card: go to /pricing, buy the cheapest plan, verify the payment appears in the Stripe Dashboard and in your payments table. Then immediately go to Stripe Dashboard → Payments → find your charge → Refund.

7. Remove any hardcoded test card numbers or price_ids from the codebase. Update price_ids in Pricing.tsx to live-mode Price IDs (they start with price_live_xxx in Live mode).

When to use: When you've validated the full test flow and are ready to charge real users

Add Resend custom branded receipts

Custom-branded receipt emails sent via Resend after checkout.session.completed, with error handling that never fails the webhook

~25-30 credits

prompt

Add custom-branded receipt emails after payment. In the stripe-webhook Edge Function, after processing a 'checkout.session.completed' event and inserting the payments row, add a Resend email call.

Get the user's email from auth.users using the service-role Supabase client: const { data: user } = await supabase.auth.admin.getUserById(user_id).

Call Resend: import { Resend } from 'https://esm.sh/resend@latest'; const resend = new Resend(Deno.env.get('RESEND_API_KEY')); await resend.emails.send({ from: 'receipts@your-domain.com', to: user.email, subject: 'Your receipt from [Your App]', html: `<h2>Payment confirmed</h2><p>Amount: $${(payment.amount_cents / 100).toFixed(2)} ${payment.currency.toUpperCase()}</p><p>View your billing details: <a href='https://your-app.com/account/billing'>Account Billing</a></p>` });

Wrap the email send in try/catch — a failed email must never fail the webhook response. Log the error but still return 200.

Note: Stripe sends its own email receipts by default (toggle in Stripe Dashboard → Settings → Customer emails). Decide once whether you want Stripe's receipts or your own Resend receipts, and disable the other to avoid sending both to the user.

Add RESEND_API_KEY to Cloud Secrets before running this prompt.

When to use: After the full flow works in live mode and default Stripe receipts feel off-brand

Common errors

Real error strings you'll see. Find yours, paste the fix prompt.

SubtleCryptoProvider cannot be used in a synchronous context. Use await stripe.webhooks.constructEventAsync(...) instead

You called stripe.webhooks.constructEvent() (the sync version). Deno's SubtleCrypto API is async — the sync version physically cannot work in a Deno Edge Function context.