stripe-integration

Stripe 統合

チェックアウト、サブスクリプション、Webhook、返金を含む、堅牢で PCI 準拠の決済フローに向けた Stripe 決済処理統合をマスターします。

このスキルを使用する場面

• Web/モバイルアプリケーションに決済処理を実装する
• サブスクリプション課金システムを設定する
• 単発の支払いと定期的な課金を処理する
• 返金と異議申し立てを処理する
• 顧客の支払い方法を管理する
• ヨーロッパの支払い向けに SCA (Strong Customer Authentication) を実装する
• Stripe Connect を使ったマーケットプレイスの決済フローを構築する

中核となる概念

1. 決済フロー

Checkout Sessions

• ほとんどの統合で推奨されます
• すべての UI パスをサポートします:
  • Stripe がホストするチェックアウトページ
  • 埋め込みチェックアウトフォーム
  • ui_mode='custom' を使用した Elements (Payment Element、Express Checkout Element) によるカスタム 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'