Stripe統合

Stripeは現在、最も安定性があり人気の高いグローバル決済処理プラットフォームで、世界的なビジネスの決済プロセスを簡素化し、SaaS製品が様々な決済方法を容易に受け付けることを可能にします。

本章では、プロジェクトにStripeを統合する方法を紹介します。

登録と基本設定

Stripeにアクセスしてアカウントを登録します
ダッシュボードページに移動し、左上からアカウントの作成を開始し、ページのガイダンスに従って必要な手順を完了します。

APIキーの取得とWebhookの作成

登録後、開発中はすべてのプロセスがデバッグされるまでSandboxモードに入り、その後製品情報をLiveモードにコピーする必要があります。

Developer - API Keysページに移動し、Secret keyとPublishable keyをそれぞれ環境変数STRIPE_SECRET_KEYとSTRIPE_PUBLISHABLE_KEYにコピーします。

Developer - Webhooksページに移動し、「Create an event destination」ボタンをクリックしてWebhookエンドポイントを作成します。

これによりフォームページが開き、Webhookエンドポイントを入力する必要があります。ローカル開発の場合、この段階でトンネルアドレスを作成する必要があります。

トンネルアドレスの作成（本番環境ではこの手順をスキップします）。

CursorまたはVSCodeを開き、Forward Portを設定し、ローカルサーバーポートを入力してからPublicに設定し、Forwarded Addressをコピーします。

注目すべき点：

長期間使用しない場合、Forward Portが開いているように見えても実際には無効になっていることがあります。再度開くだけで解決し、Forwarded Addressは変更されません。

CursorでForward Portの設定に失敗する場合は、コミュニティ提供のソリューションに従ってください：WindowsソリューションまたはMacソリューション、または慣れ親しんだトンネリングツールに切り替えてください。

Forwarded AddressをWebhook Endpoint URLにコピーし、Select eventsをクリックして必要なイベントを選択します。

ローカル環境の場合：Webhook Endpoint URLはForwarded Address + APIパス（つまり、<your_forwarded_address>/api/stripe/webhook）
本番環境の場合：Webhook Endpoint URLは本番環境アドレス + APIパス（つまり、<your_server_address>/api/stripe/webhook）

以下の7つのイベントを選択します：

charge.refunded
checkout.session.completed
customer.subscription.created
customer.subscription.updated
customer.subscription.deleted
invoice.paid
invoice.payment_failed

これらのイベントは堅牢な一回払いとサブスクリプション決済フローを完成させるのに十分で、これらすべてのイベントはNexty.devボイラープレートに対応する処理ロジックがあります。

Webhookが作成されたら、Secretを取得して環境変数STRIPE_WEBHOOK_SECRETにコピーします。

製品の作成

Product Catalogページに移動して製品を作成します。

参考として、Nexty.dev製品の入力内容を以下に示します。

作成後、製品をクリックして詳細ページに入ります。

Product IDとPrice IDを確認できます。後続の手順では、管理画面の料金プランでPrice IDを使用します。

同じ手順に従って追加のサブスクリプション製品を作成できます。

製品と料金の関係

Stripeでは、1つのProductに複数のPriceを含めることができますが、サブスクリプションシナリオでは、ユーザーのサブスクリプションプランアップグレードの潜在的なニーズに対応するため、製品構造の設計を慎重に検討する必要があります。

Stripeのサブスクリプションアップグレードは異なる製品間の切り替えに基づいており、同じ製品内の異なる価格間の切り替えではありません。つまり：

サポート対象：Product A → Product Bのアップグレード
制限事項：同じ製品内の異なる価格間での直接アップグレードは不可能

そのため、すべての料金プランを1つの製品の下に配置するのではなく、機能レベルで製品を整理することをお勧めします。例：

Product1: ベーシックプラン
├── Price: $10/month (USD)
└── Price: $100/year (USD)
 
Product2: プレミアムプラン  
├── Price: $20/month (USD)
└── Price: $200/year (USD)
 
Product3: エンタープライズプラン
├── Price: $50/month (USD)
└── Price: $500/year (USD)

Radarの有効化

StripeにはRadar機能があり、カスタムルールを設定して高リスクの決済を識別・ブロックし、アカウントのセキュリティを保護できます。

ただし、これは有料機能ですが、Sandboxでは無料で使用できます。

LiveモードでRadar機能を購入している場合は、以下のルールを追加できます：

1週間以内に作成された新規ユーザーが5枚以上のカードを使用
:card_count_for_customer_weekly: > 5 and :hours_since_customer_was_created: <= 168
 
同じ顧客が1週間以内に4枚以上のクレジットカードを使用
:card_count_for_customer_weekly: > 4 and :card_funding: = 'credit'
 
週間高リスクカード試行回数が3回を超える
:card_count_for_customer_weekly: > 3 and :risk_score: > 50
 
同じIPアドレスからの日次高リスク試行
:total_charges_per_ip_address_daily: > 10 and :risk_score: > 40

ユーザーの同時サブスクリプション制限

製品にサブスクリプションがあり、ユーザーが同時に持てるサブスクリプションを1つに制限したい場合は、Paymentsモジュールで設定できます。

この設定により、ユーザーの重複サブスクリプションも防止でき、これは争議注文を作成する可能性があります。争議の申し立てが成功しても、15ドルの処理手数料がかかります。

決済方法の管理

Settings - Payment Methodsページで、ユーザーの決済方法を管理できます。AlipayとWeChat Payの申請をお勧めします。これにより、特に中国のユーザーを含む、より多くのユーザーが製品を使用できるようになります。

AlipayとWeChat Payの申請時、Stripeはメールで追加資料を求める場合があります。メールの指示に従って提供してください。これらの資料はAlipayとWeChat Payによって要求されるもので、StripeはAlipayとWeChat Payの承認後に正式に有効化されます。

ただし、ここで有効化される権限は一回払いのみをサポートし、サブスクリプション製品は対象外です。サブスクリプション製品でもAlipayとWeChat Payをサポートしたい場合は、Stripeカスタマーサービスに個別に申請する必要があります。