Stripe Verify

Comprehensive end-to-end verification. Go deep — billing bugs are expensive.

Objective

Prove the integration works. Not "looks right" — actually works. Test real flows, verify real state changes, confirm real webhook delivery.

Process

1. Configuration Verification

Before functional tests, verify all configuration:

# Env vars exist
bunx convex env list | rg "^(STRIPE_|CONVEX_WEBHOOK_TOKEN=)"
bunx convex env list --prod | rg "^(STRIPE_|CONVEX_WEBHOOK_TOKEN=)"
vercel env ls --environment=production 2>/dev/null | rg "^(STRIPE_|CONVEX_WEBHOOK_TOKEN=)" || true

# Token parity (Next/Vercel ↔ Convex) - P0 invariant
vercel env pull .env.vercel-parity-check --environment=production --yes >/dev/null
vercel_token=$(rg "^CONVEX_WEBHOOK_TOKEN=" .env.vercel-parity-check | head -n1 | cut -d= -f2-)
rm -f .env.vercel-parity-check
convex_token=$(bunx convex env get --prod CONVEX_WEBHOOK_TOKEN 2>/dev/null || true)
[ -n "$vercel_token" ] && [ -n "$convex_token" ] && [ "$vercel_token" = "$convex_token" ] && echo "✓ CONVEX_WEBHOOK_TOKEN parity (prod)" || echo "✗ CONVEX_WEBHOOK_TOKEN parity failed (prod)"

# Webhook URL accessible
curl -s -o /dev/null -w "%{http_code}" -I -X POST "$WEBHOOK_URL"
# Must be 4xx or 5xx, not 3xx

# Stripe CLI connected
stripe listen --print-json --latest

2. Checkout Flow Test

Create a real test checkout session:

# Trigger checkout (via app or API)
# Complete with Stripe test card: 4242 4242 4242 4242

# Verify:
# - Session created successfully
# - Redirect works
# - Success page loads
# - POST /api/stripe/checkout/confirm succeeds (or equivalent return-page sync)
# - Webhook received (check logs)
# - Subscription created in Stripe Dashboard
# - User state updated in database

3. Webhook Delivery Test

Verify webhooks are actually delivering:

# Check pending webhooks
stripe events list --limit 5 | jq '.data[] | {id, type, pending_webhooks}'

# Resend a recent event
stripe events resend <event_id> --webhook-endpoint <endpoint_id>

# Watch logs for delivery
vercel logs <app> --json | grep webhook

All recent events should have pending_webhooks: 0.

4. Subscription State Transitions

Test each state transition:

New → Trial

Create account
Verify trial starts
Verify trial end date correct

Trial → Active

Complete checkout during trial
Verify remaining trial honored (trial_end passed to Stripe)
Verify local state updated

Active → Canceled

Cancel subscription (via customer portal or API)
Verify access continues until period end
Verify state reflects cancellation

Canceled → Resubscribed

Resubscribe after cancellation
Verify new subscription created
Verify billing starts immediately (no new trial)

Trial Expired

Let trial expire (or simulate)
Verify access revoked
Verify proper messaging to user

5. Edge Case Testing

Webhook Idempotency

Resend the same webhook event twice
Verify no duplicate processing
Verify no state corruption

Out-of-Order Webhooks

If possible, simulate events arriving out of order
Verify system handles gracefully

Payment Failure

Use Stripe test card for decline: 4000 0000 0000 0002
Verify subscription goes to past_due
Verify access policy for past_due state

6. Access Control Verification

Test that access control actually works:

Active subscriber → can access features
Trial user → can access features
Expired trial → blocked
Canceled (in period) → can access
Canceled (past period) → blocked
Past due → depends on policy (usually grace period)

7. Business Model Compliance

Verify against business-model-preferences:

Single pricing tier? (no multiple options)
Trial honored on upgrade? (check Stripe subscription has trial_end)
No freemium logic? (expired trial = no access)

8. Subscription Management UX

Verify against stripe-subscription-ux requirements:

Settings Page Exists:

Settings page has subscription section
Current plan name displayed
Subscription status with visual indicator
Next billing date shown
Payment method displayed (brand + last4)

Stripe Portal Integration:

"Manage Subscription" button exists
Button creates portal session and redirects
Return URL configured correctly

Billing History:

Past invoices displayed
Invoice PDFs downloadable
Payment statuses shown

State-Specific UX:

Trial banner shows for trialing users
Canceled state shows period end date
Past due state shows payment update CTA
Active state shows "all good" indicator

This is a hard requirement. If subscription management UX is missing, verification fails. Users must be able to manage their billing.

Output

Verification report:

STRIPE VERIFICATION REPORT
=========================

CONFIGURATION
✓ All env vars present
✓ Webhook URL responds correctly
✓ Stripe CLI connected

CHECKOUT FLOW
✓ Session creates
✓ Payment succeeds
✓ Webhook received
✓ State updated

SUBSCRIPTION STATES
✓ Trial → Active
✓ Active → Canceled
✓ Canceled → Resubscribed
⚠ Trial expiration: not tested (would require waiting)

EDGE CASES
✓ Idempotent webhook handling
✓ Payment decline handled
✗ Out-of-order webhooks: not testable

ACCESS CONTROL
✓ Active: access granted
✓ Trial: access granted
✓ Expired: access denied
✓ Canceled in-period: access granted

BUSINESS MODEL
✓ Single tier
✓ Trial completion on upgrade
✓ No freemium

SUBSCRIPTION MANAGEMENT UX
✓ Settings page has subscription section
✓ Plan name and status displayed
✓ Next billing date shown
✓ Payment method displayed
✓ Manage Subscription button works
✓ Billing history accessible
✓ Trial banner for trialing users
✓ Canceled state messaging
⚠ Past due state: not tested

---
STATUS: VERIFIED (with minor gaps)

When to Run

After stripe-setup (new integration)
After stripe-reconcile (fixes applied)
Before production deployment
Periodically as health check

Deep Mode