Stripe Checkout 接入：从创建到上线的完整指南

// 创建一次性付费产品
const product = await stripe.products.create({
  name: 'AI Pro 月度会员',
  description: '解锁全部 AI 功能，每月 1000 次调用额度',
})
 
// 为产品创建价格
const price = await stripe.prices.create({
  product: product.id,
  unit_amount: 2999, // 单位：分，即 $29.99
  currency: 'usd',
  recurring: { interval: 'month' }, // 月付订阅
})

// app/api/checkout/route.ts
import Stripe from 'stripe'
import { NextRequest, NextResponse } from 'next/server'
 
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: '2024-12-18.acacia',
})
 
export async function POST(req: NextRequest) {
  const { priceId, mode = 'subscription' } = await req.json()
 
  const session = await stripe.checkout.sessions.create({
    mode: mode as Stripe.Checkout.SessionCreateParams.Mode,
    payment_method_types: ['card'],
    line_items: [
      {
        price: priceId,
        quantity: 1,
      },
    ],
    // 支付成功后跳转，{CHECKOUT_SESSION_ID} 会被 Stripe 自动替换
    success_url: `${process.env.NEXT_PUBLIC_BASE_URL}/payment/success?session_id={CHECKOUT_SESSION_ID}`,
    // 用户取消支付后跳转
    cancel_url: `${process.env.NEXT_PUBLIC_BASE_URL}/pricing`,
    // 自动收集账单地址
    billing_address_collection: 'auto',
    // 始终创建 Customer 对象，方便后续管理
    customer_creation: 'always',
  })
 
  return NextResponse.redirect(session.url!, 303)
}

# server.py
import stripe
from flask import Flask, redirect, request
 
stripe.api_key = 'sk_test_xxxx'
app = Flask(__name__)
 
@app.route('/create-checkout-session', methods=['POST'])
def create_checkout_session():
    session = stripe.checkout.Session.create(
        mode='subscription',
        payment_method_types=['card'],
        line_items=[{
            'price': request.json.get('price_id'),
            'quantity': 1,
        }],
        success_url='https://yourdomain.com/payment/success?session_id={CHECKOUT_SESSION_ID}',
        cancel_url='https://yourdomain.com/pricing',
        billing_address_collection='auto',
        customer_creation='always',
    )
    return redirect(session.url, code=303)

// components/CheckoutButton.tsx
export function CheckoutButton({ priceId }: { priceId: string }) {
  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault()
    // 提交到后端 API，后端会 303 重定向到 Stripe
    const response = await fetch('/api/checkout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ priceId }),
    })
    // fetch 不会自动跟随 303，需要手动跳转
    window.location.href = response.url
  }
 
  return (
    <form onSubmit={handleSubmit}>
      <button type="submit" className="btn-primary">
        订阅 Pro 会员 — $29.99/月
      </button>
    </form>
  )
}

import { loadStripe } from '@stripe/stripe-js'
 
const stripe = await loadStripe(process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY!)
 
// 获取 session ID 后直接跳转
const { error } = await stripe.redirectToCheckout({ sessionId })

// app/api/webhooks/stripe/route.ts
import Stripe from 'stripe'
import { NextRequest } from 'next/server'
 
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!)
const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET!
 
export async function POST(req: NextRequest) {
  const body = await req.text()
  const signature = req.headers.get('stripe-signature')!
 
  let event: Stripe.Event
  try {
    event = stripe.webhooks.constructEvent(body, signature, webhookSecret)
  } catch (err) {
    return new Response('Webhook signature verification failed', { status: 400 })
  }
 
  switch (event.type) {
    case 'checkout.session.completed': {
      const session = event.data.object as Stripe.Checkout.Session
      // 支付成功，执行履约逻辑
      // 例如：更新用户权限、发送确认邮件、记录订单
      await fulfillOrder(session)
      break
    }
    case 'customer.subscription.updated': {
      // 订阅状态变更（续费成功、降级、取消等）
      await handleSubscriptionChange(event.data.object)
      break
    }
    case 'invoice.payment_failed': {
      // 续费失败，通知用户更新支付方式
      await handlePaymentFailure(event.data.object)
      break
    }
  }
 
  return new Response('ok', { status: 200 })
}

stripe listen --forward-to localhost:3000/api/webhooks/stripe

const session = await stripe.checkout.sessions.create({
  // ...其他参数
  locale: 'zh-CN', // 强制中文
  // 限制允许的国家
  shipping_address_collection: {
    allowed_countries: ['US', 'CA', 'GB', 'DE', 'JP', 'SG'],
  },
})

const session = await stripe.checkout.sessions.create({
  // ...其他参数
  custom_fields: [
    {
      key: 'company_name',
      label: { type: 'custom', custom: '公司名称（选填）' },
      type: 'text',
      optional: true,
    },
    {
      key: 'referral_code',
      label: { type: 'custom', custom: '推荐码' },
      type: 'text',
      optional: true,
    },
  ],
})

const session = await stripe.checkout.sessions.create({
  // ...其他参数
  payment_method_types: ['card', 'alipay', 'wechat_pay'],
  payment_method_options: {
    wechat_pay: {
      client: 'web', // 在网页端使用微信支付
    },
  },
})

const session = await stripe.checkout.sessions.create({
  mode: 'payment',
  line_items: [{ price: 'price_xxx', quantity: 1 }],
  metadata: {
    userId: 'usr_abc123',
    creditAmount: '100',
    packageType: 'starter',
  },
  success_url: `${BASE_URL}/dashboard?session_id={CHECKOUT_SESSION_ID}`,
  cancel_url: `${BASE_URL}/pricing`,
})