決済システム概要

NEXTY.DEV決済システムは、複数の決済プロバイダーをサポートする完全機能のSaaS決済ソリューションです。StripeとCreemの両方の決済プロバイダーをサポートし、料金プラン管理、決済処理、サブスクリプション管理からクレジットシステムまで、完全な機能を提供します。

コア機能

1. 複数の決済プロバイダーサポート

Stripe: 世界的に人気のある決済サービスプロバイダー
Creem: 新興の決済サービスプロバイダー
統一インターフェース: 異なるプロバイダーからの決済ロジックを統一されたコードインターフェースで処理

2. 柔軟な料金プラン

一回限りの決済
サブスクリプション決済
- 月額サブスクリプション
- 年額サブスクリプション

3. 完全な決済フロー

決済セッションの作成
決済の検証
Webhook処理
注文管理
サブスクリプション同期

4. クレジットシステム

一回限りのクレジット
サブスクリプションクレジット
クレジット使用記録
クレジット残高管理

システムアーキテクチャ

データベーステーブル構造

1. `pricing_plans` - 料金プランテーブル

すべての料金プランの情報を保存します：

基本情報: id、cardTitle、cardDescription
決済プロバイダー設定: provider、stripePriceId、creemProductId
決済タイプ: paymentType
- one_time (Stripe)
- onetime (Creem)
- recurring (StripeとCreem)
サブスクリプション間隔: recurringInterval
- month (Stripe)
- year (Stripe)
- every-month (Creem)
- every-year (Creem)
- once (Creem)
価格情報: price、currency、displayPrice、originalPrice
クーポン: stripeCouponId、creemDiscountCode
多言語サポート: langJsonb（JSONB形式で多言語コンテンツを保存）
特典設定: benefitsJsonb（JSONB形式で特典情報を保存、クレジット額など）
表示設定: isActive、isHighlighted、displayOrder

2. `orders` - 注文テーブル

すべての決済注文記録を保存します：

ユーザー関連: userId
決済プロバイダー: provider (stripe/creem)
注文タイプ: orderType
- one_time_purchase (Stripe)
- onetime_purchase (Creem)
- subscription_initial (Stripe)
- subscription_renewal (Stripe)
- recurring (StripeとCreem)
- refund (StripeとCreem)
注文ステータス: status (succeeded/pending/failed/refunded/partially_refunded)
金額情報: amountSubtotal、amountDiscount、amountTax、amountTotal、currency
関連情報: planId、subscriptionId、productId、priceId
プロバイダー固有フィールド: stripePaymentIntentId、stripeInvoiceId、stripeChargeId
メタデータ: metadata（JSONB形式でプロバイダー固有のメタデータを保存）

3. `subscriptions` - サブスクリプションテーブル

ユーザーのサブスクリプション情報を保存します：

ユーザー関連: userId、planId
決済プロバイダー: provider
サブスクリプション識別子: subscriptionId、customerId
サブスクリプションステータス: status (active/trialing/past_due/canceled/incompleteなど)
期間情報: currentPeriodStart、currentPeriodEnd
キャンセル情報: cancelAtPeriodEnd、canceledAt、endedAt
トライアル情報: trialStart、trialEnd
メタデータ: metadata（JSONB形式）

4. `usage` - 使用量/クレジットテーブル

ユーザーのクレジット残高と使用量を保存します：

ユーザー関連: userId（一意）
クレジット残高: subscriptionCreditsBalance、oneTimeCreditsBalance
残高詳細: balanceJsonb（JSONB形式で月次/年次配分詳細を保存）

5. `credit_logs` - クレジットログテーブル

すべてのクレジット変更を記録します：

ユーザー関連: userId
変更額: amount（増加は正、減少は負）
変更後の残高: oneTimeBalanceAfter、subscriptionBalanceAfter
変更タイプ: type (one_time_purchase/subscription_grant/feature_usage/refund_revokeなど)
関連注文: relatedOrderId
備考: notes

コアモジュール

1. Actionsレイヤー (`actions/`)

ビジネスロジックを処理するサーバーサイドアクション関数：

actions/prices/: 料金プラン管理（管理者と公開インターフェース）
actions/stripe/: Stripe決済関連操作
actions/creem/: Creem決済関連操作
actions/orders/: 注文クエリ（ユーザーと管理者）
actions/usage/: クレジット管理とクエリ

2. APIルート (`app/api/`)

HTTPリクエストとWebhookを処理します：

app/api/payment/: 決済関連API
- checkout-session: チェックアウトセッションを作成
- verify-success: 決済成功を検証
app/api/stripe/webhook/: Stripe Webhook処理
app/api/creem/webhook/: Creem Webhook処理

3. ライブラリファイル (`lib/`)

再利用可能なユーティリティ関数とクライアント：

lib/payments/: 決済関連ユーティリティ関数
- provider-utils.ts: 決済プロバイダーユーティリティ関数
- credit-manager.ts: クレジット管理
- webhook-helpers.ts: Webhookヘルパー関数
- types.ts: 型定義
lib/stripe/: Stripeクライアント
lib/creem/: Creemクライアント

4. UIコンポーネント (`components/`)

フロントエンド表示コンポーネント：

components/home/Pricing.tsx: 料金ページ（カテゴリ別表示）
components/home/PricingAll.tsx: 料金ページ（すべてのプランを表示）
components/home/PricingCardDisplay.tsx: 料金カード表示コンポーネント
components/home/PricingCTA.tsx: 料金カードCTAボタン

5. 管理者インターフェース (`app/[locale]/(protected)/dashboard/`)

(admin)/prices/: 管理者料金プラン管理
(admin)/orders/: 管理者注文管理
(user)/my-orders/: ユーザー注文一覧
(user)/credit-history/: ユーザークレジット履歴
(user)/subscription/: ユーザーサブスクリプション管理

決済フロー概要

1. ユーザーがプランを選択

ユーザーが料金ページでプランを選択し、購入ボタンをクリックします。

2. チェックアウトセッションの作成

フロントエンドが/api/payment/checkout-session APIを呼び出し、バックエンドが決済プロバイダーに応じて適切なチェックアウトセッションを作成します。

3. 決済ページへのリダイレクト

ユーザーが決済プロバイダーの決済ページにリダイレクトされ、決済を完了します。

4. 決済成功コールバック

決済成功後、ユーザーはアプリケーションの/payment/successページにリダイレクトされ、システムが決済ステータスを検証します。

5. Webhook処理

決済プロバイダーがWebhookイベント（/api/stripe/webhookまたは/api/creem/webhook）を送信し、システムが注文作成、クレジット付与、その他の操作を処理します。

6. サブスクリプション同期

サブスクリプション決済の場合、システムは定期的にサブスクリプションステータスを同期し、更新、キャンセル、その他のイベントを処理します。

決済タイプの説明

一回限りの決済

Stripe: paymentType = 'one_time'
Creem: paymentType = 'onetime'
ユーザーが一回限りの購入を行い、一回限りのクレジットを受け取ります

サブスクリプション決済

Stripe: paymentType = 'recurring'、recurringInterval = 'month'/'year'
Creem: paymentType = 'recurring'、recurringInterval = 'every-month'/'every-year'
ユーザーが月額または年額でサブスクライブし、定期的にクレジットを受け取ります

環境変数の設定

Stripe設定

STRIPE_SECRET_KEY=sk_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_CUSTOMER_PORTAL_URL=/dashboard/subscription

Creem設定

CREEM_API_KEY=your_api_key
CREEM_WEBHOOK_SECRET=your_webhook_secret
CREEM_API_BASE_URL=https://api.creem.io/v1  # オプション、デフォルト値

その他の設定

NEXT_PUBLIC_PRICING_PATH=/pricing
NEXT_PUBLIC_SITE_URL=https://yourdomain.com
[email protected]