決済は成功したのに注文の更新に失敗するチェックアウトを考えてみてください。顧客にはエラーが表示され、再試行します。その間に、カスタマーサポートには取引記録があり、倉庫には確定した注文がなく、財務は顧客に支払い義務があるかどうかを把握する必要があります。

どのシステムがこの状況を解決すべきでしょうか。こうしたインシデントこそ、アーキテクチャの意思決定が顕在化する場面です。所有権が未定義のままだと、発生のたびに場当たり的な修正が行われ、その修正は書きやすい場所に蓄積していきます。

アーキテクチャは、最初の取引が本番環境に到達する前にこの問いに答えておくべきです。さもなければ、決済コードは徐々に注文のリカバリ、サブスクリプションのルール、請求書の調整、出荷の判断を吸収していきます。

以下に示す所有権モデルは実践的な出発点を提供します。ゲートウェイをプロバイダーとの通信に集中させ、決済オペレーションに専用の場所を与え、商用の判断は請求管理と注文に委ねる、というものです。

3つではなく、4つの責任から始める

この設計では、決済ゲートウェイをより広範な決済サービスと区別します。モデルは、ゲートウェイ、決済サービス、請求管理、注文をカバーする4つの論理的境界を使用します。

これらは所有境界として扱い、4つのマイクロサービスをデプロイせよという指示ではありません。チームに合うなら、単一アプリケーション内のモジュールから始めても構いません。いずれにせよ、責任を明示的にしておくべきです。

決済ゲートウェイアーキテクチャを見直す際には、ポーネント図を意思決定マップとセットにしてください。金額を誰が決めるのか、徴収を誰が依頼するのか、結果を誰が記録するのか、次のビジネスアクションを誰が承認するのか、というマップです。

ゲートウェイをプロバイダーの近くに置く

ゲートウェイには狭いコントラクトを与えます。サポートされた決済オペレーションを受け付け、プロバイダーの形式に変換し、決済サービスが解釈できる結果を返すべきです。

この分離には実用的な動機があります。決済プロバイダーはAPI、認証方式、フィールド形式、通知メカニズムが異なり、そのばらつきを一つのレイヤーに集約することで、システムの他の部分をプロバイダー固有の仕様から隔離できます。

ゲートウェイには次のような責任を割り当てます:

• プロバイダー向けリクエストの検証
• プロバイダーとの通信の認証
• 内部フィールドのプロバイダー固有フィールドへの変換
• プロバイダーから届く通知の検証
• 有用なプロバイダー情報を保持しつつレスポンスをマッピング

プロダクトの知識はそのコントラクトから排除します。ゲートウェイがロイヤルティ階級、出荷可否、サブスクリプションの猶予期間、プロモーションバンドルを理解する必要はありません。承認済みの金額、通貨、決済参照、必要な支払い手段の情報を渡します。それらを生み出したルールではありません。

有用なレビューの問い:返品ポリシーを変えるのにゲートウェイコードの変更が必要になりますか。その場合は境界を見直してください。

決済オペレーションに別の所有者を与える

決済の試行とその結果は決済サービスに属します。試行ごとに、内部識別子、関連するプロバイダー参照、要求金額、通貨、オペレーション種別、状態を記録します。何が要求され、何が実際に確定されたかを調査できるだけの履歴を残します。

モデルを単一の「支払い済み」フラグに還元することは避けてください。代わりに、ワークフローが必要とする区別を定義します。未解決の結果も含めてです。プロバイダーとの通信には本物の不確実性が伴います。タイムアウト、遅延通知、順序不同の更新は日常的な出来事であり、状態モデルはあらゆる結果を成功か失敗かに圧縮するのではなく、曖昧さを受け入れる余地を必要とします。

次のような仮説的なシーケンスを明示的に設計してください。決済サービスがオーソリゼーションを要求し、リクエストはプロバイダーに届くが、レスポンスが失われる。そしてアプリケーシンは次に何をすべきか判断しなければなりません。タイムアウトが自動的に新しい課金を引き起こすことは決してあってはなりません。別のオペレーションを許可する前に、決済サービスが元の試行を解決または安全に管理することを要求してください。

2種類のリトライも区別すべきです:

• 技術的リトライ:定義された安全ルールの下で、同じ意図されたオペレーションの通信を繰り返すこと。
• 徴収リトライ:未収残高の回収を新たに試みること。

技術的リトライの処理は決済インテグレーション設計に割り当てます。徴収のタイミングと適格性は請求管理が決定し、決済サービスが承認された試行を実行します。

何が支払われるべきかは請求管理が決める

請求管理は金銭的債務を所有します。課金計算、請求書、クレジット、残高です。サブスクリプション商品の場合、プラン変更、日割り計算、請求期間、徴収スケジュールのルールはここに属します。

請求管理には、明示的な金額、通貨、および回収対象の債務への参照を伴う徴収リクエストをすべて発行することを要求してください。決済サービスは結果を報告し、その結果が残高にどう影響するかは請求管理が判断します。

30ドルのクレジットが付いた100ドルの請求書という仮説を考えてみてください。請求管理は残りの70ドルを要求すべきです。ゲートウェイにサブスクリプションのメタデータからその計算を再構築させてはなりません。

価格設定が複雑になるほどリスクは大きくなります。誤ったコンポーネントに置かれた計算はすべて、後から見つけ出し、移行し、システム間で突き合わせなければならないロジックになります。

返金後も同じ規律が適用されます。プロバイダーを通じて何が返金されたかは決済記録が確定し、どの請求書や残高調整がその返金に対応するかは請求管理が判断します。

購入をどう扱うかは注文が決める

出荷と購入ライフサイクルの判断は注文ドメインに留めます。決済サービスは決済結果を公開すべきであり、倉庫への指示を発行すべきではありません。注文ワークフローは、その結果を他の要件と併せて解釈します。結果の解釈は技術的な判断であると同時にビジネス上の判断でもあります。同じ確定済み決済でも、出荷モデルによって重みが異なり得るためです。

明示的な出荷ルールの一例:必要な決済条件が満たされ、在庫が確保され、必要なレビューが完了したときにのみ注文をリリースする。決済条件はビジネスモデルに合わせて選択すべきであり、プロバイダーのレスポンスハンドラの中に埋もれてはなりません。

キャンセルにも同じ分離が必要です。キャンセルが許可されるか、購入をどう扱うかは注文が決め、そのうえで適切な決オペレーションを決済サービスに依頼します。注文のキャンセル、オーソリゼーションの解放、決済の返金、サブスクリプションの解約のいずれの意味にもなり得る、多重義務を負った「キャンセル」コマンドは避けてください。各アクションに正確な名前を付けてください。

一つのシステムにすべての仕事を与えずに返金を調整する

返金ワークフローは、境界が機能しているかを試す良いテストです。3点注文から1点を顧客が返品するとします。ワークフローを次のように構成します:

• 返品または注文コンポーネントが返品を承認する。
• 指定された商用計算の所有者が返金可能額を決定する。
• 決済サービスが決済履歴と適用可能なオペレーション制限を確認する。
• ゲートウェイがプロバイダーへリクエストを送信する。
• 決済サービスが確定または未解決の結果を記録する。
• 請求管理と注文がそれぞれの記録を更新する。

各計算に一人の所有者を割り当てます。請求管理と注文がそれぞれ独立に異なる返金額を計算し、決済に選択を委ねるようなことはすべきではありません。

「返金要求」を「返金確定」とは区別してください。プロバイダーの結果が未解決の場合は、その不確実性を保持し、ワークフロー全体を完了とマークするのではなく、調査の道筋を提供してください。

リカバリをコントラクトの一部にする

境界をまたぐすべてのオペレーションでは、成功レスポンス以上のことを明示すべきです。文書化すべき項目:

• 繰り返しのリクエストをどう識別するか
• どのコンポーネントが権威ある状態を所有するか
• 遅延または重複した通知をどう扱うか
• 次のコンポーネントが利用不可の場合に何が起こるか
• スタッフが未解決の結果をどう調査するか
• どのアクションを安全にリトライできるか

特に繰り返しのリクエストについては、プロバイダーがまさにこの目的のために設計された冪等性メカニズムを提供しているのが一般的で、同じオペレーションを二重実行なしに再送信できます。

各ドメインに独自の識別子を与え、明示的に関連付けてください:注文ID、請求書ID、決済ID、試行ID、プロバイダー参照。一つの識別子ですべての関係を表現させるのは避けてください。

サポートスタッフには統合されたタイムラインを提供できますが、修正は所有コンポーネントの管理下に留めるべきです。便利なダッシュボードが、決済履歴の上書きや請求書残高の無言の変更を許す権限になってはなりません。

ビジネスの変更で境界をテストする

設計を承認する前に、いくつかの変更をウォークスルーしてください:

• 価格ルールを変えずに決済プロバイダーを追加する。
• ートウェイアダプターを編集せずにサブスクリプションの徴収タイミングを変える。
• プロバイダー通知処理を書き直さずに部分返品を導入する。
• 決済状態の定義を変えずに出荷ポリシーを変更する。

予期しないコンポーネント横断的な変更はレビューのシグナルとして扱ってください。調整には正当なものもありますが、説明のない結合は注意を要します。

所有権のドリフトは自らを告げることはめったになく、一度の都合の良い変更の積み重ねで進行します。新しいプロバイダー、決済手段、価格モデルを導入するたびにこれらのウォークスルーを再実行すれば、初期の設計レビューから長く経った後も境界を明示的に保てます。

ゲートウェイはプロバイダー向けの決済通信で終わるべきです。決済サービスは決済の実行と証拠を所有すべきです。請求管理は債務と残高を所有すべきです。注文は購入とその出荷を所有すべきです。

これらの責任をインターフェース、リカバリ手順、チームの所有権に書き込んでください。図だけでは分離を保てません。