stripe-integration

Stripe 集成

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

何时使用此技能

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

核心概念

1. 支付流程

Checkout Sessions

• 推荐用于大多数集成
• 支持所有 UI 路径：
  • Stripe 托管的结账页面
  • 嵌入式结账表单
  • 使用 Elements（Payment Element、Express Checkout Element）并通过 ui_mode='custom' 构建的自定义 UI
• 提供内置结账能力（行项目、折扣、税费、配送、地址收集、已保存的支付方式，以及结账生命周期事件）
• 与 Payment Intents 相比，集成和维护负担更低

Payment Intents（定制控制）

• 你需要自行计算含税费、折扣、订阅和货币换算的最终金额。
• 实现更复杂，长期维护负担更高
• 为符合 PCI 规范需要使用 Stripe.js

Setup Intents（保存支付方式）

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

2. Webhook

关键事件：

• 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_..."

# Create a checkout session
session = stripe.checkout.Session.create(
    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'
)

# Redirect user to session.url
print(session.url)

详细模式与完整示例

详细的模式文档位于 references/details.md。当上述导航层级不够用时，请阅读该文件。

测试

# Use test mode keys
stripe.api_key = "sk_test_..."

# Test card numbers
TEST_CARDS = {
    'success': '4242424242424242',
    'declined': '4000000000000002',
    '3d_secure': '4000002500003155',
    'insufficient_funds': '4000000000009995'
}

def test_payment_flow():
    """Test complete payment flow."""
    # Create test customer
    customer = stripe.Customer.create(
        email="[email protected]"
    )

    # Create payment intent
    intent = stripe.PaymentIntent.create(
        amount=1000,
        automatic_payment_methods={
            'enabled': True
        },
        currency='usd',
        customer=customer.id
    )

    # Confirm with test card
    confirmed = stripe.PaymentIntent.confirm(
        intent.id,
        payment_method='pm_card_visa'  # Test payment method
    )

    assert confirmed.status == 'succeeded'