Stripe Testing Best Practices: From Test Cards to Production Confidence

Scaling Self-Hosted Cloud Applications: From 1K to 100K+ Users

A practical guide to scaling Nextcloud, OpenDesk, and similar self-hosted cloud platforms through four growth tiers, with concrete configurations and architecture patterns.

Introduction

Stripe makes payments easy to integrate. Testing those payments reliably is another matter entirely. A single missed edge case — an unpaid session recorded as a purchase, a webhook replayed twice, or a download URL controlled by the client — can cost you real money and real customer trust.

This guide covers the complete Stripe testing paradigm, distilled from building and hardening a production checkout system with digital downloads, physical orders, and subscription billing.

The Stripe Testing Landscape

Test Mode vs Live Mode

Stripe operates in two modes, toggled in the Dashboard:

Key insight: Your server code doesn't change between modes. The only difference is which API keys you use. This means your test infrastructure should mirror production exactly — same webhook handlers, same idempotency logic, same validation.

When Test Cards Work

Test card numbers (like 4242424242424242) work in two scenarios:

1. Test mode keys (sk_test_*) — always work, whether through API or Checkout
2. Live mode keys (sk_live_*) — accepted by the API (session creation succeeds), but rejected by Stripe Checkout's hosted payment page at the point of payment

This means you can create checkout sessions programmatically with live keys and test cards, but the customer-facing payment step will fail. For end-to-end testing, always use test keys.

Essential Test Card Numbers

Not all test cards are equal. Stripe provides a rich set of cards to simulate specific scenarios:

Basic Success and Failure

3D Secure (3DS) Authentication

Pro tip: Test 3DS cards with payment_method_options[card][request_three_d_secure] = 'any' to ensure your flow handles authentication challenges.

Edge Cases That Matter

Testing the Checkout Flow

Architecture Overview

A typical Stripe checkout integration has four stages:

Critical Guard: payment_status and mode

One of the most common bugs: the checkout.session.completed webhook fires for all checkout sessions — including unpaid ones. SEPA payments arrive with payment_status: "unpaid" initially. Subscription checkouts fire this event too.

// ❌ WRONG — records purchases for unpaid sessions
case "checkout.session.completed": {
  const session = event.data.object;
  // Missing: no check on payment_status or mode!
  pushPurchase({ session_id: session.id, ... });
}

// ✅ CORRECT — only record completed payments
case "checkout.session.completed": {
  const session = event.data.object;
  if (session.mode !== "payment" || session.payment_status !== "paid") {
    logger.info(`Skipping non-payment: ${session.id}`);
    break;
  }
  pushPurchase({ session_id: session.id, ... });
}

Critical Guard: Never Trust Client-Supplied Download URLs

A sophisticated attack: an attacker buys the cheapest product but overrides downloadUrl in the checkout request to point at an expensive product's file. The flow:

The fix: resolve download paths server-side from content frontmatter, ignoring client metadata entirely.

// Server-side resolver — single source of truth
export async function resolveProductDownloadUrl(slug: string) {
  const content = await getContent("products", slug);
  return content?.frontmatter?.download_url || null;
}

// In webhook: resolve from content, not from client metadata
const downloadUrl = await resolveProductDownloadUrl(item.slug);
const token = signDownloadToken({ product_slug: slug, download_url: downloadUrl });

Webhook Testing Strategies

Strategy 1: Unit Tests with Mocks (Fastest)

Mock Stripe's webhook construction and test your handler logic in isolation:

// tests/unit/api/stripe/webhook.test.ts
vi.mock("@/lib/stripe", () => ({
  constructWebhookEvent: mockConstructEvent,
}));

it("records purchase for paid checkout", async () => {
  mockConstructEvent.mockReturnValue({
    type: "checkout.session.completed",
    data: {
      object: {
        mode: "payment",
        payment_status: "paid",
        id: "cs_test_123",
        metadata: { productName: "Test", productSlug: "test" },
        customer_details: { email: "buyer@test.com" },
      },
    },
  });

  const res = await POST(mockRequest("{}", "sig_abc"));
  expect(res._status).toBe(200);
  expect(mockPurchases).toHaveLength(1);
  expect(mockSendMail).toHaveBeenCalled();
});

Coverage targets for webhook tests:

Strategy 2: Stripe CLI Forwarding (Integration Test)

Install the Stripe CLI and forward real webhook events to your local server:

# Install (macOS)
brew install stripe/stripe-cli/stripe

# Login (gets your test-mode API key)
stripe login

# Forward webhooks to localhost:3000
stripe listen --forward-to localhost:3000/api/stripe/webhook

# This prints your webhook signing secret (whsec_...)
# Add it to your .env.local:
# STRIPE_WEBHOOK_SECRET=whsec_xxx

Then trigger a test event:

# Trigger a checkout completion event
stripe trigger checkout.session.completed

# Trigger a payment failure
stripe trigger payment_intent.payment_failed

# Trigger a subscription event
stripe trigger customer.subscription.updated

Strategy 3: Back-to-Back Flow Tests

Test the entire flow: checkout → webhook → download, including state management across calls:

it("checkout → webhook → download flow succeeds", async () => {
  // 1. Create checkout
  const checkout = await createCheckout({ priceId: "price_test", ... });
  expect(checkout._data.checkoutURL).toBeDefined();

  // 2. Fire webhook (simulates Stripe calling your server)
  mockConstructEvent.mockReturnValue({
    type: "checkout.session.completed",
    data: { object: { mode: "payment", payment_status: "paid", ... } },
  });
  const webhook = await webhookHandler(mockRequest({}, "sig"));
  expect(webhook._status).toBe(200);

  // 3. Download with signed token
  const token = signDownloadToken({ session_id: "cs_123", ... });
  mockRetrieve.mockResolvedValue({ payment_status: "paid" });
  const download = await downloadHandler(mockDownloadRequest(token));
  expect(download._status).toBe(200);
});

CI/CD Testing Strategy

Test Matrix

What to Run Where

Environment Variable Strategy

# .env.local (development)
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_test_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...

# .env.production (production)
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_live_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_...

Never commit real keys. Use .env.local (gitignored) for development and a secrets manager for production.

Security Checklist for Stripe Integrations

Webhook Verification

Always verify webhook signatures. Never trust raw webhook payloads.

import crypto from "crypto";

function constructWebhookEvent(body: string, signature: string) {
  const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET!;
  if (!webhookSecret) throw new Error("Not configured");

  const elements = signature.split(",");
  const timestamp = elements.find((e) => e.startsWith("t="))?.slice(2);
  const sig = elements.find((e) => e.startsWith("v1="))?.slice(3);

  if (!timestamp || !sig) throw new Error("Invalid signature format");

  // Reject events older than 5 minutes (replay protection)
  const age = Math.floor(Date.now() / 1000) - parseInt(timestamp);
  if (age > 300) throw new Error("Stale webhook");

  const signedPayload = `${timestamp}.${body}`;
  const expected = crypto.createHmac("sha256", webhookSecret).update(signedPayload).digest("hex");

  if (sig !== expected) throw new Error("Signature mismatch");

  return JSON.parse(body);
}

Idempotency

Webhooks can be delivered multiple times. Always check for duplicates:

// Before processing
const existing = loadPurchases();
if (existing.some((p) => p.session_id === session.id)) {
  logger.info("Duplicate webhook — skipping");
  break;
}

Rate Limiting

Rate-limit all Stripe-facing endpoints:

// Create checkout — external API call
const isRateLimited = createRateLimiter(60_000, 10); // 10 per minute per IP

Cryptographic OTP

Don't use Math.random() for OTPs. Use the Web Crypto API:

export function generateOTP(): string {
  const buf = new Uint32Array(1);
  crypto.getRandomValues(buf);
  return String(100000 + (buf[0] % 900000));
}

Token Security

Download tokens must be:

• Signed (HMAC) — prevents tampering
• Time-limited (24 hours) — prevents indefinite reuse
• Bound to a session — prevents sharing across purchases
• Resolved server-side — prevents URL manipulation

Common Pitfalls

1. Metadata Size Limit

Stripe metadata values are limited to 500 characters. A cart with 20+ items can exceed this:

// ❌ Unbounded
metadata.items = JSON.stringify(items);

// ✅ Guard size
const itemsJson = JSON.stringify(items.slice(0, 20));
metadata.items = itemsJson.length > 490 ? itemsJson.slice(0, 487) + '..."' : itemsJson;

2. Subscription vs Payment Events

checkout.session.completed fires for BOTH payment and subscription checkouts. Your handler must check session.mode:

if (session.mode !== "payment") break; // subscriptions use customer.subscription.* events

3. Canceled Subscription State

customer.subscription.updated fires on any subscription change, including cancellation. Don't blindly clear canceled_at:

// ❌ Wrong — wipes cancellation date
canceled_at: undefined;

// ✅ Correct — preserve unless reactivated
canceled_at: sub.status === "active"
  ? undefined
  : sub.canceled_at
    ? new Date(sub.canceled_at * 1000).toISOString()
    : undefined;

4. Rate Limiting After Body Parsing

If your rate limiter runs after request.json(), an attacker can exhaust your server's resources before being throttled:

// ❌ Wrong — body parsed before rate check
const body = await request.json();
if (isRateLimited(ip)) return 429;

// ✅ Correct — rate check before parsing
if (isRateLimited(ip)) return 429;
const body = await request.json();

5. localStorage Access Without try/catch

In private browsing or when storage is blocked, localStorage.getItem() throws:

// ❌ Crashes in private browsing
const [email] = useState(() => localStorage.getItem(KEY));

// ✅ Safe
const [email] = useState(() => {
  try {
    return localStorage.getItem(KEY) || "";
  } catch {
    return "";
  }
});

Testing Checklist

Run through this checklist before every release:

• All unit tests pass (webhook, checkout, download, token)
• Back-to-back flow test passes (checkout → webhook → download)
• Test card 4242 succeeds end-to-end (Stripe CLI mode)
• Decline card 4000000000000002 handled gracefully
• Duplicate webhook delivery is idempotent
• Unpaid session (payment_status: unpaid) is skipped
• Subscription checkout (mode: subscription) is skipped
• Download token expires after time limit
• Metadata size guard works for 20+ item carts
• Rate limiting works on all Stripe endpoints
• OTP uses cryptographic random (not Math.random)
• Webhook signature verification works
• Production keys are NOT committed to git
• Stripe webhook endpoint is registered in Dashboard

Conclusion

Testing Stripe integrations isn't optional — it's a security requirement. A single vulnerability in payment handling can lead to inventory theft, customer data exposure, or revenue loss.

The pattern is always the same: never trust client input, verify everything server-side, and test edge cases that Stripe's happy path documentation doesn't cover.

The investment in comprehensive testing pays for itself the first time a webhook is replayed, a card is declined, or a customer disputes a charge. Build the testing infrastructure once, run it on every commit, and ship payments with confidence.