Software Payments

Payments & Billing Engineering

Use this skill to design, implement, and debug production payment integrations: checkout flows, subscription management, webhook handling, regional pricing, feature gating, one-time purchases, billing portals, and payment testing.

Defaults bias toward: Stripe as primary processor (most common), webhooks as source of truth, idempotent handlers, lazy-initialized clients, dynamic payment methods, Zod validation at boundaries, structured logging, and fire-and-forget for non-critical tracking. For complex billing, consider a billing orchestrator (Chargebee, Recurly, Lago) on top of Stripe/Adyen.

Quick Reference

Scope

Use this skill to:

• Implement checkout flows (hosted, embedded, custom)
• Build subscription lifecycle management (create, upgrade, downgrade, cancel)
• Handle webhooks reliably (signature verification, idempotency, error handling)
• Set up regional/multi-currency pricing (PPP, emerging markets)
• Build feature gating and entitlement systems
• Implement one-time purchases alongside subscriptions
• Create billing portal integrations
• Test payment flows end-to-end
• Debug common payment integration issues

When NOT to Use This Skill

Use a different skill when:

• General backend patterns -> See software-backend
• API design only (no payments) -> See dev-api-design
• Conversion optimization -> See marketing-cro
• Business model / pricing strategy -> See startup-business-models
• Security audits -> See software-security-appsec

Decision Tree: Payment Platform Selection

Three platform layers (can be combined):

Payment integration needs: [Business Model]

  STEP 1: Choose your processor
    - Default / most common -> Stripe
    - Enterprise, >$1M/yr, 250+ payment methods -> Adyen
    - EU-focused, need iDEAL/Bancontact/SEPA -> Mollie
    - Need PayPal button -> Stripe (PayPal method) or PayPal Commerce Platform
    - WARNING: Do NOT start new projects on Braintree (deprecated 2026, EOL Jan 2027)

  STEP 2: Do you need a MoR?
    - Handle own tax + compliance -> Skip MoR, use processor directly
    - Want tax/VAT/disputes handled -> Stripe Managed Payments, Paddle, LemonSqueezy
    - Indie / small SaaS -> LemonSqueezy (simplest MoR)
    - EU-heavy customer base -> Paddle (strongest EU VAT handling)

  STEP 3: Is billing logic complex?
    - Simple tiers (free/pro/enterprise) -> Stripe Billing is sufficient
    - Per-seat + usage, contract billing, rev-rec -> Chargebee or Recurly on top of Stripe
    - Usage-based (API calls, AI tokens) -> Stripe Billing Meters or Lago (open-source)
    - B2C subscriptions, churn focus -> Recurly (strong revenue recovery)

  STEP 4: Platform-specific needs
    - Mobile app (iOS/Android) -> RevenueCat (wraps both stores)
    - Hybrid (web + app) -> RevenueCat + Stripe (share customer IDs)
    - Marketplace / multi-party -> Stripe Connect
    - UK Direct Debit recurring -> GoCardless (Bacs DD, lowest involuntary churn)
    - Multi-method EU checkout -> Mollie (25+ methods, single integration)
    - Online + in-person POS -> Square (unified commerce)
    - High-value A2A / zero card fees -> Open Banking (TrueLayer)
    - BNPL for e-commerce -> Klarna (via Stripe, Mollie, or direct)
    - One-time digital goods -> Stripe Checkout (payment mode)
    - Physical goods -> Stripe + shipping integration
    - Emerging markets / PPP -> Multiple Stripe Price objects per region
    - Multi-currency -> Stripe multi-currency or Paddle (auto-converts)
    - B2B invoicing -> Stripe Invoicing

For detailed platform comparison tables, see references/platform-comparison.md. For UK/EU-specific platforms (GoCardless, Mollie, Square, Klarna, Open Banking), see references/uk-eu-payments-guide.md.

Stripe Integration Patterns (Feb 2026)

1. Client Initialization

CRITICAL: Lazy-initialize the Stripe client. Import-time initialization fails during build/SSR when env vars aren't available.

// CORRECT: Lazy initialization with proxy for backwards compatibility
import Stripe from 'stripe';

let _stripe: Stripe | null = null;

export function getStripeServer(): Stripe {
  if (!_stripe) {
    const secretKey = process.env.STRIPE_SECRET_KEY;
    if (!secretKey) {
      throw new Error('STRIPE_SECRET_KEY is not configured');
    }
    _stripe = new Stripe(secretKey, {
      apiVersion: '2026-01-28.clover', // Pin to specific version
      typescript: true,
    });
  }
  return _stripe;
}

// Proxy for convenience (backwards-compatible named export)
export const stripe = {
  get customers() { return getStripeServer().customers; },
  get subscriptions() { return getStripeServer().subscriptions; },
  get checkout() { return getStripeServer().checkout; },
  get billingPortal() { return getStripeServer().billingPortal; },
  get webhooks() { return getStripeServer().webhooks; },
};

// WRONG: Crashes during build when STRIPE_SECRET_KEY is undefined
import Stripe from 'stripe';
export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!); // Build failure

2. Checkout Session Creation

CRITICAL: Do NOT set payment_method_types. Omitting it enables Stripe's dynamic payment method selection (Apple Pay, Google Pay, Link, bank transfers, local methods) based on customer region and device.

const session = await stripe.checkout.sessions.create({
  customer: customerId,
  mode: 'subscription',
  // DO NOT set payment_method_types — let Stripe auto-select
  line_items: [{ price: priceId, quantity: 1 }],
  subscription_data: {
    trial_period_days: 7,
    metadata: {
      user_id: userId,
      billing_interval: interval,
    },
  },
  success_url: `${appUrl}/dashboard?checkout=success&tier=${tier}`,
  cancel_url: `${appUrl}/dashboard?checkout=canceled`,
  allow_promotion_codes: true,
  billing_address_collection: 'auto',
  metadata: {
    user_id: userId,
    tier,
    billing_interval: interval,
  },
});

// WRONG: Limits to cards only, blocks Apple Pay, Google Pay, Link, etc.
const session = await stripe.checkout.sessions.create({
  payment_method_types: ['card'], // REMOVE THIS
  // ...
});

3. Webhook Handler Architecture

Webhooks are the source of truth for subscription state. Never trust client-side callbacks alone.

Pattern: read raw body as text → verify stripe.webhooks.constructEvent(body, signature, secret) → switch(event.type) → return { received: true } on success or 500 on handler error (so Stripe retries). Full route implementation in references/stripe-patterns.md.

Essential Webhook Events

Fire-and-Forget Pattern for Non-Critical Tracking

For checkout.session.expired (and similar analytics events): call tracking without await, never throw. Non-critical tracking must not cause a webhook 500.

4. Subscription Tier Model

// Type definitions
export type SubscriptionTier = 'free' | 'starter' | 'pro' | 'enterprise';
export type SubscriptionStatus = 'active' | 'trialing' | 'canceled' | 'past_due' | 'incomplete';
export type BillingInterval = 'month' | 'year';

// Tier hierarchy for comparison
export const TIER_HIERARCHY: Record<SubscriptionTier, number> = {
  free: 0,
  starter: 1,
  pro: 2,
  enterprise: 3,
};

// Feature access matrix
export type Feature = 'basic_dashboard' | 'advanced_reports' | 'api_access' | 'priority_support';

const TIER_FEATURES: Record<SubscriptionTier, Feature[]> = {
  free: ['basic_dashboard'],
  starter: ['basic_dashboard', 'advanced_reports'],
  pro: ['basic_dashboard', 'advanced_reports', 'api_access'],
  enterprise: ['basic_dashboard', 'advanced_reports', 'api_access', 'priority_support'],
};

export function hasFeatureAccess(tier: SubscriptionTier, feature: Feature): boolean {
  return TIER_FEATURES[tier].includes(feature);
}

export function isTierUpgrade(current: SubscriptionTier, target: SubscriptionTier): boolean {
  return (TIER_HIERARCHY[target] ?? 0) > (TIER_HIERARCHY[current] ?? 0);
}

5. Upgrade/Downgrade Flow

Use stripe.subscriptions.update() with proration_behavior: 'create_prorations' and the new price on the existing item. Update local DB immediately; webhook will confirm. See full lifecycle in references/subscription-lifecycle.md.

6. Regional / PPP Pricing

Create separate Stripe Price objects per region (standard vs emerging). Use x-vercel-ip-country or GeoIP for detection. Full implementation and market list in references/regional-pricing-guide.md.

7. One-Time Purchases Alongside Subscriptions

// Some products are one-time (e.g., PDF reports, credits)
// but subscribers get unlimited access
export function hasUnlimitedProductAccess(
  tier: SubscriptionTier,
  status: SubscriptionStatus,
  product: OneTimeProduct
): boolean {
  const isActive = status === 'active' || status === 'trialing';
  if (!isActive) return false;
  const productConfig = ONE_TIME_PRODUCTS[product];
  if (!productConfig.unlimitedFeature) return false;
  return hasFeatureAccess(tier, productConfig.unlimitedFeature);
}

8. Billing Portal

Use stripe.billingPortal.sessions.create() to redirect customers to Stripe's self-service portal for plan changes, payment method updates, and cancellation. See references/stripe-patterns.md for portal configuration checklist.

9. Referral/Coupon Integration

Key constraint: allow_promotion_codes and discounts are mutually exclusive in Stripe Checkout. If a referral coupon applies, set discounts: [{ coupon: REFERRAL_COUPON_ID }] and omit allow_promotion_codes. On invoice.payment_succeeded with billing_reason === 'subscription_create', reward the referrer via stripe.customers.createBalanceTransaction().

Feature Gating Patterns

Every paid feature requires enforcement at 3 layers: Feature Registry (maps features to tiers), API Enforcement (returns 403), UI Paywall (shows upgrade CTA). Missing any layer creates a security hole or broken UX.

Key anti-patterns:

• Gate on Wrong Key: If the feature key is in the free tier, the gate is a permanent no-op.
• Polymorphic Field Shapes: transits: Transit[] | { __gated: true } crashes (data.transits || []).sort(). Use consistent shapes with an explicit transitsGated: boolean flag.
• Checkout Mutual Exclusivity: allow_promotion_codes + discounts together = Stripe rejects.

Always verify Stripe SDK TypeScript types (node_modules/stripe/types/), not documentation examples.

For detailed gating architecture (consumables, fraud prevention, discriminated unions), see references/feature-gating-patterns.md.

Stripe API Version Notes

Current version: 2026-01-28.clover. Key breaking change: invoice.subscription replaced by invoice.parent.subscription_details since 2025-11-17.clover. Full version table and migration code in references/stripe-patterns.md.

Common Mistakes and Anti-Patterns

E2E Testing Patterns

Quick reference — full patterns in references/testing-patterns.md.

# Stripe CLI: forward events to local webhook endpoint
stripe listen --forward-to localhost:3001/api/stripe/webhook

# Trigger specific events
stripe trigger checkout.session.completed
stripe trigger invoice.payment_failed

Checkout Contract Propagation

When checkout API response contracts change, treat it as a cross-surface migration. Enumerate all entrypoints, update every caller, route blocked flows to one shared recovery UX. Full checklist in references/in-app-browser-checkout-contract.md and assets/template-checkout-entrypoint-propagation-checklist.md.

Security Checklist

10-point checklist covering webhook signature verification, secrets management, UUID validation, HTTPS, idempotency, and rate limiting. Full checklist in references/stripe-patterns.md.

Navigation

References

• references/stripe-patterns.md - Stripe patterns: webhook handlers, idempotency, status mapping, error handling, dunning, usage-based billing, security checklist, API version notes
• references/platform-comparison.md - Platform comparison: Stripe, Adyen, Paddle, LemonSqueezy, Chargebee, Recurly, Lago, Braintree (deprecated)
• references/uk-eu-payments-guide.md - UK/EU platforms: GoCardless, Mollie, Square, PayPal Commerce, Klarna, Open Banking (TrueLayer, Yapily)
• references/testing-patterns.md - E2E testing: Stripe CLI, Playwright checkout, test cards, state sync
• references/subscription-lifecycle.md - Full subscription state machine, trials, upgrades/downgrades, cancellation, dunning, pause/resume, database schema
• references/regional-pricing-guide.md - PPP implementation, multi-currency Stripe prices, tax by region, fraud prevention, A/B testing pricing
• references/webhook-reliability-patterns.md - Idempotency, retry handling, dead letter queues, monitoring, event ordering, queue-based processing
• references/feature-gating-patterns.md - Feature gating: consumable vs binary unlocks, spread-then-override filtering, fraud prevention, discriminated union typed responses
• references/in-app-browser-checkout-contract.md - Checkout response contract propagation for in-app browser recovery and cross-surface consistency
• references/ops-runbook-checkout-errors.md - Checkout 500 debugging: RLS denials, auth policy, incident loop
• data/sources.json - External documentation links (69 sources)

Templates

• assets/template-checkout-entrypoint-propagation-checklist.md - Migration checklist for contract changes across all checkout callers

Related Skills

• ../software-backend/SKILL.md - Backend API patterns, database, auth
• ../dev-api-design/SKILL.md - API design patterns
• ../marketing-cro/SKILL.md - Conversion optimization for checkout
• ../startup-business-models/SKILL.md - Pricing strategy
• ../software-security-appsec/SKILL.md - Payment security
• ../qa-testing-playwright/SKILL.md - E2E testing patterns

Freshness Protocol

When users ask version-sensitive questions about payment platforms, do a freshness check.

Trigger Conditions

• "What's the best payment platform for [use case]?"
• "Stripe vs Paddle vs LemonSqueezy?"
• "How do I handle [tax/VAT/sales tax]?"
• "What's new in Stripe [API/Billing/Checkout]?"
• "Is Stripe Managed Payments available?"
• "Best mobile subscription SDK?"

How to Freshness-Check

1. Start from data/sources.json (official docs, changelogs, API versions).
2. Run a targeted web search for the specific platform and feature.
3. Prefer official documentation and changelogs over blog posts.

What to Report

• Current landscape: what is stable and widely used now
• Emerging trends: Managed Payments, usage-based billing, entitlements API, Open Banking
• Deprecated/declining: hardcoded payment_method_types, top-level invoice.subscription, Braintree
• Recommendation: default choice + alternatives with trade-offs

Ops Runbook

For checkout 500 errors with RLS/authorization denials: 5-step incident loop, required logging fields, and guardrails. See references/ops-runbook-checkout-errors.md.

Fact-Checking

• Use web search/web fetch to verify current external facts, versions, pricing, deadlines, regulations, or platform behavior before final answers.
• Prefer primary sources; report source links and dates for volatile information.
• If web access is unavailable, state the limitation and mark guidance as unverified.