決済照合では、アプリケーションの記録と、決済処理または入金を行うシステムから受け取った情報を比較します。目的は、何が何でもデータを一致させることではありません。一致しているもの、説明できるもの、調査が必要なものを特定することです。PHPアプリケーションでは、この区別をルールと運用フローの両方に反映する必要があります。
基本原則はシンプルです。差異を検出しても、残高、状態、会計記録を変更する権限が生じるわけではありません。信頼できる照合では、元データを保持し、利用可能な証拠を示したうえで、重要な判断を権限のある担当者、または明示的で検証可能なルールに基づくプロセスに委ねます。
対象範囲と信頼できる情報源を定義する
PHPで決済照合を実装する前に、どのエンティティを、どの期間について比較するのかを明確にします。決済、返金、チャージバック、手数料、入金には、それぞれ異なるライフサイクルやスケジュールがある場合があります。たとえば、日次売上合計だけを比較すると、返金や別の日に入金される決済が見えなくなることがあります。
照合の粒度も定義します。個々の取引、入金バッチ、期間別サマリーなどが考えられます。取引単位の照合では個別の事例を調査でき、入金単位の照合では振込額の理由を説明できます。多くのシステムでは、単一のレポートですべての疑問に答えようとせず、両方の視点を保持して相互に関連付けるのが適切です。
常に単一の信頼できる情報源が存在するとは限りません。注文と顧客については内部システム、処理された取引の識別子については決済システム、実際に受け取った振込については銀行記録や入金記録が基準となる場合があります。属性ごとにどの情報源を基準とするか、各状態が何を意味するかを文書化します。食い違いがある場合、この定義が調査の指針になります。自動的に最新の値を選んではいけません。
照合キーと正規化を定める
まず、決済処理時に保存した外部取引IDなど、共有される安定した識別子に基づいて照合します。フローによっては、取引種別、アカウントまたは加盟店、通貨も含める必要があります。注文で複数回の決済試行、部分返金、複数の取引が可能な場合、注文IDだけでは不十分です。
金額と日付の近さだけでレコードを照合するのは避けてください。これらの情報はレビュー候補の提示には使えますが、取引を一意に特定できるとは限りません。情報源に信頼できるキーがない場合は、結果を「曖昧」と分類し、候補提示の根拠となったフィールドを示します。可能性の高い一致を、何の通知もなく確定扱いにしてはいけません。
比較のために値を正規化しつつ、受信したデータとそのコンテキストはそのまま保持します。金額には、ドメインに適した10進表現（整数の最小通貨単位や10進演算など）を使い、浮動小数点数は避けます。数値だけでなく通貨も比較します。異なる通貨で数値が同じでも、同じ金額を表すわけではありません。また、総額、手数料、純額は別個の概念として保持します。
日付には文書化されたルールが必要です。取得できる場合は、時刻と元のタイムゾーンを保存し、オーソリ、売上確定、入金の日付を区別します。状態については、元の状態を削除せず、外部の値を内部カテゴリに対応付けます。不明な状態は「未認識」として表示し、デフォルトで「失敗」や「完了」に変換してはいけません。
不確実性を隠さず結果を分類する
結果を読みやすく示すことで、運用チームと技術チームは解決済みの事例と対応が必要な事例を区別できます。最低限、各比較結果を次のカテゴリに分類します。
- 一致: 対応関係があり、明示されたルールに基づいて重要なフィールドが一致している。
- 説明可能な差異: 想定される手数料や入金タイミングのずれなど、差異を説明する文書化済みのルールがある。
- 未解決の不一致: レコード間に関連はあるものの、重要なフィールドに差異があり、事例を解決する証拠が十分でない。
- 対応レコードなし: 照合対象の範囲内で、一方の情報源のレコードに他方の対応レコードがない。
- 曖昧または不完全: データが不足している、または複数の対応候補がある。
分類ではラベルだけでなく、理由を説明する必要があります。たとえば、問題が金額の相違、通貨の欠落、イベントの遅延、未知の識別子のどれなのかを記録します。データの欠落と値がゼロのデータは区別してください。両者は同じではなく、必要な対応も異なる場合があります。
監査可能で安全なレビューを設計する
レビューキューには、両方の情報源のレコード、元の値、正規化したフィールド、適用したルール、元ファイルやバッチIDなどの関連証拠を表示します。また、誰が、いつ、どのような判断をし、その理由は何かも示します。データを修正する場合は、適用されるアクセス権限と保持ポリシーに従って、変更前の値と変更履歴を保持します。
検出と解決を分離します。不一致は、説明済みとしてクローズする、情報源の誤りとして確認する、または調査にエスカレーションすることができます。チームが調整を作成すると決めた場合は、承認、理由、証拠への参照を必須とし、元の記録を上書きするのではなく、追跡可能な取引として調整を保存します。これにより、照合上の仮説が財務上の事実として扱われるのを防げます。
影響に応じたアクセス制御を適用します。レポートを閲覧するすべての人に調整の承認権限が必要なわけではありません。判断や権限変更を記録し、差異の調査に不要な個人データを公開しないようにします。自動処理では、情報源に障害が発生した場合や、バッチを検証できない場合のアラートとエスカレーション経路を定義します。
効果を重複させずにバッチを再処理する
ファイルの到着が遅れたり、重複したり、問題の修正後に再インポートが必要になったりすることがあります。同じバッチを再度受信しても、取引、ケース、調整が重複して作成されないよう、処理を冪等に設計します。冪等性キーは、イベントやバッチの安定した識別子から導出できます。ただし、その適用範囲を明確に定義し、データベースで一意性制約を適用する必要があります。
ファイルの受信、検証、正規化、比較を分離します。情報源、対象期間、ハッシュまたは識別子、受信日時、検証結果などのバッチメタデータを保存し、必須の工程に失敗した場合は処理済みとしてマークしないようにします。大規模なバッチは、復旧可能な単位で処理し、進捗を記録します。再処理では、外部への効果を繰り返したり、過去の人による判断を消去したりせずに結果を再計算できる必要があります。
入力形式が変更された場合や、遅れてレコードが届いた場合は、期間の再計算、既存ケースの更新、新規ケースの作成のどれが必要かを判断します。過去の判断にどの情報が使われたかを確認できるよう、データの各バージョンと実行履歴の関係を保持します。
ルールをテストし運用を測定する
重複、順序が前後したイベント、部分返金、丸めによる金額差、異なる通貨、キーの欠落、不明な状態、初回締め後に到着したレコードなど、実際のフローにおけるリスクを反映したケースでルールをテストします。同じ入力を再処理して追加の効果が発生しないことを検証する冪等性テストも含めます。統合テストでは、情報源の実際のフォーマットと部分的なエラーへの挙動も検証します。
本番環境では、対応レコードのない件数、不一致の経過時間、曖昧なケース、失敗したバッチ、解決までの時間を監視します。こうした兆候は、フォーマット変更、配信遅延、商取引の動向と合わせて解釈してください。数値の増加だけで財務上の誤りがあるとは断定できませんが、リグレッションや情報源の不完全さを示している可能性があります。
締め処理の手順では、誰が調査し、誰が調整を承認し、どの証拠を十分とみなすかを明確にします。差異を説明できない場合は、判断が文書化されるまで未解決のまま、確認可能な状態にしておきます。この規律によって、PHPの決済照合は、差異をただ消し去るだけの定型処理ではなく、運用上の統制手段となります。
