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

# Payout のステータス、通知、レポート

> 各 Payout のステータスとサブステータスの意味、DEDUCTED が届かない理由、Payout の Webhook が発火するタイミングとまったく発火しない 2 つのケース、返戻の検知方法、日次・週次・月次の Payout レポートの内容と公開タイミング。

このページでは、Payout を作成した後にそれを読み取ること、つまりステータス、完了をどう知るか、定期レポートがどこに
あるかを扱います。作成方法は [Payout FAQ](/docs/ja/support/payout-faq) に、リクエストのフィールドは
[Payout リクエストフィールドガイド](/docs/ja/support/payout-request-field-guide)に、バッチ Payout の独自のステータスは
[バッチ Payout のステータスと資金手当て](/docs/ja/support/batch-payout-faq)にあります。

## Payout の作成は同期ですか、非同期ですか？

実務上はすべて非同期です。作成が成功すると `status: IN_PROGRESS` の注文と Waffo の `payoutOrderId` が返り、結果は
後から届きます。結果を知る方法はちょうど 3 つあり、そのうち少なくとも 2 つを前提に構築すべきです。

| 経路 | 用途 |
| - | - |
| **`/api/v1/payout/inquiry`** | いつでも `payoutRequestId` または `payoutOrderId` で取得できる、正式な現在の状態 |
| **Payout の Webhook** | ポーリングなしで速やかに通知を受ける — 下記の制限を参照 |
| **Portal** | 1 件の注文を手作業で調査する |

作成がすでに最終状態で返ることもあります。元の注文が完了している `payoutRequestId` を同一内容で再送すると、その
最終ステータスが直ちに返り、事前チェックの段階で失敗した Payout は同期的に失敗します。作成レスポンスの `SUCCESS` と
`FAILURE` は本物として扱ってください。

## Payout にはどのようなステータスがあり、どれが最終ですか？

| `status` | 意味 | 最終か |
| - | - | - |
| `IN_PROGRESS` | 処理中 | いいえ |
| `SUCCESS` | Payout が成功した | はい |
| `FAILURE` | Payout が失敗した — `failureCode` と `failureReason` を確認 | はい |

3 つの値があり、最終なのはそのうち 2 つだけです。API には「submitted」「deducted」「accounting」といった別の値は
ありません。

## Portal と API でステータスが違います。どちらが正しいですか？

両者は一致しています。Portal の Payout 一覧と詳細は API が返す**同じ 3 つの値**を表示し、一覧のフィルターも同じ 3 つを
提供します。Waffo は Payout が進行する間により細かい内部ステージを追跡していますが、そのすべては `IN_PROGRESS` として
報告され、どちらの画面にも表示されません。本当に両者が異なる場合は、どちらかが古い情報です。再照会し、照会レスポンスを
正式なものとして扱ってください。

## どこかで `DEDUCTED` を見ました。資金はもう出ていったのですか？

`DEDUCTED` は内部ステージ名であり、受け取ることのできる Payout のステータスではありません。`IN_PROGRESS` の中の位置の
1 つです。これは資金が貴社の精算口座から引き落とされ、Payout Wallet に移されたことを意味し、受取人に支払われたことを
意味するもの**ではありません**。資金はその時点から Payout が最終ステータスに達するまで *In Transit* としてウォレットに
留まります。そのため、残高上は引き落とし済みと表示されている Payout が後から失敗し、金額が戻ることがあります。
その仕組みは [Payout Wallet と対応範囲](/docs/ja/support/payout-wallet-and-coverage-faq)に記載されています。

## `subStatus` とは何ですか？ `CONSULT_SUCCESS` と `CONSULT_FAILURE` は？

`subStatus` は返戻が発生した場合に**のみ**存在し、常に次の 2 つの値のいずれかのみを持ちます。

| `subStatus` | 意味 |
| - | - |
| `FULL_REVERSED` | Payout 金額の全額が返戻された |
| `PARTIAL_REVERSED` | Payout 金額の一部が返戻された |

`CONSULT_SUCCESS` と `CONSULT_FAILURE` は事前チェックステップの内部マーカーであり、**レスポンスが組み立てられる前に
除外されます**。API が返す `subStatus` は返戻の 2 つの値のみなので、これらを受け取ることはありません。目にしたことが
あるなら、それは Payout API 以外のどこかから来たものであり、対処すべき意味は持ちません。

## Payout が成功しました。それでも返戻されることがありますか？

はい。受取側は、すでに `SUCCESS` に達した Payout を返戻することがあります。その場合：

* `status` は `SUCCESS` の**まま**です。失敗や返戻のステータスに移ることはありません。
* `subStatus` が `FULL_REVERSED` または `PARTIAL_REVERSED` になります。
* 返戻された金額は、その Payout の資金元であるアカウント、つまり貴社の精算口座に、資金手当ての通貨で戻されます。
  一部返戻では返戻された部分のみが戻るため、元の Payout 金額ではなく返戻を基準に照合してください。

**返戻では Webhook は送信されません。** Payout が返戻されても、いかなる通知もプッシュされません。知る方法は、
注文を再照会するか、返戻が独自の 2 行を記帳する Payout Wallet の取引履歴を見ることだけです。返戻が貴社の台帳にとって
重要なら、`SUCCESS` を注文の終わりとして扱うのではなく、成功した Payout を定期的に再照会してください。

## 手数料のフィールドはどう読めばよいですか？

| フィールド | 意味 |
| - | - |
| `feeCurrency` | 手数料が課される通貨 |
| `actFeeAmount` | 注文が最終状態になった時点で実際に徴収された手数料 |
| `feeStatus` | `DEDUCTED`、`RETURNED`、`NONE` |

`actFeeAmount` と `feeStatus` は連動します。

| `feeStatus` | `actFeeAmount` | 状況 |
| - | - | - |
| `DEDUCTED` | 手数料の金額 | 徴収され、保持された |
| `RETURNED` | `0` | 徴収され、返還された |
| `NONE` | `0` | 手数料がなかった |

成功した Payout は `DEDUCTED` または `NONE` で終わります。失敗した Payout は 3 つのいずれにもなりえます。注文が
受取側に到達しなかった場合は手数料が全額戻り、それ以外の場合は、Service → Payout ページでその決済手段の契約が
**Fee Refundable = Yes** とされている場合にのみ戻ります。したがって、失敗すれば無料だと仮定するのではなく、
`feeStatus` を照合対象としてください。

## Payout の手数料は金額から差し引かれますか、それとも上乗せされますか？

上乗せです。`payoutAmount` は受取人に支払うよう依頼した金額であり、貴社の精算口座から出ていくのは `prefundAmount`、
すなわち換算後の Payout 金額**プラス**その注文の手数料です。受取人が自身の受取額から手数料を負担することはありません。

## どの為替レートが使われ、いつ確定しましたか？

Payout のレスポンスにレートは含まれません。含まれるのは各サイドの金額です。要求した通貨での `payoutAmount`、
引き落とされた通貨での `prefundAmount`、受取人が受け取った通貨での `payeeAmount` であり、API にも Portal の Payout
詳細にもレートのフィールドはありません。金額から照合してください。

異なる通貨間の Payout では、注文作成時に正確な受取額が分からないことがあるため、早い段階の照会では `payeeAmount` が
空で、後から入力されることが正当にありえます。作成レスポンスの数値を受取人に提示しないでください。

## Payout の Webhook はありますか？ イベント名は何ですか？

はい：`PAYOUT_NOTIFICATION` です。その注文の `notifyUrl` に配信されます。この URL はリクエストごとのもので、
API 経由の Payout では必須であり、アカウントレベルのフォールバックはありません。ボディは他のすべての Waffo Webhook と
同じエンベロープに従い、`result` は `/api/v1/payout/inquiry` のレスポンスとまったく同じ構造で、`X-SIGNATURE` ヘッダーで
署名されます。検証、レスポンス形式、リトライ動作は他のイベントと同一です。
[署名検証](/docs/ja/developer-docs/webhook/signature-verification)と
[Webhook リトライ](/docs/ja/developer-docs/webhook/retry)を参照してください。出金には独自の別イベント
`WITHDRAW_NOTIFICATION` があります。Payout の Webhook が出金の Webhook になることも、その逆もありません。

## いつ発火しますか？ 中間の通知はありますか？

最後に 1 回だけで、途中では一切ありません。

* Payout が `SUCCESS` または `FAILURE` に達し、**かつ**手数料の会計処理が完了したときにプッシュされます。そのため
  ペイロードには `feeStatus` と `actFeeAmount` がすでに入っています。
* `IN_PROGRESS` の通知は**ありません**。内部ステージの通知もありません。
* 返戻の通知も**ありません**。

## バッチ Payout で Webhook が届かないのはなぜですか？

Payout の Webhook は **API 経由で作成された Payout に対してのみ**プッシュされるからです。Portal のバッチアップロードの
行として発生した Payout は、どのように終わっても Webhook を生成しません。バッチの結果は、バッチ記録とその結果ファイル
（[バッチ Payout のステータスと資金手当て](/docs/ja/support/batch-payout-faq)を参照）、または各行の `payoutOrderId` に対する
`/api/v1/payout/inquiry` で追跡してください。

## Webhook を取りこぼしたり、200 以外を返したりした場合は？

Waffo は、ボディが `failed` または `unknown` の場合、あるいは配信に失敗した場合に、固定のバックオフスケジュールで
リトライします。試行回数と間隔は [Webhook リトライ](/docs/ja/developer-docs/webhook/retry)にあります。イベントを保存したら
`{"message":"success"}` を返してください。

Payout の Webhook は最後に 1 回だけ発火するため、処理しなかった Webhook は、二度と知らされない結果になります。
Payout を Webhook だけで運用しないでください。最終ステータスを把握していない注文については
`/api/v1/payout/inquiry` で照合してください。

## Payout が長時間 `IN_PROGRESS` のままです。いつ心配すべきですか？

進行中の Payout が異常とみなされる時間は公開されておらず、答えはコリドーによって異なるため、経過時間だけでは
判断材料になりません。代わりに行うべきこと：

| 確認項目 | 理由 |
| - | - |
| 注文を再照会する | すでにステータスが動いていて、Webhook だけが届いていない可能性がある |
| `payoutUpdatedAt` | 注文が最後に変化した時刻が分かり、経過時間よりも参考になる |
| `payoutArrivalTime` | Payout が完了したときにのみ設定される — 空なら未完了 |
| Portal 詳細のステータスタイムライン | どのステージまで到達したかが分かる |

強制するために 2 件目の Payout を作成し**ないでください**。進行中の Payout は完了しうるため、2 件目の注文は
2 件目の支払いになります。停滞した Payout は再送するのではなく、`payoutOrderId` を添えて Waffo に提起してください。

## Payout が失敗しました。元のものを再送しますか、新規作成しますか？

**新しい `payoutRequestId`** で新規作成してください。同じ `payoutRequestId` を再送すると、元の注文が元の失敗コードとともに
返るだけで、Payout が再試行されることはありません。まず `failureCode` を読み、そこに示されたものを修正してください。
どのコードが再送の価値があるかは
[Payout エラーコードとリトライ](/docs/ja/support/payout-error-codes-and-retry-faq)を参照してください。

## Payout 記録の `payOption` と `channelId` は何を意味しますか？

`payOption` は、その Payout に対して解決された具体的な受取オプションです。たとえば銀行コードの背後にあるラベルです。
Portal の Payout 詳細では **Payment Option** として表示され、複数ある経路のうちどれを通って銀行に届いたかを確認する
必要があるときに役立ちます。

`channelId` はマーチャント向けのフィールドではありません。Portal の Payout 詳細にも、Payout 照会のレスポンスにも
ありません。どこかで入手したとしても、照合に使う必要のあるものではありません。

## どのような定期的な Payout レポートが得られますか？

3 つあり、すべて Portal の **Payout → Payout Report** の下にあります。

| レポート | 対象期間 |
| - | - |
| **日次** | 暦日 1 日 |
| **週次** | 月曜日から日曜日 |
| **月次** | 月の 1 日から末日まで |

一覧にはレポートごとに **Period**、対象の **Order Count**、**Generated Time**（UTC+8）、およびダウンロードリンクである
**File Name** が表示されます。日付範囲でフィルターし、レポートの種類を選んでください。ファイルは CSV です。

## 当日のレポートを当日中に取得できますか？

**日次**レポートについては、はい。対象日当日に生成されうる唯一のレポートであり、その日の Payout の精算がすべて
完了した時点で生成されます。週次と月次のレポートは、期間が**終了した**後にのみ作成されます。週の途中に週次レポートは
存在しません。いずれの場合も、レポートには**両方**の条件が必要です。

1. 期間が終了していること（日次の場合は当日も該当します）。
2. その期間のすべての Payout の精算が**完了していること**。期間は終了したがまだ未精算の Payout 活動が残っている場合は
   スキップされ、後で再試行されます。

そのため、期間が終了してもレポートがまだ存在しないことがあり、また一覧には正常に生成されたレポートしか表示されません。
保留中や失敗の行を解釈する必要はありません。Payout の活動がまったくない期間では、空のレポートではなく、レポート自体が
作成されません。

## Payout レポートを SFTP に配信したり、定期的にメール送信したりできますか？

**SFTP — 個別対応で可能です。** Waffo は、貴社アカウントの Payout 請求ファイルを日次サイクルで SFTP の配置先に配信できます。
Portal で切り替えるものではなく、Waffo がマーチャントアカウントごとに設定します。アカウントと必要な SFTP の情報を添えて
サポートに依頼してください。**メール — 不可です。** Payout レポートのメール配信登録はありません。いずれの場合も、
Payout レポートは Portal のダウンロードとして引き続き利用できます。Payout → Payout Report を開いてファイル名をクリックすると、
有効期限付きのダウンロードリンクが得られます。精算レポートの配信は独自の SFTP およびメールオプションを持つ別機能なので
（[レポート配信とメール配信登録](/docs/ja/support/report-delivery-and-subscription-faq)を参照）、精算の配信登録が Payout も
カバーしていると仮定しないでください。

## レポートのダウンロードリンクが使えなくなりました。新しいリンクはどう取得しますか？

もう一度ファイル名をクリックしてください。リンクは毎回新しく生成され、意図的に短命です。保存したり転送したり
ジョブに埋め込んだりするのではなく、すぐに使うことが想定されています。期限切れのリンクはエラー状態ではなく、
何も失われていません。

ダウンロードには、Portal ユーザーにレポートダウンロード権限が必要です。権限がない場合、レポートの行とファイル名は
見えますが、ファイル名はリンクではなく単なるテキストになります。アカウント管理者にご相談ください。

## Payout の一覧をエクスポートできますか？ 同期処理ですか？

はい、そして**非同期**です。単一 Payout の一覧もバッチの一覧もタスクとしてエクスポートされます。開始すると、
ブラウザでダウンロードされるのではなく、Portal のエクスポート領域にファイルが表示されます。ステータス、リトライ、
リンクの有効期限は他のすべてのエクスポートと同じです。
[エクスポートとレポートのダウンロード](/docs/ja/support/export-center-faq)を参照してください。

計画に入れるべき 2 つの制限：

| 制限 | 値 |
| - | - |
| エクスポートの日付範囲 | 最大 1 か月 — それより広い選択はタスク作成前に拒否される |
| 照会の日付範囲 | Payout 一覧の照会も 1 か月の範囲に制限される |

非常に大きなエクスポートは切り捨てられるのではなく複数ファイルに分割されるため、データが欠けていると結論する前に
ファイルが 1 つだけでないか確認してください。

## レポートと API のどちらで照合すべきですか？

照合対象の粒度に合う方を使い、両者が異なるものを記述していると想定してください。

| ソース | 粒度 | 適した用途 |
| - | - | - |
| `/api/v1/payout/inquiry` | 1 注文の現在の状態 | 返戻を含む、注文ごとの事実 |
| Payout 一覧のエクスポート | 日付範囲内の注文 | 貴社自身の注文レベルの台帳 |
| Payout レポート | 精算済みの期間 | Payout を実際に清算されたものと突き合わせる |

両者が一致しない場合、通常それを説明するフィールドは、`prefundAmount` と `payoutAmount`（前者は手数料を含み、
資金手当ての通貨）、`actFeeAmount` と `feeStatus`（失敗した Payout は手数料を返している場合とそうでない場合がある）、
そして `subStatus`（返戻は `status` を変えずに資金を動かす）です。不一致を提起する前にこの 3 つを確認してください。

## Waffo は受取人にInvoiceや支払明細を発行できますか？

Payout について受取人向けの領収書やInvoiceが作成されることはありません。受取人が目にするのは、銀行またはウォレットの
明細上に表示される、貴社が送信した `description` です。貴社側で Payout の証跡となるのは、注文記録、Payout 一覧の
エクスポート、Payout レポートです。受取人に書類を渡す必要がある場合は、注文データから生成してください。支払いを特定する
フィールドは `payoutOrderId`、`payeeAmount`、`payeeCurrency`、`payoutArrivalTime`、`description` です。

***

ステータスやレポートが想定と一致しませんか？ `payoutOrderId`、またはレポートの期間と種類を添えて
[サポートにお問い合わせください](mailto:support@waffo.com)。


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