Stripe Best Practices

Stripe Provider

Connect PayKit to Stripe with @paykitjs/stripe.

Setup

1. Install the provider

pnpm add @paykitjs/stripe

2. Get your Stripe keys

From the Stripe Dashboard:

• Secret key (sk_test_... or sk_live_...)
• Webhook signing secret (whsec_...), created when you add a webhook endpoint

3. Add environment variables

STRIPE_SECRET_KEY="sk_test_..."
STRIPE_WEBHOOK_SECRET="whsec_..."

4. Configure the provider

import { createPayKit } from "paykitjs"
import { stripe } from "@paykitjs/stripe"

export const paykit = createPayKit({
  // ...
  provider: stripe({
    secretKey: process.env.STRIPE_SECRET_KEY!,
    webhookSecret: process.env.STRIPE_WEBHOOK_SECRET!,
  }),
})

Syncing Plans to Stripe

After defining or changing plans, sync them:

npx paykitjs push

This creates/updates in Stripe:

• Products: one per plan
• Prices: one per plan with pricing

Check sync status:

npx paykitjs status

Note: Always run push after modifying plans. PayKit won't auto-sync on startup.

Webhook Setup

PayKit processes Stripe webhooks through its route handler. Configure Stripe to send webhooks to:

https://your-domain.com/paykit/api/webhook

Required Stripe webhook events

PayKit needs these events enabled in your Stripe webhook endpoint:

• checkout.session.completed
• customer.subscription.created
• customer.subscription.updated
• customer.subscription.deleted
• invoice.paid
• invoice.payment_failed

Local development

Use the Stripe CLI to forward webhooks locally:

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

The CLI outputs a webhook signing secret (whsec_...). Use this as STRIPE_WEBHOOK_SECRET in development.

Customer Portal

Stripe's Customer Portal lets customers manage their billing. PayKit provides a wrapper:

Server-side:

const { url } = await paykit.customerPortal({
  customerId: "user_123",
  returnUrl: "https://example.com/billing",
})

// Redirect user to url

Client-side:

await paykitClient.customerPortal({
  returnUrl: window.location.href,
})

Configure the Customer Portal appearance and features in the Stripe Dashboard.

How PayKit Uses Stripe

PayKit maps its concepts to Stripe objects:

PayKit stores its own records in your PostgreSQL database and keeps them in sync with Stripe via webhooks.

Test vs Live Mode

Use Stripe test keys (sk_test_...) during development. Switch to live keys (sk_live_...) for production.

PayKit doesn't distinguish between modes. It follows whatever key you provide.

Test cards: Use Stripe's test card numbers to simulate payments:

• 4242 4242 4242 4242 succeeds
• 4000 0000 0000 0002 declines

Troubleshooting