SILVERCLOUD / 技術記事
信頼できる決済確認:アプリとWebサイトのためのサーバー側チェックリスト
お客様が「支払う」をタップし、緑のチェックマークを見てアプリを閉じる。その注文は支払い済みでしょうか。おそらくそうでしょう。ただ、お金のことで「おそらく」では足りません。チェックマークが示すのは、ある端末が一連の画面を最後まで進んだということだけです。お金が実際に動いたかどうかを知っているのは決済事業者であり、サーバーはそれを決済事業者から直接、第三者が偽装できない経路で受け取る必要があります。
このチェックリストでは、決済の状態、サーバー側での確認、安全な再試行、返金、照合、テストを取り上げます。カード、スマホ決済、QRコードによる振込のいずれにも当てはまります。
完了画面は確認ではない
支払いを終えたお客様は、多くの場合 ?status=success&order=1042 のようなパラメータ付きでWebサイトやアプリに戻ってきます。これを証拠として扱うと、三つの点で破綻します。
- 誰でも書き換えられる。 ブラウザで
failedをsuccessに変えるのは数秒です。 - そもそも読み込まれないことがある。 タブを閉じる、電波が途切れる、銀行アプリから戻ってこない。決済は成功しているのに、サーバーはそれを知りません。
- 入金より先に届くことがある。 銀行振込をはじめ一部の決済手段は、お客様の操作が終わった後もしばらく保留のままです。
戻り先のページには「決済を確認しています」と表示し、自社のサーバーに状態を問い合わせます。サーバーは検証済みの情報源しか信用しません。注文が支払い済みかどうかを、クライアント側が決めることはありません。
決済の状態
単一の paid フラグではなく、決済の状態を明示的にモデル化します。
- 作成済み:決済事業者に登録済みで、まだ支払われていない。
- 保留中:お客様が操作した、または振込が進行中で、結果は確定していない。
- 成功:決済事業者が支払いを確定した。
- 失敗:拒否、キャンセル、またはブロックされた。
- 期限切れ:支払い期限までに結果が出なかった。
- 一部返金と全額返金:成功後に、一部または全額が返された。
カードではさらに「オーソリ済み・売上未確定」の状態や、後日のチャージバック(異議申し立て)が加わることがあります。許可する状態遷移はコードに書き出しておきましょう。作成済みは保留中へ、作成済みと保留中は成功・失敗・期限切れへ、成功は一部返金・全額返金へ進めます。一部返金のあとに追加で返金することもできますが、作成済みや保留中に戻ることはありません。それ以外の変化は、バグか、人が確認すべきケースです。
検証できる情報源から、サーバー側で確認する
信頼できる情報源は二つあり、堅牢な連携では両方を使います。
署名付きWebhook。 何かが起きると、決済事業者がエンドポイントを呼び出します。多くの事業者は共有シークレットで各リクエストに署名します。一般的には生のリクエストボディに対するHMAC-SHA256で、タイムスタンプを含めることもよくあります。ハンドラーでは次のことを行います。
- 受け取ったままの生のボディを読む。JSONをパースして再シリアライズすると、空白、エスケープ、キーの順序が変わることがあり、署名が一致しなくなります。
- HMACを計算し、ヘッダーの値と定数時間で比較する。通常の文字列比較は最初に異なる文字で止まるため、その時間差から正しい署名の情報が漏れるおそれがあります。
- 短い許容時間(よく使われるのは5分)を外れたタイムスタンプは拒否し、傍受されたリクエストを後から再送(リプレイ)できないようにする。許容時間内の再送は、イベントIDでの重複除去で防げます。
- 金額、通貨、注文番号を、作成した注文と照らし合わせる。署名が正しければ送信者は証明できますが、正しい注文に正しい金額が支払われたことの証明にはなりません。金額は通貨の最小単位の整数で保存し、浮動小数点は使いません。
決済事業者のAPI。 サーバーからシークレットキーを使い、IDで決済を照会します。Webhookの遅延や欠落はこれで補えます。Webhookを単なる合図として扱い、受け取るたびに最新の状態を取りに行くチームもあります。
APIキーとWebhookのシークレットはサーバー上だけに置き、アプリにもリポジトリにも含めず、無停止でローテーションできるようにしておきます。
冪等性:同じイベントが二度届いても何も変わらない
多くの決済事業者は、Webhookを「少なくとも一回」配信します。エンドポイントがタイムアウトしたりエラーを返したりするとイベントは再送され、それが何度も続くこともあります。重複は例外ではなく日常なので、処理は冪等でなければなりません。
- イベントIDで重複を除く。 処理済みのイベントIDを一意制約のもとで保存すれば、再配信されても何も変わりません。
- 一つのトランザクションで、更新は一度。 イベントIDの記録と注文状態の変更を、同じデータベーストランザクションで行います。失敗すれば両方がロールバックされ、再試行はまっさらな状態から始まります。更新には条件(
WHERE status = 'pending')を付け、同時に届いたWebhookとAPI照会が同じ注文を二重に処理しないようにします。 - 決済と返金の作成には冪等キーを付ける。 事業者が対応していれば、自社の決済試行IDからキーを作ります。タイムアウト後に再試行しても二重請求にはならず、最初の結果が返ります。対応していなければ、先に一意の参照番号で自社の記録を保存し、再試行の前にその番号で照会します。
- イベントの順序は入れ替わる。 配信順は一般に保証されず、成功イベントが返金イベントより後に届くこともあります。最後に届いたイベントで上書きせず状態遷移の定義に従い、迷ったら最新の状態を照会します。
- バックオフ付きで再試行する。 タイムアウト、接続エラー、429と5xxの応答は、指数バックオフとジッターを使い、回数に上限を設けて再試行します。入力検証のエラーは再試行しません。
- タイムアウトは「失敗」ではなく「不明」。 請求は通っているかもしれません。照会して確定させます。
- 期限切れは定期処理で。 期限を過ぎても保留中の決済をジョブが拾い、事業者に状態を確認してから期限切れにします。期限切れの後に成功が届いた場合(銀行振込では起こり得ます)は、事前に決めたルールに従って確認キューに回すか返金します。
Webhookには素早く応答します。保存してコミットし、2xxを返し、メール送信や出荷のような重い処理はキューに回します。遅いハンドラーはタイムアウトを生み、タイムアウトはさらなる重複を生みます。
コードにするとこうなる
Node.jsとPostgreSQLを使った、TypeScriptによる最小限のハンドラーです。ヘッダー名、署名のエンコード、署名対象の文字列は事業者ごとに異なりますが、全体の形は変わりません。
import { createHmac, timingSafeEqual } from "node:crypto";
import { Pool } from "pg";
const pool = new Pool(); // reads the PG* environment variables
const SECRET = process.env.PAYMENT_WEBHOOK_SECRET!; // server-side only, never in the app
export async function handlePaymentWebhook(req: Request): Promise<Response> {
const raw = Buffer.from(await req.arrayBuffer()); // the exact bytes, before any JSON parsing
const timestamp = req.headers.get("x-signature-timestamp") ?? "";
const received = Buffer.from(req.headers.get("x-signature") ?? "", "hex");
const expected = createHmac("sha256", SECRET).update(`${timestamp}.`).update(raw).digest();
const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300; // Unix seconds, 5 minutes
if (!fresh || received.length !== expected.length || !timingSafeEqual(received, expected)) {
return new Response("invalid signature", { status: 400 });
}
const event = JSON.parse(raw.toString("utf8"));
const db = await pool.connect();
try {
await db.query("BEGIN");
// event_id is the primary key: a repeated delivery inserts nothing.
const inserted = await db.query(
"INSERT INTO processed_events (event_id) VALUES ($1) ON CONFLICT DO NOTHING", [event.id]);
if (inserted.rowCount === 1 && event.type === "payment.succeeded") {
// Only pending -> paid, and only if amount and currency match the order.
const paid = await db.query(
`UPDATE orders SET status = 'paid', paid_at = now()
WHERE id = $1 AND status = 'pending' AND amount = $2 AND currency = $3`,
[event.data.order_id, event.data.amount, event.data.currency]);
if (paid.rowCount === 0) await db.query("INSERT INTO payment_review (event_id) VALUES ($1)", [event.id]);
}
await db.query("COMMIT");
return new Response("ok");
} catch {
await db.query("ROLLBACK");
return new Response("retry later", { status: 500 }); // the provider retries
} finally {
db.release();
}
}一致する保留中の注文がない場合(支払い済み、期限切れ、金額の不一致)、イベントは消えずに確認用のテーブルへ入ります。
返金、照合、監査証跡
返金は決済にひも付く独立したレコードで、独自の状態を持ちます。返金も保留になったり失敗したりするからです。一部返金の合計が売上確定額を超えてはいけません。返金リクエストには冪等キーを付け、注文の状態は事業者が確認してから変更します。
日次の照合は、ほかの仕組みが取りこぼしたものを拾います。毎日、前日分の取引レポートまたは精算レポートを決済事業者から取得し、各行を事業者側の取引IDで自社の記録と突き合わせ、金額、通貨、状態を比較します。よくある不一致は次のとおりです。
- 事業者側は支払い済み、自社システムは保留中:Webhookが失われ、支払ったお客様が待たされている。
- 自社システムは支払い済み、事業者側には記録なし:バグか不正利用で、最も緊急度が高い。
- 金額や状態が異なる:記録漏れの一部返金、または総額・手数料・入金額の取り違え。
不一致は担当者と対応メモ付きで差異キューに入れ、黙って修正することはしません。レポートの締め時刻にも注意が必要です。深夜0時前後の決済は、双方で別の日付に計上されることがあります。
監査証跡。 受け取ったWebhookはヘッダーと署名検証の結果ごと、すべて生のまま保存し、再送できるようにします。あわせて状態変更の履歴を追記専用で残し、どの状態から、どの状態へ、いつ、どのイベント・ジョブ・人によって変わったのかを記録します。シークレットやカード番号の全桁はログに残しません。事業者がホストする決済ページや埋め込み型の入力欄を使えば、カード番号が自社サーバーに届くことはありません。
アラートは、署名検証エラーの急増、処理エラー、保留のまま止まった決済、返金の失敗、照合の不一致、成功率の急低下で発火させます。
正常系だけでなく、失敗をテストする
決済事業者のサンドボックスまたはテストモードで、テスト用のキーを使って次を試します。
- Webhookをリプレイする。 実際のサンドボックスイベントをフィクスチャとして保存し、同じイベントを二度送る、順序を逆にする、ボディを1バイト変える、古いタイムスタンプを使う。
- 障害を注入する。 コミット後、2xxを返す前にプロセスを止める。事業者が再送しても、何ひとつ二重に起きてはいけません。データベースを1分間止める。事業者への呼び出しに遅延を加え、タイムアウトを発生させる。
- クライアントを想定外に使う。 「支払う」を連打する、リダイレクト前にブラウザを閉じる、偽のパラメータで戻り先URLを開く。
本番前チェックリスト
- 注文が支払い済みになるのは、検証済みのWebhookかサーバー側のAPI照会によってのみ。
- 署名は生のボディに対して定数時間で検証し、古いタイムスタンプは拒否する。
- 金額、通貨、注文番号を注文と照合する。
- イベントIDは一意で、重複には副作用なしで2xxを返す。
- イベントの記録と状態変更は一つのトランザクションでコミットし、更新には条件を付ける。
- 決済と返金の作成には、冪等キーまたは自社の参照番号による照会を使う。
- 状態遷移はコードで定義し、遅れて届いたイベントで注文の状態が後戻りしない。
- Webhookエンドポイントは事業者のタイムアウト内に応答し、重い処理はキューに回す。
- 外部呼び出しにはタイムアウトを設け、再試行は上限付きでバックオフとジッターを使う。
- 保留中の決済は状態を照会したうえで定期的に期限切れにし、期限後に届いた成功には対応手順がある。
- 一部返金が売上確定額を超えることはない。
- 照合を毎日実行し、すべての不一致に担当者がいる。
- 生のWebhookと状態履歴を保存し、ログにシークレットやカード番号の全桁を残さない。
- アラートが署名検証エラー、処理エラー、止まった決済、照合の不一致をカバーしている。
silvercloud は受託開発チームです。パートナー企業のアプリやWebサイトに、チェックアウトやWebhookから返金、照合までのこの層を組み込み、要件に合わせた決済ゲートウェイシステムも構築したうえで、先方のチームが運用できるよう引き渡します。決済連携をご検討中でしたら、silvercloud.city からブリーフをお送りください。