---

name: stripe-integration description: "掌握 Stripe 支付处理集成，实现健壮的、符合 PCI 标准的支付流程，包括结账、订阅、Webhook 和退款。" risk: unknown source: community date_added: "2026-02-27"

Stripe 集成

掌握 Stripe 支付处理集成，实现健壮的、符合 PCI 标准的支付流程，包括结账、订阅、Webhook 和退款。

不适用场景

• 任务与 Stripe 集成无关
• 需要此范围之外的不同领域或工具

使用说明

• 明确目标、约束和所需输入。
• 应用相关最佳实践并验证结果。
• 提供可操作的步骤和验证方法。
• 如需详细示例，请打开 resources/implementation-playbook.md。

适用场景

• 在 Web/移动应用中实现支付处理
• 设置订阅计费系统
• 处理一次性支付和循环扣费
• 处理退款和争议
• 管理客户支付方式
• 为欧洲支付实现 SCA（强客户认证）
• 使用 Stripe Connect 构建市场支付流程

核心概念

1. 支付流程

Checkout Session（托管式）

• Stripe 托管的支付页面
• 最小的 PCI 合规负担
• 最快的实现方式
• 支持一次性和循环支付

Payment Intents（自定义 UI）

• 完全控制支付 UI
• 需要 Stripe.js 以符合 PCI 标准
• 实现更复杂
• 更好的自定义选项

Setup Intents（保存支付方式）

• 收集支付方式但不扣费
• 用于订阅和未来支付
• 需要客户确认

2. Webhooks

关键事件：

• payment_intent.succeeded：支付完成
• payment_intent.payment_failed：支付失败
• customer.subscription.updated：订阅变更
• customer.subscription.deleted：订阅取消
• charge.refunded：退款已处理
• invoice.payment_succeeded：订阅付款成功

3. 订阅

组成部分：

• Product：你销售的产品
• Price：价格和频率
• Subscription：客户的循环支付
• Invoice：每个计费周期生成的发票

4. 客户管理

• 创建和管理客户记录
• 存储多种支付方式
• 跟踪客户元数据
• 管理账单详情

快速开始

import stripe

stripe.api_key = "sk_test_..."

# 创建结账会话
session = stripe.checkout.Session.create(
    payment_method_types=['card'],
    line_items=[{
        'price_data': {
            'currency': 'usd',
            'product_data': {
                'name': 'Premium Subscription',
            },
            'unit_amount': 2000,  # $20.00
            'recurring': {
                'interval': 'month',
            },
        },
        'quantity': 1,
    }],
    mode='subscription',
    success_url='https://yourdomain.com/success?session_id={CHECKOUT_SESSION_ID}',
    cancel_url='https://yourdomain.com/cancel',
)

# 将用户重定向到 session.url
print(session.url)

支付实现模式

模式 1：一次性支付（托管结账）

def create_checkout_session(amount, currency='usd'):
    """创建一次性支付结账会话。"""
    try:
        session = stripe.checkout.Session.create(
            payment_method_types=['card'],
            line_items=[{
                'price_data': {
                    'currency': currency,
                    'product_data': {
                        'name': 'Purchase',
                        'images': ['https://example.com/product.jpg'],
                    },
                    'unit_amount': amount,  # 金额以分为单位
                },
                'quantity': 1,
            }],
            mode='payment',
            success_url='https://yourdomain.com/success?session_id={CHECKOUT_SESSION_ID}',
            cancel_url='https://yourdomain.com/cancel',
            metadata={
                'order_id': 'order_123',
                'user_id': 'user_456'
            }
        )
        return session
    except stripe.error.StripeError as e:
        # 处理错误
        print(f"Stripe error: {e.user_message}")
        raise

模式 2：自定义 Payment Intent 流程

def create_payment_intent(amount, currency='usd', customer_id=None):
    """为自定义结账 UI 创建 payment intent。"""
    intent = stripe.PaymentIntent.create(
        amount=amount,
        currency=currency,
        customer=customer_id,
        automatic_payment_methods={
            'enabled': True,
        },
        metadata={
            'integration_check': 'accept_a_payment'
        }
    )
    return intent.client_secret  # 发送到前端