第三章：収金こそが真実 - ECPay 緑界金流連携の原理とWebhook災害予防

これまでの実戦コースでは、記事のロック方法、サイトの美化、GAを使ったトラッキングを学びました。
しかし、実際の商用SaaSサイトにおいて、これらの努力の最終目的はただ一つ：
「ユーザーが決済ボタンを押し、カード決済ページに進み、銀行での引き落とし成功後、システムが自動的に購入したコースのロックを解除すること」です。

多くの初心者エンジニアがSide Projectを練習する際、「偽の決済ボタン」を作成し、押すと「決済成功」のアラートが表示されるだけで完了とすることがあります。
しかし、実際の案件で「台湾の実在する決済システム（緑界科技ECPayなど）」と連携する必要が生じると、通常1～2週間行き詰まり、ロジックの誤りにより顧客の支払いは完了したのにコースが利用できないという深刻なクレームを引き起こす可能性があります。

この章では複雑なSHA256暗号化コード（こうした面倒な作業はVibe Promptを使ってAIに任せるべきです）には触れず、神の視点から金流連携の基盤アーキテクチャと動作ロジックを理解することに焦点を当てます。

🎯 本章の目標

オンライン決済連携の3つの核心段階を深く理解する
非同期通知ReturnURL（Webhook）の重要性を認識する - これはあなたのビジネス評判を守る鍵です
セキュリティ基準を満たした金流APIをAIに書かせるための高品質なVibe Promptの作成方法を学ぶ

💸 金流連携の3大核心段階（緑界を例に）

緑界（ECPay）、藍新（NewebPay）、あるいは国際的なStripeであっても、オンラインカード決済の基盤ロジックは以下の3つの標準段階から離れることはありません：

段階一：注文作成と偽造防止署名（Create Order）

ユーザーがあなたのサイトで3000元のプレミアムパッケージを見つけ、「今すぐ購入」ボタンを期待に胸を膨らませて押した時、フロントエンドは直接リダイレクトしてはいけません。

フロントエンドはまずAPIリクエストをバックエンド（例えばNext.jsのRoute HandlerやFastAPI）に送信する必要があります。
バックエンドでは以下の処理を行います：

データベースに「未払い」状態の注文レコードを作成し、重複しない注文番号（例：ORDER20240901001）を生成
.envに保存された機密のHashKeyとHashIVを取り出す（これは絶対にフロントエンドに知られてはいけません）
注文情報（金額3000、商品名）を緑界の規定する特殊なルールでソートし、HashKeyでSHA256暗号化を行い、CheckMacValue（偽造防止チェックコード）と呼ばれる文字列を生成
これらのデータを隠しHTMLフォームにパッケージ化し、フロントエンドに返す

段階二：クリーンルームへの転送（Redirect to Payment Gateway）

フロントエンドがCheckMacValueを含むHTMLフォームを受け取ると、JavaScriptで自動的にSubmit（Auto-Submit）します。
この時、ユーザーの画面は瞬時にあなたのサイトから離れ、緑界（ECPay）の公式グリーン決済ページに転送されます。

なぜこのような処理が必要なのでしょうか？
あなたのサーバーは国際クレジットカードPCI DSSセキュリティ認証を受けていないからです。もしユーザーにあなたのページで「クレジットカード16桁」を入力させ、一度でも情報漏洩が発生すれば、一生かかっても賠償しきれない可能性があります。
そのため、この最もリスクの高い「クリーンルーム」を緑界に任せます。この段階では、あなたはクレジットカード番号に一切触れず、結果を待つだけです。

段階三：非同期コールバック通知（Return URL / Webhook） - 最も失敗しやすい危険地帯

これはすべての初心者エンジニアが致命的なミスを犯しやすい部分です！

ユーザーが緑界で決済に成功した後、サイトに戻る1秒の間にブラウザを閉じてしまったり、新幹線でトンネルに入り通信が切断されたりする可能性があります。
もし「コースのロック解除とデータベースへの書き込み」ロジックを、フロントエンドが戻る「成功感謝ページ（ClientRedirectURL）」に実装していた場合、「お金を払ったのにコースが見られない」というクレームが大量発生します！

💡 業界標準の正しい方法：
段階一で、ReturnURL（例：https://api.your-website.com/ecpay/callback）を緑界に送信します。
緑界が銀行からの引き落とし成功を確認すると、緑界のスーパーコンピュータがバックグラウンドで、このURLにHTTP POSTリクエストを送信します。

これは、あなたが以前Line Botを開発した際にユーザーメッセージを受信したWebhookと全く同じ概念です！
このWebhook APIが緑界からの通知を受け取ったら、再度HashKeyで署名を検証し、ハッカーによる偽装リクエストでないことを確認した後、バックエンドがデータベースの注文ステータスを「支払い済み」に更新し、コースのアクセス権限を解除します。最後に、APIは緑界にプレーンテキスト1|OKを返し、「受信しました」と伝えます。

この非同期アーキテクチャにより、ユーザーのスマホが爆発しても、クレジットカードの引き落としが成功していれば、あなたのデータベースは正確に注文を完了できます。

🤖 Vibe Codingで危険地帯を乗り越える

緑界金流の暗号化ルールは非常に複雑で煩雑です（アルファベット順にソート、大文字小文字変換、特定の記号の特別なencodeが必要）。
アーキテクトであるあなたは、緑界の分厚く古いPDFドキュメントを一行一行コードに落とし込んではいけません！ これはVibeに反します。

🔥【究極のVibe Prompt実戦アドバイス】
プロジェクトに緑界金流を追加する場合、この精密な呪文をCursorやClaudeに投げてください：

現在のNext.js App Router（Node.js環境）プロジェクトで台湾のECPay（緑界金流）と連携する必要があります。
以下の2つのAPI Routesを作成してください：
1. /api/ecpay/createOrder：フロントエンドから送信された金額と商品名を受け取ります。ECPay AIOインターフェースの完全なSHA256暗号化ロジック（CheckMacValue）を実装し、緑界テスト環境に自動的にリダイレクトするHTML Form文字列を返します。
2. /api/ecpay/callback：緑界からの支払い成功通知（ReturnURL）を受信するWebhookです。逆CheckMacValue検証ロジックを実装します。検証成功後、端末に注文番号を出力し、必ず'1|OK'文字列を緑界に返します。
すべての特殊なURL Encode変換ルールを処理し、環境変数としてECPay_HashKeyとECPay_HashIVを使用するようにしてください。

AIがコードを生成したら、あなたは自分のキーを入力するだけで、24時間稼働する収金マシンのエンジンが簡単に完成します！

實作注意事項

Error Handling

try:
    result = ecpay.create_order(order_data)
except EcpayException as e:
    logger.error(f'ECPay error: {e}')
    return {"status": "failed", "message": str(e)}

安全性考量

所有 API 請求都應該有 checksum 驗證
不要在客戶端暴露金鑰
使用 HTTPS 傳輸
定期輪換 API 金鑰

よくある問題と解決策

| 問題 | 原因 | 解決方法 | |------|------|---------| | 期待通りの結果が出ない | パラメータ設定ミス | デフォルト値と境界条件を確認 | | 実行が遅い | アルゴリズムの効率 | より効率的なデータ構造を使用 | | メモリ不足 | データ量過多 | バッチ処理を検討 | | デバッグが困難 | ログ不足 | 詳細なログ出力を追加 |

さらに学ぶには

公式ドキュメントを読む
GitHubのオープンソース例を参照
コミュニティディスカッションに参加
コードを修正して結果の変化を観察