Stripe Integration

Stripe の決済処理統合をマスターし、チェックアウト、サブスクリプション、ウェブフック、返金を含む堅牢で PCI コンプライアント決済フローを実装します。

このスキルを使用しないケース

• タスクが Stripe 統合と無関係の場合
• このスコープ外の異なるドメインやツールが必要な場合

手順

• 目標、制約、必要なインプットを明確にする
• 関連するベストプラクティスを適用し、結果を検証する
• 実行可能なステップと検証方法を提供する
• 詳細な例が必要な場合は、resources/implementation-playbook.md を開く

このスキルを使用するケース

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

コアコンセプト

1. 決済フロー

Checkout Session (ホスト型)

• Stripe がホストする決済ページ
• PCI コンプライアンス負担が最小限
• 最速の実装
• ワンタイム決済と定期決済をサポート

Payment Intents (カスタム UI)

• 決済 UI に完全なコントロール
• PCI コンプライアンスには Stripe.js が必要
• より複雑な実装
• より優れたカスタマイズオプション

Setup Intents (決済方法を保存)

• 課金なしで決済方法を収集
• サブスクリプションと将来の決済に使用
• 顧客の確認が必要

2. ウェブフック

重要なイベント:

• 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  # フロントエンドに送信

# フロントエンド (JavaScript)
"""
const stripe = Stripe('pk_test_...');
const elements = stripe.elements();
const cardElement = elements.create('card');
cardElement.mount('#card-element');

const {error, paymentIntent} = await stripe.confirmCardPayment(
    clientSecret,
    {
        payment_method: {
            card: cardElement,
            billing_details: {
                name: 'Customer Name'
            }
        }
    }
);

if (error) {
    // エラーを処理
} else if (paymentIntent.status === 'succeeded') {
    // 決済成功
}
"""

パターン 3: サブスクリプション作成

def create_subscription(customer_id, price_id):
    """顧客のサブスクリプションを作成します。"""
    try:
        subscription = stripe.Subscription.create(
            customer=customer_id,
            items=[{'price': price_id}],
            payment_behavior='default_incomplete',
            payment_settings={'save_default_payment_method': 'on_subscription'},
            expand=['latest_invoice.payment_intent'],
        )

        return {
            'subscription_id': subscription.id,
            'client_secret': subscription.latest_invoice.payment_intent.client_secret
        }
    except stripe.error.StripeError as e:
        print(f"Subscription creation failed: {e}")
        raise

パターン 4: カスタマーポータル

def create_customer_portal_session(customer_id):
    """顧客がサブスクリプションを管理するためのポータルセッションを作成します。"""
    session = stripe.billing_portal.Session.create(
        customer=customer_id,
        return_url='https://yourdomain.com/account',
    )
    return session.url  # ここに顧客をリダイレクト

ウェブフック処理

セキュアなウェブフックエンドポイント

from flask import Flask, request
import stripe

app = Flask(__name__)

endpoint_secret = 'whsec_...'

@app.route('/webhook', methods=['POST'])
def webhook():
    payload = request.data
    sig_header = request.headers.get('Stripe-Signature')

    try:
        event = stripe.Webhook.construct_event(
            payload, sig_header, endpoint_secret
        )
    except ValueError:
        # 無効なペイロード
        return 'Invalid payload', 400
    except stripe.error.SignatureVerificationError:
        # 無効な署名
        return 'Invalid signature', 400

    # イベントを処理
    if event['type'] == 'payment_intent.succeeded':
        payment_intent = event['data']['object']
        handle_successful_payment(payment_intent)
    elif event['type'] == 'payment_intent.payment_failed':
        payment_intent = event['data']['object']
        handle_failed_payment(payment_intent)
    elif event['type'] == 'customer.subscription.deleted':
        subscription = event['data']['object']
        handle_subscription_canceled(subscription)

    return 'Success', 200

def handle_successful_payment(payment_intent):
    """成功した決済を処理します。"""
    customer_id = payment_intent.get('customer')
    amount = payment_intent['amount']
    metadata = payment_intent.get('metadata', {})

    # データベースを更新
    # 確認メールを送信
    # 注文を処理
    print(f"Payment succeeded: {payment_intent['id']}")

def handle_failed_payment(payment_intent):
    """失敗した決済を処理します。"""
    error = payment_intent.get('last_payment_error', {})
    print(f"Payment failed: {error.get('message')}")
    # 顧客に通知
    # 注文ステータスを更新

def handle_subscription_canceled(subscription):
    """サブスクリプションキャンセルを処理します。"""
    customer_id = subscription['customer']
    # ユーザーアクセスを更新
    # キャンセルメールを送信
    print(f"Subscription canceled: {subscription['id']}")

ウェブフックベストプラクティス

import hashlib
import hmac

def verify_webhook_signature(payload, signature, secret):
    """ウェブフック署名を手動で検証します。"""
    expected_sig = hmac.new(
        secret.encode('utf-8'),
        payload,
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(signature, expected_sig)

def handle_webhook_idempotently(event_id, handler):
    """ウェブフックが正確に 1 回処理されるようにします。"""
    # イベントが既に処理されているかチェック
    if is_event_processed(event_id):
        return

    # イベントを処理
    try:
        handler()
        mark_event_processed(event_id)
    except Exception as e:
        log_error(e)
        # Stripe は失敗したウェブフックを再試行します
        raise

顧客管理

def create_customer(email, name, payment_method_id=None):
    """Stripe 顧客を作成します。"""
    customer = stripe.Customer.create(
        email=email,
        name=name,
        payment_method=payment_method_id,
        invoice_settings={
            'default_payment_method': payment_method_id
        } if payment_method_id else None,
        metadata={
            'user_id': '12345'
        }
    )
    return customer

def attach_payment_method(customer_id, payment_method_id):
    """決済方法を顧客にアタッチします。"""
    stripe.PaymentMethod.attach(
        payment_method_id,
        customer=customer_id
    )

    # デフォルトに設定
    stripe.Customer.modify(
        customer_id,
        invoice_settings={
            'default_payment_method': payment_method_id
        }
    )

def list_customer_payment_methods(customer_id):
    """顧客のすべての決済方法をリストします。"""
    payment_methods = stripe.PaymentMethod.list(
        customer=customer_id,
        type='card'
    )
    return payment_methods.data

返金処理

def create_refund(payment_intent_id, amount=None, reason=None):
    """返金を作成します。"""
    refund_params = {
        'payment_intent': payment_intent_id
    }

    if amount:
        refund_params['amount'] = amount  # 部分返金

    if reason:
        refund_params['reason'] = reason  # 'duplicate', 'fraudulent', 'requested_by_customer'

    refund = stripe.Refund.create(**refund_params)
    return refund

def handle_dispute(charge_id, evidence):
    """異議申し立てを証拠で更新します。"""
    stripe.Dispute.modify(
        charge_id,
        evidence={
            'customer_name': evidence.get('customer_name'),
            'customer_email_address': evidence.get('customer_email'),
            'shipping_documentation': evidence.get('shipping_proof'),
            'customer_communication': evidence.get('communication'),
        }
    )

テスト

# テストモードキーを使用
stripe.api_key = "sk_test_..."

# テストカード番号
TEST_CARDS = {
    'success': '4242424242424242',
    'declined': '4000000000000002',
    '3d_secure': '4000002500003155',
    'insufficient_funds': '4000000000009995'
}

def test_payment_flow():
    """完全な決済フローをテストします。"""
    # テスト顧客を作成
    customer = stripe.Customer.create(
        email="test@example.com"
    )

    # payment intent を作成
    intent = stripe.PaymentIntent.create(
        amount=1000,
        currency='usd',
        customer=customer.id,
        payment_method_types=['card']
    )

    # テストカードで確認
    confirmed = stripe.PaymentIntent.confirm(
        intent.id,
        payment_method='pm_card_visa'  # テスト決済方法
    )

    assert confirmed.status == 'succeeded'

リソース

• references/checkout-flows.md: 詳細なチェックアウト実装
• references/webhook-handling.md: ウェブフックセキュリティと処理
• references/subscription-management.md: サブスクリプションライフサイクル
• references/customer-management.md: 顧客と決済方法の処理
• references/invoice-generation.md: 請求書生成と課金
• assets/stripe-client.py: 本番環境対応 Stripe クライアントラッパー
• assets/webhook-handler.py: 完全なウェブフックプロセッサ
• assets/checkout-config.json: チェックアウト設定テンプレート

ベストプラクティス

1. 常にウェブフックを使用: クライアント側の確認のみに依存しない
2. べき等性: ウェブフックイベントをべき等に処理する
3. エラーハンドリング: すべての Stripe エラーを適切に処理する
4. テストモード: 本番環境に移行する前にテストキーで十分にテストする
5. メタデータ: メタデータを使用して Stripe オブジェクトをデータベースにリンク
6. 監視: 決済成功率とエラーを追跡する
7. PCI コンプライアンス: サーバー上で生のカードデータを処理しない
8. SCA 対応: ヨーロッパの決済に 3D Secure を実装する

よくある落とし穴

• ウェブフック検証なし: 常にウェブフック署名を検証する
• ウェブフックイベントの欠落: すべての関連ウェブフックイベントを処理する
• ハードコードされた金額: セント/最小通貨単位を使用する
• 再試行ロジックなし: API 呼び出しに再試行を実装する
• テストモードを無視: テストカードですべてのエッジケースをテストする

制限事項

• このスキルは、上記で説明されているスコープに明確に一致するタスクでのみ使用してください。
• 出力を環境固有の検証、テスト、または専門家のレビューの代替として扱わないでください。
• 必要なインプット、権限、安全境界、または成功基準が不明な場合は、停止して明確化を求めてください。