Payments & Billing Engineering Skill

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

| Task | Default Picks | Notes | |------|---------------|-------| | Subscription billing | Stripe Checkout (hosted) | Omit payment_method_types for dynamic methods | | MoR / tax compliance | Stripe Managed Payments / Paddle / LemonSqueezy | MoR handles VAT/sales tax for you | | Mobile subscriptions | RevenueCat | Wraps App Store + Google Play | | Enterprise / high-volume | Adyen | 250+ payment methods, interchange++ pricing | | Complex billing logic | Chargebee / Recurly on top of Stripe | Per-seat + usage, contract billing, revenue recognition | | Usage-based billing | Stripe Billing Meters or Lago (open-source) | API calls, AI tokens, compute metering | | UK Direct Debit | GoCardless | Bacs/SEPA/ACH DD, lowest involuntary churn | | EU multi-method | Mollie | iDEAL, Bancontact, SEPA DD, Klarna — 25+ methods | | Online + POS | Square | Unified commerce: online payments + in-person readers | | Bank-to-bank (A2A) | Open Banking (TrueLayer / Yapily) | Zero card fees, instant settlement, no chargebacks | | Webhook handling | Verify signature + idempotent handlers | Stripe retries for 3 days | | Feature gating | Tier hierarchy + feature matrix | Check at API boundary | | One-time purchases | Stripe Checkout mode: 'payment' | Alongside subscriptions | | Billing portal | Stripe Customer Portal | Self-service management | | Regional pricing | PPP-adjusted prices per country | Use x-vercel-ip-country or GeoIP | | PayPal button | Stripe PayPal method or PayPal Commerce Platform | Avoid Braintree — deprecated 2026, EOL Jan 2027 | | BNPL (e-commerce) | Klarna (via Stripe/Mollie/direct) | Split payments; UK regulation expected 2026-27 | | Testing | Stripe CLI + test cards | 4242 4242 4242 4242 |

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):

| Layer | Role | Examples | |-------|------|----------| | Payment Processor | Moves money, payment methods, fraud | Stripe, Adyen, Mollie, Square | | Merchant of Record (MoR) | Handles tax, legal, disputes for you | Paddle, LemonSqueezy, Stripe Managed Payments | | Billing Orchestrator | Subscription logic, dunning, revenue recognition | Chargebee, Recurly, Lago (open-source) | | Direct Debit | Bank-account recurring pulls | GoCardless (Bacs, SEPA, ACH) | | Open Banking (A2A) | Bank-to-bank instant payments | TrueLayer, Yapily |

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

| Event | When | Handler Pattern | |-------|------|-----------------| | checkout.session.completed | Checkout finishes | Link Stripe customer to user, create subscription record | | checkout.session.expired | Abandoned checkout | Fire-and-forget analytics (never fail the response) | | customer.subscription.created | New subscription | Upsert subscription record with tier, status, period | | customer.subscription.updated | Plan change, renewal, cancel-at-period-end | Update tier, status, cancel flags | | customer.subscription.deleted | Subscription ends | Reset to free tier | | invoice.payment_succeeded | Successful charge | Update period dates, process referral rewards | | invoice.payment_failed | Failed charge | Set status to past_due | | customer.subscription.trial_will_end | 3 days before trial ends | Trigger retention email |

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

| FAIL Avoid | PASS Instead | Why | |------------|--------------|-----| | payment_method_types: ['card'] | Omit the field entirely | Blocks Apple Pay, Google Pay, Link, local methods | | Trusting client-side checkout callback | Use webhooks as source of truth | Client can close browser before callback | | new Stripe(key) at module top level | Lazy-initialize in a function | Build fails when env var is undefined | | Catching webhook errors silently | Log + return 500 so Stripe retries | Lost events = lost revenue | | Storing subscription state only client-side | Sync from webhook to DB | Single source of truth | | Hardcoding prices in code | Use Stripe Price objects via env vars | Prices change, regional variants | | Skipping webhook signature verification | Always verify with constructEvent() | Prevents replay/spoofing attacks | | Using invoice.subscription (2025+) | Use invoice.parent.subscription_details | Breaking change since 2025-11-17.clover | | await on fire-and-forget analytics | Don't await, don't throw | Non-critical tracking must not fail webhooks | | Missing UUID validation on user_id from metadata | Validate with regex before DB operations | Prevents injection and corrupt data | | Creating checkout without checking existing subscription | Check and use upgrade flow if active | Prevents duplicate subscriptions | | Using --no-verify for Stripe webhook testing | Use Stripe CLI: stripe listen --forward-to | Real signature verification in dev |

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

| Card | Scenario | |------|----------| | 4242 4242 4242 4242 | Successful payment | | 4000 0000 0000 0002 | Declined | | 4000 0000 0000 3220 | 3D Secure required | | 4000 0000 0000 9995 | Insufficient funds |

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

Start from data/sources.json (official docs, changelogs, API versions).
Run a targeted web search for the specific platform and feature.
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.

Agent Skills: Payments & Billing Engineering

Install this agent skill to your local

Skill Files