payment-integration

決済連携

SePay（ベトナムの決済）と Polar（グローバルな SaaS の収益化）を使用した決済処理を実装します。

使用するタイミング

以下を実装する場合に使用します。

• 決済ゲートウェイ連携（チェックアウト、決済処理）
• サブスクリプション管理（トライアル、アップグレード、請求）
• Webhook 処理（決済通知）
• QR コード決済（VietQR、NAPAS）
• 従量課金（使用量計測、クレジット）
• 特典の自動提供（ライセンス、GitHub アクセス、Discord ロール）
• カスタマーポータル（セルフサービス管理）
• 銀行振込の自動化（ベトナムの銀行）
• 価格を設定した製品カタログ

プラットフォームの選択

以下の場合は SePay を選択します。

• ベトナム市場（通貨は VND）
• 銀行振込の自動化
• VietQR／NAPAS 決済
• 現地の決済方法
• 銀行口座の直接監視

以下の場合は Polar を選択します。

• グローバルな SaaS 製品
• サブスクリプション管理
• 従量課金
• 特典の自動提供（GitHub、Discord、ライセンス）
• Merchant of Record（税務コンプライアンス）
• デジタル製品の販売

クイックリファレンス

SePay 連携

• 概要と認証：references/sepay/overview.md - プラットフォームの機能、API／OAuth2 認証、対応銀行
• API リファレンス：references/sepay/api.md - エンドポイント、取引、銀行口座、仮想口座
• Webhook：references/sepay/webhooks.md - 設定、ペイロード構造、検証、再試行ロジック
• SDK の使用方法：references/sepay/sdk.md - Node.js、PHP、Laravel の実装
• QR コード：references/sepay/qr-codes.md - VietQR の生成、テンプレート、連携
• ベストプラクティス：references/sepay/best-practices.md - セキュリティ、パターン、監視

Polar 連携

• 概要と認証：references/polar/overview.md - プラットフォームの機能、認証方法、MoR の概念
• 製品と価格設定：references/polar/products.md - 製品タイプ、価格モデル、従量課金
• チェックアウト：references/polar/checkouts.md - チェックアウトフロー、埋め込み型チェックアウト、リンク
• サブスクリプション：references/polar/subscriptions.md - ライフサイクル、アップグレード、ダウングレード、トライアル
• Webhook：references/polar/webhooks.md - イベントタイプ、署名の検証、監視
• 特典：references/polar/benefits.md - 自動提供（GitHub、Discord、ライセンス、ファイル）
• SDK の使用方法：references/polar/sdk.md - TypeScript、Python、PHP、Go、フレームワークアダプター
• ベストプラクティス：references/polar/best-practices.md - セキュリティ、パターン、監視

連携スクリプト

• SePay Webhook の検証：scripts/sepay-webhook-verify.js - SePay Webhook の真正性を検証します
• Polar Webhook の検証：scripts/polar-webhook-verify.js - Polar Webhook の署名を検証します
• チェックアウトヘルパー：scripts/checkout-helper.js - 両プラットフォームのチェックアウトセッションを生成します

実装ワークフロー

SePay の実装

1. 認証設定のために references/sepay/overview.md を読み込みます
2. 連携のために references/sepay/api.md または references/sepay/sdk.md を読み込みます
3. 決済通知のために references/sepay/webhooks.md を読み込みます
4. Webhook の検証には scripts/sepay-webhook-verify.js を使用します
5. 本番環境への対応のために references/sepay/best-practices.md を読み込みます

Polar の実装

1. 認証と概念について references/polar/overview.md を読み込みます
2. 製品の設定について references/polar/products.md を読み込みます
3. 決済フローについて references/polar/checkouts.md を読み込みます
4. イベント処理について references/polar/webhooks.md を読み込みます
5. Webhook の検証には scripts/polar-webhook-verify.js を使用します
6. 提供を自動化する場合は references/polar/benefits.md を読み込みます
7. 本番環境への対応のために references/polar/best-practices.md を読み込みます

主な機能

SePay：

• 決済ゲートウェイ（QR、銀行振込、カード）
• Webhook による銀行口座の監視
• 注文ベースの仮想口座
• VietQR 生成 API
• 44 以上のベトナムの銀行に対応
• レート制限：毎秒 2 回

Polar：

• Merchant of Record（グローバルな税務コンプライアンス）
• サブスクリプションのライフサイクル管理
• 使用量ベースの課金（イベント、メーター）
• 特典の自動付与（GitHub、Discord、ライセンス）
• 顧客ポータル（セルフサービス）
• 多言語 SDK
• レート制限：毎分 300 リクエスト

手順

決済連携を実装する際は、次の手順に従ってください。

1. 要件（ベトナム向けかグローバル向けか、決済方法など）に基づいてプラットフォームを特定します
2. 必要に応じて関連するリファレンスを段階的に読み込みます
3. プラットフォーム固有の方法で認証を実装します
4. ビジネスモデルに応じて商品と価格を設定します
5. チェックアウトフロー（ホスト型、埋め込み型、API 駆動型）を実装します
6. 適切な検証を行う Webhook を設定します
7. 決済イベント（成功、失敗、返金）を処理します
8. 本番環境に移行する前に、サンドボックスで十分にテストします
9. プラットフォームの分析機能を利用して監視と最適化を行います

コンテキストを効率的に保つため、現在の実装手順に必要なリファレンスだけを読み込んでください。