通知パラメータ仕様

取引・返金・チャージバック・定期課金の状態が変わると、Wire Pay は加盟店の システム通知先 URL にリクエスト（Webhook）を送信します。送信内容は加盟店ごとの 3 つの設定で決まります。加盟店の追加・詳細画面（通知設定タブ）では、設定に応じた 実際のリクエストのサンプル をリアルタイムに確認できます。送信の記録・再送は Webhook 送信ログ を参照してください。

1. 通知の型（送信方法）

2. 送信パラメータセット（累積）

3. 決済識別子の形式

パラメータ一覧

パラメータの順序は「識別子 → 最小 → 標準 → フル」で固定です（フォーム / クエリの署名検証で順序が重要になるため、受信側は 受け取ったボディ / クエリ文字列をそのまま 署名対象にしてください）。

イベントと status の値

ヘッダー

署名の検証

signed_payload = "<X-Timestamp>" + "." + <署名対象>      # 署名対象は上表（ボディ、または GET のクエリ文字列）
v1 = hex( HMAC_SHA256( key = 署名鍵, message = signed_payload ) )

署名鍵 は次の優先順位で決まります。

1. 加盟店の 署名シークレット（加盟店詳細 → APIキータブで発行する wp_<test|live>_ss_…）。通知と同じモード（テスト / 本番）で、失効・期限切れでない最新のもの
2. 同じ環境に使用可能な署名シークレットが無い場合、通知は 送信されません（送信ログに failed / signing_secret_missing。加盟店パスワードで代用することはありません）

受信側の手順:

1. ヘッダーから X-Timestamp と X-Signature の v1 を取り出す。
2. 受け取ったボディ（GET はクエリ文字列）をパースせず そのまま 使って v1 を再計算し、定数時間比較 で一致を確認する。
3. X-Timestamp が現在時刻から 5 分以上 ずれている場合は拒否する（リプレイ対策）。
4. 検証に成功したら event と payment_id で処理を分岐し、2xx を返す。

Node.js の例:

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(req, rawBody, secret) {
  const ts = req.headers["x-timestamp"];
  const v1 = String(req.headers["x-signature"] ?? "").replace(/^v1=/, "");
  if (!ts || !v1 || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex");
  return expected.length === v1.length && timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

再送と冪等性

• 応答が 2xx 以外、または 10 秒 以内に応答が無い場合は失敗として記録し、1 分 → 5 分 → 30 分 → 2 時間 → 24 時間 の間隔で最大 5 回まで自動再送します。5 回失敗すると断念し、管理画面から手動で再送できます。
• 同じ payment_id + event の通知は 複数回届く可能性 があります（再送・手動再送）。受信側は冪等に処理してください。
• 1 つの取引に対して複数のイベント（例: payment.completed → refund.completed）が届きます。順序は保証されないため、paid_at / status ではなく自システムの状態と event で判断してください。

サンプル（JSON / 標準 / 一意の決済IDのみ）

POST https://shop.example.jp/wirepay/notify
Content-Type: application/json
X-Timestamp: 1756697696
X-Signature: v1=3f0c9c5d...
Wirepay-Signature: t=1756697696,v1=3f0c9c5d...
User-Agent: WirePay-Notify/1.0

{
  "payment_id": "pay_01J9X4M8K2Q7Z3T6",
  "event": "payment.completed",
  "merchant_id": "MER-00001",
  "amount": 4980,
  "currency": "JPY",
  "paid_at": "2026-09-01T12:34:56+09:00",
  "status": "captured",
  "payment_method": "credit",
  "user_id": "user_10293",
  "product_id": "SKU-2026-0042"
}

デモ環境では seed の加盟店の通知先が /api/demo/webhook-receiver になっており、?result=ok|error|timeout で応答を切り替えて再送の挙動を確認できます。