第 13 章 / 全 27 章
精算管理
加盟店ごとに、対象期間の売上から手数料・返金・チャージバック・振込手数料を差し引いた 差引支払額 を精算バッチとして管理します。
精算設定（加盟店詳細の「精算設定」タブ）
| 項目 | 説明 |
|---|---|
| 締めサイクル | 月末締め / 15日・月末締め / 週次締め。精算バッチの既定の対象期間になります |
| 支払サイト | 翌月末 / 翌月15日 / 翌々月15日 / 翌週。対象期間の終了日から振込予定日を計算します |
| 振込先口座 | 銀行名・支店名・口座種別（普通 / 当座）・口座番号（7〜8 桁）・口座名義。デモではダミーで構いません |
| 精算手数料 | 振込 1 回ごとに差し引く手数料（円） |
変更は操作ログ（merchant.settlement_update）に記録されます。
締めサイクルと対象期間
期間の境界はすべて 日本時間（Asia/Tokyo）の 0:00 で、サーバーのタイムゾーンに依存しません。生成フォームの既定値は「直近の締め分」です。
| 締めサイクル | 既定の対象期間（生成日を基準） | 例（9 月 3 日に生成） |
|---|---|---|
| 月末締め | 前月 1 日 〜 前月末日 | 8/1 〜 8/31 |
| 15日・月末締め | 生成日が 16 日以降なら当月 1 〜 15 日、15 日以前なら前月 16 日 〜 前月末日 | 8/16 〜 8/31 |
| 週次締め | 前週の月曜 〜 日曜 | 8/24 〜 8/30 |
期間は任意に指定できます（開始日 ≤ 終了日）。内部では終了日の 翌日 0:00 を排他的終端 として扱い、同じ加盟店・モードで開始日と終了日が同じバッチは 1 つしか作れません（重複は 409）。
| 支払サイト | 振込予定日（対象期間の終了日を基準） |
|---|---|
| 翌月末 | 終了日の翌月の末日 |
| 翌月15日 | 終了日の翌月 15 日 |
| 翌々月15日 | 終了日の翌々月 15 日 |
| 翌週 | 終了日の 7 日後 |
精算バッチの生成と計算
精算管理の上部フォームで加盟店と対象期間を指定して 生成する を押すと、次の明細行を集めてバッチを作ります。
| 種別 | 対象 | 判定に使う日時 | 金額 | 手数料 |
|---|---|---|---|---|
| 売上 | ステータスが完了 / 一部返金済 / 返金済 / チャージバックの取引 | 完了日時（capturedAt） | 取引金額（+） | 下記の式 |
| 返金 | 完了した返金申請 | 返金完了日時（completedAt） | 返金額（−） | 0 |
| チャージバック | 敗訴 / 確定したチャージバック | 確定日時（resolvedAt） | 異議額（−） | 0 |
- 手数料 =
floor(取引金額 × 料率% ÷ 100) + 固定手数料を取引ごとに計算します（円未満切り捨て）。料率は 取引の完了日時に適用中だった契約（契約・手数料タブの履歴で適用開始日 ≤ 完了日時の最新）の決済手段別の値です。契約が無い場合や決済手段が「その他」の場合は 0 円です。 - 内訳: 売上総額 = 売上行の合計、手数料合計 = 売上行の手数料の合計、返金合計・チャージバック合計 = それぞれの絶対値の合計、精算手数料 = 加盟店設定の値（バッチ 1 件につき 1 回）。差引支払額 = 売上総額 − 手数料合計 − 返金合計 − チャージバック合計 − 精算手数料。
- 返金・チャージバックは 発生した期間のバッチ で控除します（元の売上がどの期間でも構いません）。差引支払額がマイナスになることもあります。
- 本来は締めサイクルごとに自動で走る処理ですが、デモでは手動で生成します。ヘッダーの テスト / 本番 スイッチで対象データが切り替わります。本番運用ではテストモードの取引を精算に含めません（テストのバッチはデモ用です）。
ステータスと操作（マスター権限）
| ステータス | 意味 | 可能な操作 |
|---|---|---|
| 集計中 | 生成直後。明細を確認する段階 | 確定する / バッチを破棄 |
| 確定 | 金額が確定し、明細は変更不可 | 振込予定にする / 保留する |
| 振込予定 | 振込予定日に支払う予定 | 振込済にする / 保留する |
| 振込済 | 支払完了 | — |
| 保留 | チャージバック係争中などで支払を止めている（理由必須） | 保留を解除（確定に戻る） |
すべての操作は状態遷移表に従い、操作ログ（settlement.generate / confirm / schedule / pay / hold / release / delete）に記録されます。破棄できるのは集計中のバッチだけです。代理店手数料は 確定 / 振込予定 / 振込済 のバッチだけを対象にします（代理店手数料）。
詳細と明細 CSV
バッチ詳細には請求書番号、内訳（売上総額・手数料合計・返金合計・チャージバック合計・精算手数料・差引支払額）と、手数料合計の下に 税率別内訳（税抜 / 消費税額 / 税込と端数処理方式。請求書 PDF と同じ計算）、明細行（発生日時・種別・注文番号（取引詳細へのリンク）・決済手段・金額・手数料・税区分）を表示します。
請求書番号 は確定時に INV-YYYYMM-<加盟店番号>-<連番 2 桁>（年月は対象期間の開始日、連番は同じ加盟店の同じ月内で 01 から）で採番され、以後変わりません。一覧・詳細・請求書 PDF・加盟店管理画面・加盟店 API の応答（invoiceNo）に表示され、横断検索で番号から精算バッチを引けます。集計中のバッチには番号がありません。列追加前に確定したバッチは npm run db:backfill で採番します。明細 CSV（/api/settlements/<id>/lines?format=csv）で明細行を、一覧右下の CSV でバッチ一覧を出力できます。
加盟店側の参照（加盟店 API）
加盟店は自分の API キー（Authorization: Bearer wp_<test|live>_ak_…）で次を呼べます。キーのモード（テスト / 本番）と同じモードのバッチだけが返ります。
| リクエスト | 応答 data |
|---|---|
GET /api/merchant-api/settlements | { merchantCode, mode, settlements: [ { id, periodFrom, periodTo, status, grossAmount, feeAmount, refundAmount, chargebackAmount, settlementFee, netAmount, scheduledAt, paidAt, holdReason, createdAt } ] }（最新 100 件） |
GET /api/merchant-api/settlements?id=<バッチID> | { batch: 上記 1 件, lines: [ { kind, method, description, amount, fee, occurredAt } ] }。他社のバッチや別モードは 404 |
日時は ISO 8601 / UTC、金額は円の整数です。認証の詳細は 加盟店管理 の「加盟店 API リファレンス」を参照してください。