技能檔案

Software Payments

Name: Software Payments
Author: vasilyu1983

Production-grade payment integration for Stripe, Paddle, Adyen, and more. Use when implementing checkout, subscriptions, webhooks, or billing.

vasilyu198356 星標2026年3月12日

職業
分類: 支付

技能內容

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

相關技能

Software Payments | Skills Pool

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

// 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

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
  // ...
});

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

// 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);
}

// 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);
}

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

# 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

Software Payments

Payments & Billing Engineering

Quick Reference

Software Payments

Payments & Billing Engineering

Quick Reference

Scope

When NOT to Use This Skill

Decision Tree: Payment Platform Selection

Stripe Integration Patterns (Feb 2026)

1. Client Initialization

2. Checkout Session Creation

3. Webhook Handler Architecture

Essential Webhook Events

Fire-and-Forget Pattern for Non-Critical Tracking

4. Subscription Tier Model

5. Upgrade/Downgrade Flow

6. Regional / PPP Pricing

7. One-Time Purchases Alongside Subscriptions

8. Billing Portal

9. Referral/Coupon Integration

Feature Gating Patterns

Stripe API Version Notes

Common Mistakes and Anti-Patterns

E2E Testing Patterns

Checkout Contract Propagation

Security Checklist

Navigation

Freshness Protocol

Trigger Conditions

How to Freshness-Check

What to Report

Ops Runbook

Fact-Checking

Customer Billing Ops

Billing Automation

Paypal Integration

Stripe Integration

Pci Compliance

Square Automation