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

# 返金の記録、ID、通知、所要時間

> 返金が持つすべての識別子と、誰にどれを伝えるべきか、一部の返金で顧客の銀行口座と氏名が求められる理由、それらを誤って入力した場合の対処、返金 Webhook が発火するタイミングと配信先、返金が顧客に届くまでの一般的な所要時間、顧客自身が返金を開始できるかどうか。

返金が*許可される*かどうかは別のページで扱います。このページは返金の**記録**について、つまりその識別子、一部の返金で
求められる追加情報、結果がどのように通知されるか、そして待っている顧客に何を伝えるべきかを扱います。

| ページ | 用途 |
| - | - |
| [返金 FAQ](/docs/ja/support/refund-faq) | 基本ルール、異なる通貨間の金額、安全なリトライ |
| [決済手段別の返金制限](/docs/ja/support/payment-method-refund-limits-faq) | 何回、いくら、いつまで、決済手段ごとの違い |
| [返金の原資はどこから来るか](/docs/ja/support/refund-funding-source-faq) | 残高、資金不足、精算への影響 |
| [バッチ返金](/docs/ja/support/batch-refund-faq) | CSV のフローとバッチの追跡 |
| **このページ** | ID、受取人の追加フィールド、通知、所要時間、エクスポート |

## 返金はどの識別子を持ち、誰にどれを伝えますか？

返金は最大 6 つの識別子を持ちます。3 つは貴社が生成し、3 つは Waffo が生成します。

| フィールド | 生成者 | 識別対象 |
| - | - | - |
| `refundRequestId` | **貴社**（最大 32） | この返金**リクエスト**。冪等キーであり、同じ返金を安全にリトライするために再利用します |
| `merchantRefundOrderId` | **貴社**（最大 64） | 貴社自身の返金注文番号（帳簿用） |
| `acquiringRefundOrderId` | **Waffo** | 返金注文。**Waffo サポートに伝えるのはこれです** |
| `acquiringOrderId` | **Waffo** | 返金対象の**元の決済** |
| `origPaymentRequestId` | **貴社**（元の決済時） | 元の決済に対する貴社のリクエスト ID。返金を貴社自身の決済記録に紐づける方法 |
| Refund Batch ID | **Waffo** | バッチファイルから作成された返金にのみ存在します。[バッチ返金](/docs/ja/support/batch-refund-faq)を参照 |

使い分け：

* **Waffo サポートとのやり取り** → `acquiringRefundOrderId`。元の決済に関わる質問であれば `acquiringOrderId` も。
* **貴社自身の帳簿の照合** → `merchantRefundOrderId` と `origPaymentRequestId`。貴社のシステム内で意味を持つのは
  この 2 つだけです。
* **返金のリトライ** → `refundRequestId` をそのまま。新しい値を使うと新しい返金が作成されます。それがこのフィールドの
  趣旨です。
* **顧客とのやり取り** → 上記のいずれでもありません。顧客が自身の決済履歴で目にするのは*元の決済*の参照番号であり、
  それは元の注文の `payMethodResponse` 内の `payMethodRefId` として返ります。第三者に資金を指し示す必要がある場合、
  相手が認識するのはその参照番号です。
  [どの金額・通貨フィールドを確認すべきか](/docs/ja/support/order-amount-and-currency-fields-faq)を参照してください。

`merchantRefundOrderId` と `refundRequestId` はいずれも Portal → Transactions → Refunds の列として表示されるため、
API で起票した返金を貴社自身の番号で Portal から探すことができ、Portal で起票した返金を Waffo の番号で探すこともできます。

## 返金で顧客の銀行口座、氏名、国籍が求められるのはなぜですか？

一部の決済手段では、資金を来た経路に沿って単純に戻すことができず、返金が顧客への Payout として実行されるためです。
Payout には、決済では必要としなかった受取人の情報が必要になります。これは貴社のアカウントや個々の返金ではなく、
決済手段の属性です。

API では、これを返金リクエスト上の任意の `userInfo` オブジェクトとしてモデル化し、決済手段が必要とする場合に必須になります。

| グループ | フィールド |
| - | - |
| 銀行情報 | `userInfo.userBankInfo.bankAccountNo`、`bankCode`、`bankName`、`bankCity`、`bankBranch` |
| 本人情報 | `userInfo.userType`（`INDIVIDUAL` / `BUSINESS`）、`userFirstName`、`userMiddleName`、`userLastName`、`nationality` |
| 連絡先 | `userInfo.userEmail`、`userInfo.userPhone`（`+CountryCode-Number`） |
| 本人確認書類 | `userInfo.userIDType`、`userIDNumber`、`userIDIssueDate`、`userIDExpiryDate`（日付は `dd/mm/yyyy`） |

**値はどこから取得しますか？** 顧客からです。Waffo は顧客の銀行口座を保持しておらず、元の決済でも保持していませんでした。
だからこそこのフィールドが求められるのです。実務上は、これらの決済手段での返金はワンクリックの操作ではなく、
まず顧客に口座情報を確認する必要があるということです。Refund を押した時点で気付くのではなく、返品プロセスに
組み込んでください。

**どのフィールドが不足しているかは通知されるため、推測する必要はありません。** 両方の入口で同じように動作します。

* **Portal** では、返金ドロワーを開くとその注文に必要なフィールドが正確に求められます。銀行は固定の候補から選ぶ
  検索可能なリスト、国籍は国の一覧から選びます。氏名は 60 文字、その他のテキストフィールドは 64 文字が上限で、
  電話番号は決済の国の国番号に対して検証されます。任意なのはミドルネームのみです。
* **API** では、必須フィールドを欠いたまま送信された返金は、どのフィールドパスが不足しているかを返します。それらを
  収集して再送してください。2 回目でさらに多くが求められるのは正常です。すべてを先回りして埋めるのではなく、
  求められたものを提供して再送してください。

一般的な仕組みと、フィールドパスの表記法は
[決済手段別の条件付き必須フィールド](/docs/ja/support/conditional-required-fields-faq)にあります。

## 銀行口座を誤って入力して返金が失敗しました。その返金を修正できますか？

いいえ。返金記録は編集できず、失敗した返金に「修正して再送」というアクションはありません。**新しい
`refundRequestId`** で**新しい返金**を起票し、正しい情報を入力してください。

再送前に確認すべき 2 点：

* **返金可能な金額。** 失敗した試行がすべてを解放したと仮定するのではなく、返金レスポンスまたは返金照会の
  `remainingRefundAmount` を使用してください。これが正式な数値であり、その注文のすべての返金をすでに考慮しています。
* **情報そのもの。** 誤った受取人情報で失敗した返金は、同じ情報で再び失敗します。貴社の記録からではなく、顧客に
  口座を確認してください。

*同じ* `refundRequestId` の再利用も役に立ちません。これは冪等キーなので、再送すると新しい情報での新しい試行ではなく、
元の返金が返ってきます。冪等なリトライの動作は[返金 FAQ](/docs/ja/support/refund-faq)で扱っています。

## 顧客自身が返金を開始できますか？

**いいえ。** 返金は貴社が Portal または返金 API を通じて開始するものであり、顧客向けの経路はありません。Waffo の
チェックアウトに返金のアクションはなく、顧客がアクセスできるサブスクリプションのセルフ管理ページにもありません。
そこでサブスクリプションをキャンセルすると将来の請求が止まりますが、過去の請求が取り消されるわけではありません。

返金記録の `refundSource` も同じことをフィールドの形で示しています。4 つの値は次のとおりです。

| `refundSource` | 意味 |
| - | - |
| `MERCHANT` | 貴社が開始した |
| `RDR` | チャージバックアラートサービスによって自動的に起票された |
| `ETHOCA` | チャージバックアラートサービスによって自動的に起票された |
| `CDRN` | チャージバックアラートサービスによって自動的に起票された |

顧客を表す値はありません。顧客の経路が存在しないからです。顧客が*できる*のは自身の銀行に異議を申し立てることで、
これは資金も期限も異なる別の仕組みです。[チャージバック FAQ](/docs/ja/support/chargeback-faq)を参照してください。

プロダクト上の実務的な帰結：セルフサービスの返品を提供したい場合は、リクエストのフローを貴社側で構築し、承認した
時点で返金 API を呼び出してください。顧客を誘導できる Waffo の顧客向け画面を待たないでください。

## すでに自分で顧客に返金しました。返金 API を呼ぶと二重に支払われますか？

はい。Waffo を通じた返金は実際の資金の移動であり、Waffo はプラットフォーム外で顧客と精算した内容（貴社自身が行った
銀行振込、ストアクレジット、店頭での現金返金）を一切把握していません。両者を照合する仕組みはないため、プラットフォーム外の
返金の後に返金を呼び出すと、顧客に 2 回目の支払いが行われます。

安全策は、Waffo が代行できるチェックではなく、返金記録そのものです。

* **返金前に注文の返金履歴を確認してください。** Portal または返金照会で確認し、`remainingRefundAmount` を読んでください。
  貴社が起票していない返金も含めて、Waffo がすでに送金した内容が分かります。
* **プラットフォーム外の精算を貴社自身のシステムに記録し**、返金アクションをそれで制御してください。その情報が存在するのは
  そこだけです。
* 決済手段が許す場合は、**Waffo 経由での返金を優先してください**。まさに返金が決済と同じ記録に収まるようにするためです。

同じ理屈は逆にも当てはまります。Waffo がすでに返金した注文について貴社が改めて動く必要はなく、プラットフォーム外で
再度顧客に支払うのは鏡写しの誤りです。

## Portal から一部の金額だけ返金できますか？

はい。Portal の返金ドロワーは返金可能な全額が入力された状態で開き、金額フィールドは編集可能です。注文の通貨で、
その通貨の小数精度の範囲内で、**ゼロより大きく**決済金額**以下**の任意の金額を入力できます。理由の入力が必須であり、
返金が作成される前にダイアログで正確な金額を確認します。

同じ注文で*2 回目*の一部返金が可能かどうかは、Portal ではなく決済手段の問題です。一部返金を 1 回のみ許可し、
それ以上は認めない決済手段もあります。段階的な返金を計画する前に
[決済手段別の返金制限](/docs/ja/support/payment-method-refund-limits-faq)を参照してください。また、Portal から返金する
ステーブルコインの注文には、元のチェーン上の受取アドレスが追加で必要です。

## 返金記録に `RDR`、`ETHOCA`、`CDRN` と表示されています。その注文をまだ返金できますか？

その注文は、アラートサービスが予見した異議申し立てを未然に防ぐため、すでに自動的に返金されています。したがって：

* **その注文に対してこれ以上の返金はできません。** チャージバックアラートサービスが起票した失敗以外の返金が
  注文に付いた時点で、それ以降のすべての返金試行は専用のエラー `A0039 Order has already been refunded by
  chargeback alert service` で拒否されます。**金額にかかわらず**です。このチェックは自動返金が決済全額をカバーしたか
  どうかを見ないため、そのような注文で `remainingRefundAmount` がゼロより大きくても、残りを API や Portal から
  返金できるわけではありません。顧客にまだ支払うべき金額があると考える場合は、サポートの案件になります。
* 自動返金が行われなかったと仮定して、**Waffo の外で顧客に再度返金しないでください。** まず返金記録を読んでください。
  `refundSource` はそのためにあります。

異議申し立てが進行中の注文は、別途、独自のエラー（`A0019`）で返金がブロックされます。この区別は重要です。`A0039` は
*すでに返金済み*、`A0019` は*異議申し立ての進行中はロック*を意味します。いずれもそのままではリトライできません。

## 返金 Webhook はいつ発火し、どこに送られますか？

返金が**最終**状態、つまり完了または失敗に達したときに発火します。中間の「返金を受理」という Webhook はないため、
`REFUND_IN_PROGRESS` の通知は届きません。

配信先：

| 状況 | 配信先 |
| - | - |
| 返金リクエストで `refundNotifyUrl` を送信した | その URL |
| 送信していないが、アカウントに返金通知 URL が設定されている | 設定された URL |
| どちらもない | Webhook なし。`/api/v1/refund/inquiry` で結果を取得してください |
| バッチファイルから作成された返金 | 設定されたアカウントの URL — バッチの行に行ごとの URL はありません |

イベントタイプは `REFUND_NOTIFICATION` で、ボディは返金照会のレスポンスと同じ構造なので、1 つのパーサーで両方に
対応できます。これは意図的です。返金照会を読める連携は Webhook も読めるため、ポーリングは 2 つ目の実装ではなく
正当なフォールバックになります。

運用上の注意が 2 点。`refundNotifyUrl` の上限は 256 文字で、決済の `notifyUrl` より短いです。また、決済の Webhook と
同じ配信ルールが適用されます。標準ポート上の到達可能な HTTPS であることと、期待される成功レスポンスのボディです。
配信のトラブルシューティングは
[Webhook リトライ](/docs/ja/developer-docs/webhook/retry)と
[Portal の Webhook ログ](/docs/ja/support/portal-webhook-log-faq)にあります。

## Webhook を待たずにポーリングで返金結果を取得できますか？

はい。`/api/v1/refund/inquiry` は返金の現在の状態を返し、通知 URL を設定していない場合、署名検証に失敗した場合、
あるいは単に今すぐ答えが欲しい場合の、文書化されたフォールバックです。`refundStatus`、失敗時の `refundFailedReason`、
`refundCompletedAt`、`remainingRefundAmount`、および識別子一式を返します。

決済についても同じで、Order Inquiry は結果を取得する正規の方法であり、回避策ではありません。ポーリングが解消しないのは、
Webhook を処理する必要そのものです。Webhook の経路を構築し、照会は隙間を埋めることと、サポートチームからの
「今どうなっているか」という質問に答えることに使ってください。

## 返金が顧客に届くまでどのくらいかかりますか？

顧客の支払い方法によって異なり、正直なところ幅があります。Waffo の担当部分、すなわち返金を最終状態に移すことは
`refundStatus` が報告しますが、最後の区間は顧客の銀行、カードイシュア、ウォレット事業者の手にあり、Waffo はその
到着日を約束しません。Portal のサポート画面には決済手段ごとの目安処理時間が表示されます。顧客と話すときはそれを
基準にしてください。数値は変わっても、答えの形は安定しています。

| 顧客の支払い方法 | 想定 |
| - | - |
| クレジットカードまたはデビットカード | 最も遅い経路 — 返金はイシュアが定める明細サイクルに載り、誰にも予測できる日ではありません |
| オンラインバンキングまたは銀行振込 | 時間単位ではなく営業日単位。銀行と国によって異なります |
| ウォレット — ウォレット残高への返金 | 通常は速く、多くは同日中 |
| ウォレット — それ以外の方法での返金 | 営業日単位。ウォレットや銀行によって異なります |
| 手動振込、ATM、現金入金 | 営業日単位。銀行と国の影響を受けます |

顧客対応での使い方：

* **返金が進行中と表示されている間**は、返金が進んでいると伝えてください。エスカレーションすべきものはありません。
* **返金が完了と表示され**、その決済手段の目安期間を過ぎても資金が届かない場合は、報告する価値があります。
  `acquiringRefundOrderId` を添えてください。
* **日付を約束しないでください。** 特にカードの返金は、予測できる日ではなく明細サイクルに載ります。

そもそもその決済手段で返金が*できる*かどうか、および決済手段ごとの返金期限は別の問題です。
[決済手段別の返金制限](/docs/ja/support/payment-method-refund-limits-faq)を参照してください。

## 返金では、顧客が支払った手数料や税も返りますか？

必ずしも返りません。API はこの点を明示しています。返金において、*顧客が受け取る金額*である `finalDealAmount` は、
顧客が当初支払ったサービス手数料や税を**除外する**ことがあり、そのため対応する注文金額より小さくなりえます。

したがって、顧客とやり取りする際には区別すべき 2 つの金額があります。

| フィールド | 内容 |
| - | - |
| `refundAmount` | 注文通貨で、返金を依頼した金額 |
| `finalDealAmount` | 顧客が実際に受け取る金額 |

顧客には後者を伝えてください。手数料込みで顧客を元の状態に戻すのが貴社のポリシーであれば、その分は貴社自身で
価格に織り込む必要があります。注文金額の返金が自動的に手数料を戻すわけではありません。

元の決済で**貴社**が支払った手数料や、マーチャント負担の税がどうなるかは、返金記録ではなく精算の問題です。
[返金 FAQ](/docs/ja/support/refund-faq)と
[手数料と税の取り扱い](/docs/ja/support/fee-and-tax-treatment-faq)を参照してください。

## 返金理由は何文字まで書けますか？ 顧客に表示されますか？

`refundReason` はすべての返金で**必須**です。上限は起票する場所によって異なります。API は最大 **256** 文字を受け付け、
Portal の返金フォームは文字数カウンターとともに **128** 文字でフィールドを制限します。

これは内部向けの注記です。返金記録に保持され、Portal に表示され、返金照会で返ってきます。半年後に貴社のサポートチームが
読むものです。顧客へのメッセージとしてではなく、その読み手に向けて書いてください。注文の参照番号、返品チケット番号、
簡潔な理由などです。

## 返金はどこで確認でき、何をエクスポートできますか？

Portal → Transactions → **Refunds** が一覧です。その列は識別子一式と各返金の状態をカバーします。

| グループ | 列 |
| - | - |
| 識別子 | 返金注文 ID、元の注文 ID、貴社の返金注文 ID、貴社の元の注文 ID、返金リクエスト ID、Refund Batch ID、使用している場合はサブマーチャント ID |
| 金額 | 返金金額と通貨 |
| 決済手段 | 決済手段、タイプと国、マスクされたカード番号 |
| 状態 | 返金ステータス、精算ステータス |
| 時刻 | 作成日時、元の決済日時 |
| 関連 | 関連するサブスクリプション ID、貴社のユーザー ID |

一覧は返金の識別子、ステータス、通貨、Refund Batch ID、作成日時でフィルターでき、エクスポートも可能です。
エクスポートはバックグラウンドタスクとして実行され、独自の期間・サイズ制限と独自のステータス一覧を持ちます。
エクスポートが成功しつつ失敗件数がゼロでない場合も含め、すべて
[エクスポートセンター](/docs/ja/support/export-center-faq)にあります。取引と返金のエクスポートがどの列を持つかは
[決済手段の設定と制限](/docs/ja/support/payment-method-config-and-limits-faq)にあります。

API で起票した返金が一覧にない場合は、失われたと結論する前に、貴社自身の `refundRequestId` または
`merchantRefundOrderId` で検索してください。これらは列であり、返金は貴社自身の番号で見つけられます。

## 返金は成功と表示されているのに、顧客は資金が届いていないと言っています

同じ苦情を生む状況が 3 つあるため、次の順序で確認してください。

1. **その決済手段の目安期間を確認してください**（Portal のサポート画面に表示されます）。次の明細サイクルにまだ
   達していないカードの返金は遅延ではありません。
2. **`refundAmount` ではなく `finalDealAmount` を確認してください。** 手数料が返らなかった場合、顧客は想定より
   少ない金額を受け取っており、それを「届いていない」と受け取ることがあります。
3. **資金がどこに送られたかを確認してください。** ウォレット残高に返金される決済手段では、その背後のカードではなく
   ウォレットに入ります。カードの明細を見ている顧客には見えません。

3 つとも問題なく、それでも資金が見つからない場合はサポートの案件です。`acquiringRefundOrderId` と日付を送ってください。
成功と報告されながら下流で失敗する返金、および `ORDER_REFUND_FAILED` で終わる返金は
[決済手段別の返金制限](/docs/ja/support/payment-method-refund-limits-faq)で扱っています。

ステーブルコイン決済の返金には独自の必須フィールド（同じチェーン上の受取アドレス）と、ネットワーク手数料を誰が
負担するかについての独自のルールがあります。これらは
[ステーブルコインの例外](/docs/ja/support/stablecoin-exceptions-faq)にあります。

***

返金の追跡が必要ですか？ `acquiringRefundOrderId` を添えて
[サポートにお問い合わせください](mailto:support@waffo.com)。


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