tinyship-payment

TinyShip の決済連携

TinyShip で決済プロバイダーを設定するためのガイドです。

プロバイダーの選択

ユーザーに対象市場を尋ね、プロバイダーをおすすめしてください。

市場	おすすめ	サブスクリプション対応
中国	WeChat Pay、Alipay	1 回払い＋クレジットのみ
グローバル	Stripe	全対応（1 回払い、継続課金、クレジット）
グローバル（簡単に登録可能）	Creem	全対応（1 回払い、継続課金、クレジット）
グローバル（代替）	PayPal	全対応（1 回払い、継続課金、クレジット）
グローバル（MoR／税務対応不要）	Dodo Payments	全対応（Merchant of Record）
グローバル（MoR／税務対応不要）	Waffo Pancake	全対応（Merchant of Record。サブスクリプションでは CNY 非対応）

プロバイダー別の設定

詳しい手順については、該当するリファレンスファイルをお読みください。

• references/stripe-setup.md — Stripe（グローバル向けのおすすめ）
• references/wechat-pay-setup.md — WeChat Pay
• references/alipay-setup.md — Alipay
• references/paypal-setup.md — PayPal

Creem、Dodo Payments、Waffo Pancake については、TinyShip リポジトリの docs/user-guide/payment/creem.md、docs/user-guide/payment/dodo.md、docs/user-guide/payment/waffo.md をお読みください。

Waffo についての注意点：API キーは作成時に Test または Production に紐付けられます（TEST_MODE の切り替えはありません）。Webhook の検証には RSA 公開鍵を使用します（SDK には Test／Prod の鍵が組み込まれています）。また、各プランには waffoProductId（PROD_xxx）が必要です。

料金プランの設定

プロバイダーの設定後、2 つの方法でプランを設定できます。

オプション A：静的プラン（デフォルト）

config/payment.ts でプランを直接定義します。

plans: {
  monthly: {
    provider: 'stripe',           // must match your configured provider
    id: 'monthly',
    amount: 10,
    currency: 'USD',
    duration: { months: 1, type: 'recurring' },
    stripePriceId: 'price_xxx',   // provider-specific ID (required for Stripe)
    i18n: {
      'en': {
        name: 'Monthly Plan',
        description: 'Full access for one month',
        duration: 'month',
        features: ['All features', 'Priority support']
      },
      'zh-CN': {
        name: '月度订阅',
        description: '一个月完整访问',
        duration: '月',
        features: ['所有功能', '优先支持']
      }
    }
  }
}

プランは /pricing ページに自動的に表示されます。

オプション B：動的料金設定（管理者による管理）

.env に PRICING_MODE="dynamic" を設定して有効にします。プランはデータベースに保存され、/admin/pricing の管理パネルから管理できます。コードの変更や再デプロイをせずに、いつでも価格を調整できます。

新規プロジェクトでは、スキーマに pricing_plan テーブルがすでに含まれているため、通常のデータベース初期化で対応できます。古いバージョンからアップグレードしたプロジェクトでは、先にテーブルを追加する必要があります。

pnpm db:push          # PostgreSQL
pnpm db:push:sqlite   # SQLite / D1

動的料金設定では、次の機能が追加されます。

• 管理 UI からのプランの作成、編集、並べ替え
• Markdown 形式の機能一覧
• 取り消し線付きの価格（元の価格）
• ロケールに基づくプランの表示制御
• 既存の静的プランをデータベースにワンクリックでインポート

既存の静的プランを移行するには、動的モードを有効にし、/admin/pricing を開いて「Import from Config」をクリックします。各プランのプロバイダー ID を確認したら、テスト決済を実行してください。PRICING_MODE="static" に設定して再起動すれば、いつでも静的モードに戻せます。動的プランのデータは保持されます。

詳しくは、TinyShip リポジトリの docs/user-guide/payment/dynamic-pricing.md をご覧ください。

プランの種類

種類	duration.type	プロバイダー
1 回払い	one_time	すべて
サブスクリプション	recurring	Stripe、Creem、PayPal、Dodo、Waffo
クレジットパック	credits	すべて（duration.credits: 100 を設定）

Webhook の設定（ローカル開発）

決済プロバイダーからアプリに Webhook を送信する必要があります。ローカル開発の場合は、次の手順に従ってください。

1. トンネルツールをインストールします。

# Option A: ngrok
ngrok http 7001

# Option B: Cloudflare Tunnel
cloudflared tunnel --url http://localhost:7001

2. トンネル URL を Webhook エンドポイントとして使用します。
3. プロバイダーのダッシュボードで Webhook URL を設定します。

Webhook エンドポイントは {BASE_URL}/api/payment/webhook/{provider} です （例：/api/payment/webhook/stripe）。

クレジットシステム（任意）

AI クレジットの消費を有効にするには、config/credits.ts を設定します。

credits: {
  consumptionMode: 'dynamic',          // 'fixed' or 'dynamic'
  fixedChatCost: 10,                   // credits per chat (fixed mode)
  dynamicChatCostPerKiloToken: 1,      // credits per 1K tokens (dynamic mode)
  modelMultipliers: {
    'qwen3.7-flash': 1.0,
    'gpt-5.6-sol': 2.0,
    'default': 1.0
  }
}

サブスクリプションプランに加えて、クレジット購入プランを追加します。

credits100: {
  provider: 'stripe',
  id: 'credits100',
  amount: 10,
  currency: 'USD',
  duration: { type: 'credits', credits: 100 },
  stripePriceId: 'price_xxx',
  i18n: { /* ... */ }
}

確認

1. 開発サーバーを起動します。
2. /pricing にアクセスし、プランが表示されることを確認します。
3. プランをクリックし、テスト決済を完了します（サンドボックス／テストモードを使用してください）。
4. /dashboard を確認し、注文が表示されることを確認します。
5. サブスクリプションの場合は、/api/subscription/status が有効なステータスを返すことを確認します。

TinyShip リポジトリの参考ファイル

• config/payment.ts — 決済プロバイダーとプランの設定
• config/credits.ts — クレジットシステムの設定
• libs/payment/AGENTS.md — 決済ライブラリのアーキテクチャ
• libs/credits/AGENTS.md — クレジットシステムのアーキテクチャ
• docs/user-guide/payment/overview.md — 決済ドキュメントのインデックス
• docs/user-guide/payment/waffo.md — Waffo Pancake のセットアップ（MoR、ホステッドチェックアウト）
• docs/user-guide/payment/dynamic-pricing.md — 動的価格設定の管理者向けガイド
• docs/user-guide/payment-testing.md — テストと Webhook のデバッグガイド