> ## 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.

# 返金 FAQ

> Waffo の返金に関する最もよくある質問への回答：複数回の一部返金、返金の前提条件、べき等なリトライ、異通貨の金額と端数処理、返金とキャンセルの違い、処理時間、決済手段の制約。

このページでは、返金について加盟店から最もよく寄せられる質問に回答します。項目レベルの仕様は
Acquiring API 仕様（`/api/v1/order/refund`、`/api/v1/refund/inquiry`、返金注文の通知）にあります。

## 同じ注文を複数回返金できますか？

決済手段と契約の設定によって異なります。

* **複数回の一部返金に対応している場合** — 各返金は *返金済み + 処理中 + 今回のリクエスト ≤ 元の決済金額* となるよう検証されます。
  1 つの注文につき本番環境では最大 **50 回**の返金が可能で、これを超えるとエラー `A0027` が返ります。サンドボックスおよびテスト環境では
  上限がより低いため、数回の返金で `A0027` に到達するのは想定どおりであり、バグではありません。すべての返金レスポンスには
  `remainingRefundAmount` が含まれるため、まだ返金可能な額を追跡できます。
* **対応していない場合** — その注文について 1 回の返金が完了すると、それ以降の返金リクエストは拒否されます。

一部返金が成功するたびに、注文の**返金ステータス**（`refundStatus`）は `ORDER_PARTIALLY_REFUNDED` になります。
成功した返金の合計額が注文金額に等しくなって初めて `ORDER_FULLY_REFUNDED` になります。注文の `orderStatus` 自体は返金によって
変更**されません** — 全額返金された注文も引き続き `PAY_SUCCESS` を返します。

## 返金が拒否されたのはなぜですか？

返金リクエストは以下の前提条件をすべて満たす必要があります。

| 前提条件 | 詳細 |
| - | - |
| 注文ステータス | 元の決済が成功している必要があります。 |
| 契約が返金に対応している | 返金の可否は契約の設定です。返金不可の契約に対するリクエストは失敗します（例：`A0014`）。 |
| 返金の有効期間 | 返金は、**注文の作成日**（決済成功時点ではありません）から起算した契約で定められた期間内でのみ受け付けられ、最終日の終わりで終了します。注文照会レスポンスの `refundExpiryAt` を確認してください — 返金が許可されていない場合は `null` です。 |
| 十分な資金 | Waffo はまず精算待ち残高（与信枠を含む利用可能残高）から返金を引き当てます。それで足りない場合は返金備用金アカウントにフォールバックします。どちらでも金額をカバーできない場合にのみ、リクエストは `A0012` で拒否されます。 |
| 未解決の異議申し立てがない | チャージバックの異議申し立て中の注文は返金がロックされます（`A0019`）。チャージバックアラートサービスによってすでに返金された注文は `A0039` を返します。 |

有効期間と複数回返金への対応は契約依存です — 正確な設定は加盟店 Portal で契約を確認するか、インテグレーションサポートに
お問い合わせください。

## 返金リクエストがタイムアウトしました。安全に再送できますか？

はい。`refundRequestId` がべき等キーです。

* **同じ ID と同じ金額**で再送すると、現在の返金ステータスが返されます。返金がまだ中間状態にある場合は、処理が前に進められます。
* **同じ ID で異なる金額**を再送すると、拒否されます。

安全にリトライするには、常に同一のリクエストを再送してください。新しい `refundRequestId` は、追加の返金を作成する意図がある
場合にのみ使用してください。

## 異通貨の返金金額はどう計算されますか？

ユーザーが注文通貨と異なる通貨で支払った場合、送信した返金金額（注文通貨）はユーザーの通貨に換算されます。2 つのルールが適用されます。

* **切り捨て** — 換算後の返金額は常に切り捨てられるため、返金合計がユーザーが実際に支払った額を超えることはありません。
* **最後の返金が差額を補う** — 複数回の一部返金では、為替の端数処理により返金合計が決済金額をわずかに下回ることがあります。
  残額を使い切る最後の返金では残り全額が返金されるため、全額返金された注文は確実に `ORDER_FULLY_REFUNDED` に到達します。

返金照会レスポンスの `finalDealAmount` が、ユーザーが自分の通貨で実際に受け取る金額です。

## 注文をキャンセルしましたが、ユーザーはすでに支払ったと言っています

キャンセルは、まだ中間状態にある注文に対してのみ機能します。ユーザーが実際に決済を完了していた場合、キャンセルリクエストは
失敗し、注文は決済成功として進行します — 決済成功の通知を受け取ります。その時点で資金を返すには返金 API を使ってください。
キャンセルをリトライしないでください。

## 返金にはどれくらいかかりますか？ステータスが処理中のままです

返金は**非同期**です。`/api/v1/order/refund` の呼び出しが成功したということは、リクエストが*受理された*
（`REFUND_IN_PROGRESS`）という意味であり、完了したという意味ではありません。その後 Waffo が決済手段と返金処理を行い、
回復可能な失敗は最終状態に到達するまで自動的にリトライします。

* `refundNotifyUrl` を指定して返金注文の通知で最終結果を受け取るか、`/api/v1/refund/inquiry` をポーリングしてください。
* 返金が確定するのは `ORDER_PARTIALLY_REFUNDED`、`ORDER_FULLY_REFUNDED`、`ORDER_REFUND_FAILED` のいずれかになったときだけです —
  `REFUND_IN_PROGRESS` は失敗ではなく保留として扱ってください。

## すべての決済手段が API 返金に対応していますか？

いいえ。2 つの異なるケースがあります。

**返金が許可されていない場合。** 2 つのコードに 2 つの意味があります。`A0017`（「payment channel not supported」）は、
決済手段そのものが返金を実行できない — 全額でも一部でも — ことを意味します。`A0014`（「refund rules」）は、その決済手段は
返金できるが、契約上の返金の形が*この*リクエストを許可していないことを意味します：全額返金のみの行に対する一部返金や、
1 回しか許可されていないところでの 2 回目の返金です。残りの返金可能額を超える請求はさらに別で、単なる `A0003` のパラメーター失敗です。
[決済手段ごとの返金上限](/docs/ja/support/payment-method-refund-limits-faq) を参照してください。

**追加項目が必要な返金。** 一部の返金では、銀行口座情報などの追加のユーザー情報が必要です。元の決済を取り消すのではなく、
振込で資金を返すためです。**どの項目が必要かはチャネルごとに設定されるため、自社のコード内で決済手段から判断しないでください。**
まず返金を送信してください。項目が不足している場合、API は不足している項目名の一覧とともに `A0003` を返すので、
それらの項目を埋めて再送します。

一部の決済手段では、返金は Waffo 側で送金レールを通じて実行されます — お客様の API 契約は変わりません。

## 一度に多数の返金を送信できますか？

はい — Portal の Transaction モジュール配下の **Batch Refunds** ページです。加盟店アカウントごとに有効化されるため、
ページが見当たらない場合は有効になっていません。サポートにお問い合わせください。テンプレートとアップロードのボタンは、
すでに単一の返金を開始できるロールにのみ表示されます。

フローは次のとおりです：一括返金テンプレート（CSV）をエクスポートし、記入し、アップロードし、サマリーダイアログ
（レコード件数、合計金額、通貨）を確認すると、Waffo が `BRP` + MID + `YYYYMMDD` + 6 桁の連番という形式の
**Refund Batch ID** を作成します — 例：`BRP<your merchant ID>20260225000001`。

| テンプレートの列 | 必須 |
| - | - |
| Original Order Id | はい |
| Refund Amount | はい |
| Refund Currency | はい |
| Refund Reason | いいえ |

## バッチファイル全体が拒否されました。なぜですか？

アップロードの検証はオール・オア・ナッシングです：1 行でも不正があるとファイル全体が拒否されるので、修正して再度アップロードします。
チェックされる内容：

* **ファイル** — エクスポートしたテンプレートの CSV であること。ちょうどその 4 列で、余分な列がないこと。破損・暗号化・空でないこと。
  最大 **2,000 レコード**かつ **2 MB** であること。以前にアップロード済みのファイルでないこと（重複はファイル名ではなく内容から検出されます）。
* **通貨** — ファイル全体で 1 つの返金通貨であり、各元注文の通貨と一致していること。
* **各行** — 元の注文が存在し、支払い済みでまだ全額返金されておらず、その決済手段が返金を許可し、返金期間内であり、
  金額がゼロより大きく残りの返金可能額以下であり、その注文に処理中の返金がないこと。
* **重複** — 同じ注文が 1 つのバッチ内に 2 回現れないこと。
* **バッチ合計** — ファイルの合計が、アップロード時点の精算待ち残高と返金備用金残高の合計でカバーされること。

行ごとのルールは、単一の返金が満たす前提条件と同じです。各項目の意味については上記の「返金が拒否されたのはなぜですか？」を参照してください。

## 送信後にバッチを追跡するにはどうすればよいですか？

各行は独立して処理されます：失敗した行には理由が記録され、残りは処理が続きます — 1 つの失敗でバッチが止まることはありません。

| バッチステータス | 意味 |
| - | - |
| `INIT` | バッチが作成され、処理は未開始 |
| `PROCESSING` | 少なくとも 1 行がまだ処理中 |
| `PARTIAL_SUCCESS` | 一部の行が成功し、一部が失敗 |
| `FULL_SUCCESS` | すべての行が成功 |
| `FAILED` | すべての行が失敗 |

バッチ一覧には、合計 / 成功 / 失敗 / 処理中の件数、バッチの金額と通貨、作成日時と更新日時が表示されます。すべての返金には
Refund Batch ID が付くため、返金一覧をバッチで絞り込み、個々の返金の詳細を通常どおり開き、失敗理由を含むバッチ結果を
エクスポートできます。バッチにリトライの操作はありません — 失敗した行を新しいファイルで再送するか、1 件ずつ返金してください。

## 一部返金では、元の決済手数料は戻ってきますか？

デフォルトは**手数料の返還なしの返金**です。契約に手数料の返還が含まれている場合、返金では元の決済手数料の対応する割合が
返還され、小数点以下 2 桁に**切り捨て**られます。

```
Returned fee = ROUNDDOWN2( refund amount / original order amount × original fee amount )
```

一部返金では按分した割合が、全額返金では全額が返還されます。ルールが切り捨てであるため、返還される手数料は単純な按分計算で
得られる数値より 1 セント低くなることがあります。これは返金行の Settlement Amount のプラスの構成要素として現れます —
[精算レポートとエクスポート](/docs/ja/support/settlement-reports-faq) を参照してください。


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