Menu

決済システム ドキュメント索引

NEXTY.DEV の決済システムは Stripe・Creem・PayPal の 3 チャネルに同時対応し、サブスクリプション、買い切り購入、クレジット台帳、チーム共有プール、返金、照合をカバーします。

本章は「全体から部分へ」の順に構成されています。まず全体像をつかみ、次に各モジュールへ踏み込んでください。

章の構成

  1. 決済システム概要

    • 全体像を 1 本の流れで
    • 5 つの設計原則
    • データベーステーブルとコードマップ
    • 個人とチーム、2 つの課金主体
    • 3 プロバイダーの機能差

  2. 料金設定

    • なぜ料金をコードに置くのか
    • サブスクリプション / クレジットパック / チームプランの書き方
    • フィールドリファレンスとプロバイダー側の参照
    • 多言語コピー、プロモーションコード、プラン廃止の鉄則

  3. 決済フロー

    • クリックからクレジット付与までの全経路
    • チェックアウトのガードの順序とその理由
    • 成功ページと Webhook による二重の保険
    • ガードコード早見表

  4. Webhook 処理

    • 3 層構造と署名検証
    • 3 プロバイダーのイベント対応表
    • 冪等性、ステータスの正規化、エラー処理
    • 重複サブスクリプションの決着と失われた Webhook の補償

  5. クレジットシステム

    • 2 バケットモデルと追記専用台帳
    • 年額サブスクリプションの月次ドリップ
    • 機能をクレジットに接続する
    • チーム共有プール、登録ボーナス、管理者の操作

  6. 注文とサブスクリプション管理

    • 注文のデータ構造と照会
    • 返金：なぜ API を呼ぶだけでローカル状態を書かないのか
    • セルフサービスポータルとクーポンコンソール
    • ユーザー側と管理側のページ一覧

  7. クーポンコンソール

    • Stripe Coupon + Promotion Code のデータモデル
    • コードは変更不可であること、そこから導かれる UI
    • 作成フォームと適用範囲の変換経路
    • 自動適用と一覧のスキャン上限

  8. サブスクリプション変更

    • Stripe の変更入口の設定
    • 期間途中の変更におけるクレジット差分のアルゴリズム
    • 不正防止の設計と周期をまたぐ再アンカー

はじめに

初めての導入

  1. 決済システム概要を読み、全体像を把握します
  2. Stripe 連携（または PayPal 連携）に従い、プロバイダー側で製品を作成します
  3. 料金設定に従って config/pricing.ts を編集するか、pnpm stripe:bootstrap --write を実行します
  4. Webhook のアドレスと CRON_SECRET を設定します（定期実行タスクを参照）
  5. テストカードで 1 件通し、決済フロー末尾のチェックリストで検証します

目的から探す

やりたいこと参照先
価格の変更、プランの追加、プロモーション料金設定
ある機能でクレジットを消費させるクレジットシステム
支払いが反映されない原因を調べるWebhook 処理
ユーザーに返金する注文とサブスクリプション管理
クーポンやプロモーションコードを運用するクーポンコンソール
プランのアップ/ダウングレードに対応するサブスクリプション変更
全体アーキテクチャを理解する決済システム概要

環境変数

完全な一覧は環境変数にあります。決済関連は次の通りです。

Stripe

STRIPE_SECRET_KEY=sk_...
STRIPE_PUBLISHABLE_KEY=pk_...
STRIPE_WEBHOOK_SECRET=whsec_...
# 任意：refund,email | refund | email | 空
STRIPE_RADAR_EARLY_FRAUD_WARNING_TYPE=refund,email

Creem

CREEM_API_KEY=your_api_key
CREEM_WEBHOOK_SECRET=your_webhook_secret
CREEM_API_BASE_URL=https://api.creem.io/v1  # 任意

PayPal

NEXT_PUBLIC_ENABLE_PAYPAL=true
NEXT_PUBLIC_PAYPAL_CLIENT_ID=your_client_id
NEXT_PUBLIC_PAYPAL_ENVIRONMENT=sandbox  # sandbox | live
PAYPAL_CLIENT_SECRET=your_client_secret
PAYPAL_WEBHOOK_ID=your_webhook_id

定期実行タスク

# /api/cron/credits の認証シークレット。サブスクリプションまたはクレジット機能を有効にする場合は必須
CRON_SECRET=your_cron_secret

その他

NEXT_PUBLIC_DEFAULT_CURRENCY=USD
NEXT_PUBLIC_SITE_URL=https://yourdomain.com
[email protected]

よくある質問

Q: どの決済プロバイダーに対応していますか？

Stripe、Creem、PayPal の 3 つです。どのプロバイダーを使うかは config/pricing.ts の各プランの provider フィールドで決まり、3 つすべてを同時に有効化できます。

Q: 価格はどう変更しますか？管理画面はどこですか？

v4.0.0 以降、管理画面の料金ページはありません。料金は config/pricing.ts にあり、編集してデプロイするだけです。料金設定を参照してください。

Q: 定期実行タスクは必須ですか？

サブスクリプションを販売する、またはクレジットを使う場合は必須です。年額プランの月次ドリップ、失われた Webhook の照合、PayPal 保留中キャプチャの前進がすべてこれに依存します。定期実行タスクを参照してください。

Q: クレジットシステムはどう動きますか？

2 つのバケットがあります。サブスクリプションクレジット（付与のたびにリセット、サブスクリプション終了時にクリア）と購入クレジット（無期限）で、消費はサブスクリプションバケットから先に引かれます。すべての変更は台帳を通り、追記のみで変更はしません。クレジットシステムを参照してください。

Q: ユーザーは自分でサブスクリプションを管理できますか？

できます。/dashboard/billing の「サブスクリプションを管理」ボタンが、そのサブスクリプションのプロバイダーに応じたセルフサービスポータルへ遷移させます。PayPal にはホスト型ポータルがないため、PayPal の自動支払いページへ遷移します。

Q: どうテストしますか？

3 プロバイダーともテスト/サンドボックスモードを使い、Webhook をローカルへ転送します。詳細は決済フローのテストの節を参照してください。

決済システム

NEXTY.DEV 決済システムの全体アーキテクチャと中核となる概念の紹介

料金設定

config/pricing.ts でのプラン定義、3 つの決済プロバイダーへの接続、3 言語コピーの記述、プロモーションの設定方法

決済フロー

購入クリックからクレジット付与までの全経路。チェックアウトのガード、プロバイダーへの振り分け、二重のフルフィルメント、ガードコードの扱い

Webhook 処理メカニズム

Stripe・Creem・PayPal 3 プロバイダーの署名検証、イベントの対応表、フルフィルメントコア、エラー処理

クレジットシステム

2 バケットモデル、追記専用台帳、年額ドリップ、消費と払い戻し、機能をクレジットに接続する方法

注文とサブスクリプション管理

注文の照会、返金、サブスクリプションのセルフサービスポータル、クーポンコンソール、ユーザー側と管理側の各ページ

クーポン

Stripe Coupon + Promotion Code によるクーポン管理 —— データモデル、変更不可の制約、作成フォーム、自動適用、一覧のスキャン上限

サブスクリプション変更

Stripe のプラン変更入口の設定と、内蔵の期間途中プラン変更がクレジット差分をどう計算し、クレジット稼ぎをどう防ぎ、年額ドリップをどう再アンカーするか