Plainform

Learn how to test Stripe payments, webhooks, and checkout flows locally using the Stripe CLI.

Prerequisites

Stripe account in test mode
Stripe CLI installed
Local development server running

Steps

Install Stripe CLI

Install the Stripe CLI following the official installation guide.

Verify installation:

stripe --version

Authenticate with your Stripe account:

stripe login

This opens your browser to authorize the CLI. Press Enter after authorizing.

The CLI automatically uses test mode. Your live API keys are never exposed.

Start Webhook Forwarding

Forward Stripe webhooks to your local server:

npm run stripe:listen

Or manually:

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

This command:

Listens for webhook events from Stripe
Forwards them to your local webhook endpoint
Displays a webhook signing secret

Copy the webhook signing secret (starts with whsec_).

Update Environment Variables

Add the webhook secret to your .env file:

.env

STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret_here

Restart your development server:

npm run dev

Test Checkout Flow

With webhook forwarding active, test the complete checkout flow:

Navigate to http://localhost:3000
Click "Get Started" on a product
Use test card: 4242 4242 4242 4242
Enter any future expiry date (e.g., 12/34)
Enter any 3-digit CVC (e.g., 123)
Complete checkout

Watch the Stripe CLI terminal for webhook events:

✔ Received event: checkout.session.completed
✔ Forwarded to localhost:3000/api/stripe/webhook

Test Card Numbers

Stripe provides test cards for different scenarios:

Successful Payment:

4242 4242 4242 4242

Requires Authentication (3D Secure):

4000 0025 0000 3155

Declined Card:

4000 0000 0000 0002

Insufficient Funds:

4000 0000 0000 9995

Expired Card:

4000 0000 0000 0069

All test cards:

Use any future expiry date
Use any 3-digit CVC
Use any billing ZIP code

Find more test cards in Stripe's testing documentation.

Trigger Test Webhooks

Manually trigger webhook events for testing:

npm run stripe:trigger

Or trigger specific events:

# Trigger checkout session completed
stripe trigger checkout.session.completed

# Trigger payment intent succeeded
stripe trigger payment_intent.succeeded

# Trigger subscription created
stripe trigger customer.subscription.created

Common Webhook Events

Test these events for your payment flow:

Checkout Events:

stripe trigger checkout.session.completed
stripe trigger checkout.session.expired

Payment Events:

stripe trigger payment_intent.succeeded
stripe trigger payment_intent.payment_failed

Subscription Events:

stripe trigger customer.subscription.created
stripe trigger customer.subscription.updated
stripe trigger customer.subscription.deleted

Coupon Events:

stripe trigger coupon.created
stripe trigger coupon.updated

Verify Webhook Processing

Check your application logs to verify webhooks are processed:

Watch the Stripe CLI output for forwarded events
Check your server console for webhook handler logs
Verify database updates (if applicable)
Confirm emails are sent (check Resend dashboard)

Common Issues

Webhook Secret Not Working

Ensure you copied the complete secret (starts with whsec_)
Verify the secret is in .env file
Restart your dev server after updating .env
Check that STRIPE_WEBHOOK_SECRET matches the CLI output

Events Not Forwarding

Confirm Stripe CLI is running (stripe listen)
Verify your dev server is running on the correct port
Check firewall settings aren't blocking localhost
Ensure the webhook endpoint path is correct

Test Card Declined

Use the correct test card number (4242 4242 4242 4242)
Enter any future expiry date
Use any 3-digit CVC
Verify you're in test mode (not live mode)

Webhook Handler Errors

Check server console for error messages
Verify webhook signature validation is working
Ensure all required environment variables are set
Review webhook handler code for bugs

Best Practices

Development Workflow:

Start Stripe CLI webhook forwarding first
Then start your development server
Keep both running during development
Monitor both terminals for errors

Testing Strategy:

Test successful payments first
Test declined cards and error cases
Verify webhook events are processed correctly
Test with different product types (one-time, subscription)
Verify email notifications are sent

Security:

Never commit webhook secrets to version control
Use test mode for all local development
Verify webhook signatures in production
Keep Stripe CLI updated

Production Webhook Setup

When deploying to production:

Go to Stripe Dashboard → Developers → Webhooks
Click "Add endpoint"

Enter your production webhook URL:

https://yourdomain.com/api/stripe/webhook

Select events to listen for:
- checkout.session.completed
- payment_intent.succeeded
- customer.subscription.*
- coupon.*
Copy the webhook signing secret
Add to production environment variables

Production webhook secrets are different from test mode secrets. Update your production environment variables accordingly.

Next Steps

Customize Checkout - Customize the checkout experience
Add Product - Create products to test
Create Subscription - Test subscription billing

Test Payments Locally