> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 一括返金

> Portal の Batch Refunds タブについて：テンプレートの列と上限、アップロード時にどの検証がどの順序で行われるか、重複ファイルと「同時に 1 バッチのみ」のルール、バッチのステータス、行ごとの失敗理由がどこで確認できるか。

Batch Refunds は Portal の **Transactions** モジュールのタブのひとつで、Payments、Refunds、Reports と並んでおり、
Portal 内で返金を*開始*できる唯一の場所です。ファイルの各行は通常の返金レコードになるため、前提条件、一部返金、
クロスカレンシーの金額、手数料の返還については [返金 FAQ](/docs/ja/support/refund-faq) に記載のとおりに動作します。

このタブはアカウント単位で有効化されます。お使いの Portal に表示されていない場合は、まだ有効化されていません。タブ内では、
**Export Batch Refund Template** と **Upload Batch Refund File** に一括返金アップロード権限が必要ですが、
一覧・フィルター・**Export** はタブを開けるロールであれば誰でも利用できます。ボタンが見えていれば、使用できます。

## 一括返金の流れは、最初から最後までどのようになっていますか？

| ステップ | Portal での操作 | 起きること |
| - | - | - |
| 1. テンプレートのダウンロード | **Export Batch Refund Template** | サンプル行 1 行を含む 4 列の CSV、`Batch_Refund_Template.csv` |
| 2. アップロード | **Upload Batch Refund File** | ファイル全体が検証されます。この時点では何も作成されません |
| 3. プレビュー | 確認ダイアログ | レコード件数、合計金額、通貨が表示されます |
| 4. 確認 | ダイアログ内の **Confirm** | 各行が再検証され、その後バッチと返金が作成されます |
| 5. 追跡 | バッチ一覧のフィルターと **Export** | バッチ一覧を絞り込み、エクスポートします |

この流れ全体はブラウザーセッション内で行われる Portal の機能であり、API キー署名の連携 API にはバッチ用エンドポイントはありません。
システム連携の場合は、単件の返金 API を使用してください。確認すると、`BRP` + MID + `YYYYMMDD` + 6 桁の日次連番という形式の
**Refund Batch ID** が生成されます。例：`BRP<your merchant ID>20260225000001`。バッチの **Batch Name** はアップロードした
ファイル名になるため、後から見分けられる名前を付けてください。

## ファイルはどのような形式にする必要がありますか？

| テンプレートの列 | 必須 | 補足 |
| - | - | - |
| `Original Order Id` | はい | 返金対象の決済に対応する Waffo アクワイアリング注文 ID |
| `Refund Amount` | はい | 0 より大きく、その通貨の小数精度の範囲内 |
| `Refund Currency` | はい | 3 文字コード。すべての行で同一で、注文の通貨と一致すること |
| `Refund Reason` | いいえ | 自由記述。返金レコードに引き継がれます |

ハード上限：`.csv` のみ、最大 **2 MB**、最大 **2,000 件**、空でなく解析可能であること。Portal はアップロード前に拡張子とサイズを確認し、
サーバー側でも両方を再確認します。つまずきやすい点が 2 つあります。**サンプル行を削除すること**（テンプレートの例の注文 ID を含む行は、
他のどの検証よりも先に、それ単体で拒否されます）と、**1 ファイルにつき 1 通貨**であることです。

## なぜファイル全体が拒否されたのですか？

アップロード時の検証はオール・オア・ナッシングです。何も作成されず、Portal は問題のある行を*行、フィールド、メッセージ*の形式で一覧表示します。
検証は固定の順序で実行されるため、一度に 1 つのカテゴリーしか表示されないことがよくあります。

1. ファイルレベルの検証 — 形式、サイズ、空かどうか、重複コンテンツ、処理中のバッチの有無。
2. サンプル行の検証。これに該当した場合、返されるエラーはこれのみです。
3. 行ごとの検証 — 注文が自社の MID 配下に存在すること、ファイル内に注文の重複がないこと、金額 > 0、通貨が有効であること、
   すべての行で一貫していること、注文の通貨と一致すること。
4. 行ごとの単件返金の前提条件 — 注文が支払済みかつ返金可能であること、進行中の返金がないこと、返金期間内であること、
   金額が返金可能残額の範囲内であること、異議申し立てによるロックがないこと（それぞれ [返金 FAQ](/docs/ja/support/refund-faq) で説明しています）。
5. バッチの残高検証。**すべての行が通過した場合のみ**実行されます。ファイルの合計額が、単件返金で使用されるのと同じ返金資金源で
   賄える必要があります。賄えない場合、行番号のないバッチレベルのエラーが 1 件返されます（"Insufficient
   merchant refund account capacity for batch refund"）。

ステーブルコインの注文（USDT、USDC）はバッチに含められません。これらには返金先アドレスが必要ですが、テンプレートにはその列がありません。
個別に返金してください。

## なぜアップロードできないのですか — 重複ファイル、または処理中のバッチとは？

重複検出はファイルの**内容**に対して行われ、名前ではなく、自社の MID の範囲内で判定されます。以前のアップロードがまだ確認待ちの状態で
同じ内容を再アップロードすると、その保留中のアップロードがそのまま返されるため、確認ダイアログを再度開くことができます。
その内容からバッチが一度作成されると、その内容は永続的に拒否されます。失敗した行を再試行するには新しいファイルを作成してください。
理由テキストであっても、何かを変更すれば新しいファイルとして扱われます。また、検証済みのアップロードを放置すると期限切れになります。
後から確認すると *File token is invalid or expired* で失敗するため、再度アップロードしてください。

これとは別に、**いずれかのバッチのいずれかの返金がまだ処理中**の間は、アップロードと確認の両方が拒否されます（"You
have a batch refund in progress. Please wait for it to complete."）。そのため、大量に実行する場合はファイルを順番に処理する計画を立ててください。
API 経由の単件返金はこの制限を受けません。また、確認時にすべての行が再検証されるため、確認ダイアログを開いたまま状況が変化した場合
（別の場所で注文が返金された、返金期間が終了した、残高が変動した）、部分的に無効なバッチが作成されるのではなく、
最初に問題となった行のメッセージで確認が失敗します。

## バッチのステータスはそれぞれ何を意味しますか？

| ステータス | 意味 |
| - | - |
| `INIT` | 一時的な状態 — バッチレコード作成時に設定され、直後に再計算されます。ほとんど表示されず、ステータスフィルターにも含まれません |
| `PROCESSING` | 少なくとも 1 行が保留中または処理中 |
| `PARTIAL_SUCCESS` | すべての行が完了。成功した行と失敗した行がある |
| `FULL_SUCCESS` | すべての行が成功 |
| `FAILED` | すべての行が失敗 |

ステータスは個別に管理されるのではなく行の件数から導出されるため、各行が確定するにつれて自動的に変化します。
**Total / Success / Failed / Processing Count** はバッチごとに表示されます。Failed Count には送信時の検証で失敗した行が含まれ、
Processing Count には未着手の行が含まれます。1 行の不備でバッチ全体が止まることはありません。行は独立して処理され、それが `PARTIAL_SUCCESS` の
意味です。また、バッチには再試行の操作はありません。失敗した行を新しいファイルにまとめるか、1 件ずつ返金してください。

## どの行がなぜ失敗したかは、どこで確認できますか？

バッチの **Detail** をクリックしてください。その Refund Batch ID であらかじめ絞り込まれた **Refunds** タブが、バッチページの日付範囲を
引き継いで開きます。各返金は通常のレコードであり、その詳細ページには Refund Batch ID と、ステータスが *Refund Failed* の場合は失敗理由が
表示されます。Refunds タブには Refund Batch ID の列とフィルターもあるため、同じビューに直接アクセスすることもできます。

バッチ一覧のエクスポート（`Batch_Refunds_<timestamp>.csv`）は**バッチレベルのサマリー**です。ID、名前、金額、通貨、ステータス、
4 つの件数、操作者、作成日時と更新日時が含まれ、行ごとの失敗理由は**含まれません**。ファイル内の時刻はブラウザーが報告する UTC オフセットを使用します。
一覧自体は Refund Batch ID、ステータス、通貨、作成日時で絞り込め、初期表示は過去 3 か月です。まれに、返金レコードが作成されないほど
早い段階で行が失敗することがあります。その場合も Failed Count には計上されますが、Refunds タブで開くものはありません。
こうした行については、Refund Batch ID を添えてサポートにお問い合わせください。

## 単件の返金 API とはどのような関係ですか？

エンジンは同じで、入口が異なるだけです。ライフサイクル、アカウント選択、精算上の扱いは同一です。実務上の違いは 2 つあります。
**返金リクエスト ID** — バッチの行にはシステムが生成した、お客様には見えない ID が付与されます。そのため、自社の参照番号ではなく、
Refund Batch ID または Portal 上の返金注文 ID で追跡してください。**通知** — バッチの行には行ごとの通知 URL がないため、
返金通知はアカウントに設定されたデフォルトの返金通知 URL に送信されます。設定がない場合、バッチの行は Webhook を送信せず、
Portal が唯一の確認手段になります。

***

何度も失敗するファイルがありますか？ そのファイルと、作成されていれば Refund Batch ID を添えて[サポートにお問い合わせください](mailto:support@waffo.com)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.