Stripe Payment Failures 生产环境处理手册：如何挽回 3-7% 的收入损失

import Stripe from 'stripe'

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!)

async function chargeSubscription(customerId: string, amount: number) {
  const idempotencyKey = `sub_${customerId}_${Date.now()}`

  const paymentIntent = await stripe.paymentIntents.create(
    {
      amount: Math.round(amount * 100), // cents
      currency: 'usd',
      customer: customerId,
      automatic_payment_methods: { enabled: true },
    },
    {
      idempotencyKey,
      // Stripe 会保留结果 24 小时
      // 任何使用相同密钥的重试都会返回原始结果
    },
  )

  return paymentIntent
}

async function retryWithBackoff<T>(
  fn: () => Promise<T>,
  maxAttempts = 3,
): Promise<T> {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn()
    } catch (error) {
      const isRetryable =
        error.code === 'API_CONNECTION_ERROR' ||
        error.code === 'RATE_LIMIT_ERROR' ||
        (error.statusCode >= 500 && error.statusCode < 600)

      if (!isRetryable || attempt === maxAttempts) {
        throw error
      }

      // 带 ±20% 抖动的指数退避
      const baseDelay = Math.min(1000 * Math.pow(2, attempt - 1), 30000)
      const jitter = baseDelay * (0.8 + Math.random() * 0.4)
      const delay = Math.min(jitter, 30000)

      console.warn(`Stripe error (attempt ${attempt}/${maxAttempts}), retrying in ${Math.round(delay)}ms:`, error.message)
      await sleep(delay)
    }
  }
  throw new Error('Max retry attempts exceeded')
}

function sleep(ms: number) {
  return new Promise(resolve => setTimeout(resolve, ms))
}

import Stripe from 'stripe'

async function getCustomerPortalUrl(customerId: string, returnUrl: string) {
  const session = await stripe.billingPortal.sessions.create({
    customer: customerId,
    return_url: returnUrl,
  })
  return session.url
}

import Stripe from 'stripe'
import crypto from 'crypto'

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!)
const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET!

export async function handleStripeWebhook(
  body: Buffer,
  signature: string,
): Promise<void> {
  let event: Stripe.Event

  try {
    event = stripe.webhooks.constructEvent(body, signature, webhookSecret)
  } catch (err) {
    console.error('Webhook signature verification failed:', err.message)
    throw new Error(`Webhook Error: ${err.message}`)
  }

  // 处理事件——确认后不要抛出异常
  try {
    await processStripeEvent(event)
  } catch (err) {
    // 记录日志以便调试，但返回 200 确认
    // Stripe 会重试；幂等处理意味着重复是安全的
    console.error('Webhook processing error:', err)
  }
}

async function processStripeEvent(event: Stripe.Event) {
  // 幂等：检查是否已处理
  const processed = await checkEventProcessed(event.id)
  if (processed) return // 安全重复——确认已发送

  switch (event.type) {
    case 'invoice.payment_failed':
      await handlePaymentFailed(event.data.object as Stripe.Invoice)
      break
    case 'customer.subscription.updated':
      await handleSubscriptionUpdated(event.data.object as Stripe.Subscription)
      break
    case 'payment_intent.succeeded':
      await handlePaymentSucceeded(event.data.object as Stripe.PaymentIntent)
      break
  }

  await markEventProcessed(event.id)
}

async function updateSubscriptionRetryBehavior(subscriptionId: string) {
  await stripe.subscriptions.update(subscriptionId, {
    default_payment_behavior: 'allow_payment_methods_need_invoice',
    default_settings: {
      billing_cycle_anchor: 'unchanged',
    },
    items: [
      {
        id: (await stripe.subscriptions.retrieve(subscriptionId)).items.data[0].id,
        payment_behavior: 'pending_if_incomplete',
      },
    ],
    proration_behavior: 'create_prorations',
  })
}