Stripe payments

Configure Stripe payments in your PocketStarter app to accept subscriptions and one-time payments. This guide covers setup, configuration, and production deployment.

Quick setup

Create a Stripe account at stripe.com and activate payments
Configure your account:
- Go to Settings → Business
- Add your account and business details
- Under Branding, upload your logo and set brand colors
- Go through your other settings and ensure things are set up correctly. For example, you can enable fraud protection under Radar → Risk Controls.
Enable Test Mode for development
Get your API keys from the Developers section and add this to the PocketBase .env.local:
```
STRIPE_SECRET_KEY=sk_test_your_key
STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret
```
Set up webhooks locally:
- Go to Developers → Webhooks → Local listeners in your Stripe dashboard
- Follow the instructions to install the Stripe CLI and run:
```
stripe listen --forward-to localhost:8090/api/stripe/webhook
```
Note that the webhook points to localhost:8090 (PocketBase) and not localhost:3000 (frontend).
- Copy the webhook secret to STRIPE_WEBHOOK_SECRET in .env.local

You don't need STRIPE_PUBLIC_KEY for this setup. PocketStarter uses Stripe's hosted checkout pages, which handle payment processing securely on Stripe's servers without requiring client-side integration.

Configure the pricing

Create a product in your Stripe dashboard and copy the price ID
Update frontend/src/config/pricing.ts with your Stripe price IDs and customize:
- Trial periods - Set trialDays for free trials
- Payment modes - Use 'subscription' or 'payment' for one-time purchases
- Features - List what each plan includes
- Remove unused plans - Delete any pricing plans you don't need from the array

Upgrade Your Account

Customers can upgrade their account from any place in your app.

Protecting Premium Content

The subscription status is accessible from the auth store. Use it to control access to premium features.

const { subscriptionStatus } = useAuth();

if (subscriptionStatus !== 'active' && subscriptionStatus !== 'trialing') {
  return <div>Please subscribe to access this content</div>;
}

Customer portal

The boilerplate includes a customer portal for subscription management. Users can access it from their account dashboard to update payment methods, view invoices, and cancel subscriptions.

Going live

When you're ready for production:

Disable Test Mode in your Stripe dashboard
Set up production webhooks - Add endpoint with your domain + /api/stripe/webhook
Select webhook events: checkout.session.completed, customer.subscription.updated, customer.subscription.deleted, invoice.payment_succeeded, invoice.payment_failed
Update environment variables with live keys.

Make sure your webhook endpoint points to your PocketBase domain (e.g., https://pb.yourdomain.com/api/stripe/webhook) and not just your frontend domain. The webhook needs to reach PocketBase directly to process payments.

How it works

The app automatically handles subscription lifecycle through webhooks. When a user subscribes, their subscription status is set to active or trialing. When they cancel or payment fails, it's updated accordingly.

You can add custom logic to the webhook handler for things like sending welcome emails or adding user credits.

Payment testing

Use these Stripe-provided test cards during Test mode (see the Stripe Testing documentation for more details):

Success: 4242 4242 4242 4242
Decline: 4000 0000 0000 0002
3D Secure: 4000 0025 0000 3155

On this page