決済基盤の整合性設計を仕様から決める。バクラク請求書発行のカード決済における2つの判断

はじめに こんにちは。LayerX でソフトウェアエンジニアをしている @ysakura_ です。バクラク請求書発行のカード決済機能の新規開発を担当しました。これは、発行した請求書に対してクレジットカードでの決済を受け付けられるようにする機能です。取引先がクレジットカードで支払うと、バクラク請求書発行の利用者には銀行振込で請求書の代金が入金されます。カード決済の受付から銀行振込での入金までの一連のプロセスを実装するにあたり、決済基盤の整合性設計において重要な判断を2つ行いました。本記事では、その判断に至った背景と設計の考え方を共有します。 ケース1: 決済実行時の保存失敗 — 仕様は「ユーザー体験を壊さない」 課題と仕様 カード決済の実行中に、決済情報の保存に失敗する可能性があります。例えば、データベースへの書き込みがタイムアウトしたり、ネットワークエラーが発生したりするケースです。この場合の仕様として、「ユーザー体験を壊さない」ことを最優先としました。具体的には、ユーザーに対して決済処理が失敗したことを明確に伝え、再試行を促す一方で、決済プロバイダ側とのトランザクション状態に不整合が生じないようにする必要がありました。 設計の考え方 保存失敗が発生した場合、まず決済プロバイダとの通信状態を確認します。決済が既にプロバイダ側で完了している可能性があるため、冪等性を確保した再試行メカニズムを設計しました。ユーザーには「処理中です」などの曖昧なメッセージではなく、「保存に失敗しました。もう一度お試しください」と具体的にエラーを表示します。バックエンドでは、保存失敗を検知した際に補正処理を実行し、プロバイダ側との状態を同期させることで、データの不整合を防ぎます。 ケース2: 送金結果不明 — 仕様は「統制・監査上の説明可能性」 課題と仕様 カード決済後、銀行振込による入金処理において、送金結果が不明（例: 銀行側の応答がない、タイムアウト）になるケースがあります。この場合の仕様として、「統制・監査上の説明可能性」を重視しました。金融規制に準拠し、すべての取引について監査証跡を残し、後からでも状態を追跡できるようにする必要がありました。 設計の考え方 送金結果不明が発生した場合、システムは即座に異常状態としてフラグを立て、監査ログに詳細を記録します。その後、定期的なポーリングや銀行からの通知（webhook）を活用して結果を確認する非同期プロセスを設計しました。ユーザーには入金遅延の可能性を通知し、内部では「保留中」状態として管理します。これにより、監査時に「いつ、どのような理由で結果不明になったか」を説明可能にし、規制要件を満たします。また、自動復旧メカニズムを組み込むことで、人的介入を最小限に抑えています。 おわりに 決済基盤の設計では、技術的な課題だけでなく、ユーザー体験や規制対応といった仕様から整合性設計を考えることが重要です。今回の2つのケースでは、「ユーザー体験を壊さない」と「統制・監査上の説明可能性」という異なる仕様を出発点に、それぞれ適切な設計判断を行うことができました。バクラク請求書発行のカード決済機能は、これらの設計に基づき、安定して稼働しています。決済システムを開発される際の参考になれば幸いです。

背景や根拠まで確認しますか？

関連記事

調べる

選ぶ

サイト