技術負債化した決済機能を安全に改修する方法
「決済まわりだけは、もう誰も触りたがらないんです」——既存プロダクトの改修相談で、この言葉を聞かない月はほとんどありません。機能追加の中でも決済コードだけは後回しにされ、気づけば継ぎ足しの分岐だらけになり、最初に書いたエンジニアもすでに退職している、というのはよくある光景です。
決済は「バグったら金額がズレる・二重に課金する・返金が反映されない」という、他の機能とは失敗の重さが違う領域です。だからこそ「怖くて触れない」まま放置され、身動きが取れなくなっているプロダクトを数多く見てきました。この記事では、技術負債化した決済機能を、外部チームとしてどう安全に改修していくかを整理します。
なぜ決済コードは他より怖いのか
通常の機能であれば、バグが出ても「表示がおかしい」「一部の操作ができない」程度で済み、リリース後に直せば挽回できます。決済コードが厄介なのは、失敗の種類がそもそも異なるからです。
- お金の整合性が壊れる: 注文は成立しているのに課金されていない、あるいは二重に課金される
- 失敗が即座に見えない: 決済代行会社のWebhookが数分〜数時間遅れて届くと、その間の状態不整合に気づけない
- 修正の副作用が大きい: 「ついでに直した」つもりの変更が、既存の正常系の金額計算を狂わせる
こうした失敗は返金対応・カスタマーサポート対応というコスト、そして何より顧客の信頼を直接損ないます。だから決済コードは「動いているなら触らない」という判断が積み重なり、結果として一番古く一番複雑な部分が温存されていくのです。
決済コードが複雑化する典型パターン
改修の相談を受けるプロダクトの決済まわりには、共通する負債パターンがあります。
- 条件分岐の継ぎ足し: 「このプランだけ税率が違う」「キャンペーン中だけ計算式が変わる」といった例外が、既存コードを直さずif文の追加で対応され続けた結果、分岐が数十段になっている
- 決済代行APIのバージョン混在: 古いAPIバージョンで実装した箇所と、後から追加した新しいAPIバージョンの呼び出しが同居し、挙動の一貫性がない
- 状態管理が暗黙的: 注文ステータスがDBのフラグ列で分散管理され、「決済完了かどうか」の判定ロジックが複数箇所に重複している
- ログが最小限: 決済失敗時に「なぜ失敗したか」を追える情報がログに残っておらず、問い合わせが来ても再現・調査ができない
これらは一つひとつは小さな判断の積み重ねですが、合計すると「誰も全体像を把握していない」状態を作り出します。
改修の前提: 整合性と冪等性を最優先に置く
決済コードを改修するとき、機能追加や見た目の整理より先に確認すべきなのが、整合性(お金の帳尻が常に合っているか)と冪等性(同じ処理を複数回実行しても結果が変わらないか)です。
- 二重送信・二重処理の防止: ネットワークの再送やユーザーの連打で同じ決済リクエストが複数回飛んでも、二重課金にならない設計になっているか。決済代行会社が提供する冪等キー(idempotency key)を使っているかは特に重要な確認点です
- 注文と決済の状態の同期: 決済側の状態(成功・失敗・保留)と、自社DB側の注文状態が食い違うタイミングがないか。特にWebhookで非同期に決済結果が届く設計では、この同期のズレが最も事故の温床になります
- 返金・キャンセルの整合性: 返金処理が決済代行側だけで完結し、自社DB側の注文状態や在庫に反映されないケースがないか
これらは「バグを直す」というより「壊れたときに検知できる仕組みを先に作る」という発想に近いものです。改修に着手する前に、この安全網が現状どこまであるかを棚卸しするところから始めます。
テストの安全網: 決済は「特性化テスト」が特に効く
決済コードの改修は、テストがないシステムを安全に改修する進め方で紹介した特性化テスト(現状の挙動をそのまま固定するテスト)のアプローチが特に有効です。決済は「あるべき仕様」が曖昧なまま実装されているケースが多く、まず正解を決めるより先に「今何が起きているか」を機械的に固定するほうが安全に進められます。
- 主要な金額計算(税込計算、割引適用、複数プラン混在時の合算)を、実際の入力データで固定テスト化する
- 決済代行APIとの通信は本番に依存せず、モックやサンドボックス環境でリクエスト・レスポンスのパターンをテスト化する
- Webhook受信の処理は、遅延・重複・順序入れ替わりのケースを意図的に再現するテストを用意する
ここまで安全網ができて初めて、「ロジックを整理しても金額計算の結果が変わらない」ことを確認しながらリファクタリングに着手できます。テストなしで決済コードを書き直すのは、事故が起きても誰も気づけないという最も危険な進め方です。
段階改修の進め方: 一度に書き直さない
決済コードは「全部書き直したい」という誘惑が強い領域ですが、実際に安全に進めるには小さく分割することが不可欠です。
- 観測を先に増やす: リファクタリングの前に、決済フローの各ステップにログ・アラートを足し、現状どこで何が起きているかを可視化する
- 境界を切り出す: 決済処理をモジュール・サービスクラスとして独立させ、呼び出し側から実装詳細を隠す。これにより後続の変更が呼び出し側に波及しにくくなる
- 並行稼働で検証する: 新しいロジックと旧ロジックを並行して走らせ、結果を突き合わせてから旧ロジックを段階的に落とす(シャドーテスト的な進め方)
- 小さくリリースする: 一部のプラン・一部のユーザー層から新ロジックを適用し、問題が起きても影響範囲を限定する
この進め方は時間がかかるように見えますが、決済で「一発勝負のビッグバンリリース」をして事故を起こすコストと比べれば、結果的に早く安全にたどり着けます。
決済代行サービスへの移行を検討すべきタイミング
自社で決済ロジックを作り込みすぎているプロダクトでは、決済代行サービス(Stripeなど)への移行や活用範囲の拡大を検討する価値があります。判断の目安は次のとおりです。
- カード情報を自社サーバーで扱っている(PCI DSS準拠の負担が大きい)
- 税率変更・国際対応・不正検知など、決済代行側がすでに解決している問題を自前で再実装し続けている
- 決済まわりの改修のたびに「壊れないか」の不安が開発速度を大きく落としている
一方で、すでに決済代行サービスを使っている場合でも、古いAPIバージョンのまま止まっていたり、提供されている冪等性・Webhookの仕組みを活かしきれていないケースは多くあります。移行より先に「今使っているサービスの機能を使い切れているか」を確認するほうが、投資対効果が高いこともあります。
監査ログを軽視しない
決済コードの改修で見落とされがちなのが監査ログです。「誰が・いつ・どの注文に対して・どんな操作をしたか」を後から追跡できる記録は、問い合わせ対応だけでなく、改修そのものの安全性にも直結します。
- 金額変更・返金操作は、実行者と理由をセットで記録する
- Webhook受信の生データは一定期間保持し、後から再検証できるようにする
- 決済ステータスの変更履歴を、上書きではなく追記型で残す
監査ログが整っていないプロダクトでは、改修後に「意図した挙動か、バグか」の判断材料自体が存在しません。改修と同時に、この記録の仕組みを整えることを強くおすすめしています。
外部チームに依頼するときの進め方
私たちが決済まわりの改修を引き継ぐときも、いきなりコードを書き直すことはしません。まず現状の決済フロー全体を図に起こし、整合性が壊れうるポイントを洗い出すところから始めます。その上で特性化テストを主要な金額計算とWebhook処理に足し、観測(ログ・アラート)を強化してから、段階的にリファクタリングを進めます。
決済コードは他の改修以上に「発注者側の業務知識」が必要な領域です。税率・キャンペーン条件・返金ポリシーなど、コードだけでは読み取れない仕様が絡むため、要件整理の段階でしっかり時間を取ります。負債の全体像や取り組む順番の考え方は既存プロダクト改善、外部チームが最初に見る観点でも解説していますので、あわせてご覧ください。
まとめ
- 決済コードは「バグの重さ」が他の機能と根本的に違うため、整合性・冪等性・返金の同期を最優先に安全網を張ることが改修の出発点になる
- 一度に書き直さず、観測を増やす→境界を切り出す→並行稼働で検証する→小さくリリースする、という段階的な進め方がリスクを最小化する
- 決済代行サービスの活用範囲や監査ログの整備も、改修と同時に見直す価値が高い
「決済まわりだけは怖くて誰も触れない」という状態でも、torcheees はご相談を受け付けています。まずは開発診断の「既存プロダクト改善」で、決済フローのリスクの見極めと改修の進め方をご提示します。継続的な改善支援も承っています。お問い合わせフォームからお気軽にご連絡ください。