Payout の作成は同期ですか、非同期ですか？
実務上はすべて非同期です。作成が成功するとstatus: IN_PROGRESS の注文と Waffo の payoutOrderId が返り、結果は
後から届きます。結果を知る方法はちょうど 3 つあり、そのうち少なくとも 2 つを前提に構築すべきです。
作成がすでに最終状態で返ることもあります。元の注文が完了している
payoutRequestId を同一内容で再送すると、その
最終ステータスが直ちに返り、事前チェックの段階で失敗した Payout は同期的に失敗します。作成レスポンスの SUCCESS と
FAILURE は本物として扱ってください。
Payout にはどのようなステータスがあり、どれが最終ですか？
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 と対応範囲に記載されています。
subStatus とは何ですか？ CONSULT_SUCCESS と CONSULT_FAILURE は？
subStatus は返戻が発生した場合にのみ存在し、常に次の 2 つの値のいずれかのみを持ちます。
CONSULT_SUCCESS と CONSULT_FAILURE は事前チェックステップの内部マーカーであり、レスポンスが組み立てられる前に
除外されます。API が返す subStatus は返戻の 2 つの値のみなので、これらを受け取ることはありません。目にしたことが
あるなら、それは Payout API 以外のどこかから来たものであり、対処すべき意味は持ちません。
Payout が成功しました。それでも返戻されることがありますか？
はい。受取側は、すでにSUCCESS に達した Payout を返戻することがあります。その場合：
statusはSUCCESSのままです。失敗や返戻のステータスに移ることはありません。subStatusがFULL_REVERSEDまたはPARTIAL_REVERSEDになります。- 返戻された金額は、その Payout の資金元であるアカウント、つまり貴社の精算口座に、資金手当ての通貨で戻されます。 一部返戻では返戻された部分のみが戻るため、元の Payout 金額ではなく返戻を基準に照合してください。
SUCCESS を注文の終わりとして扱うのではなく、成功した Payout を定期的に再照会してください。
手数料のフィールドはどう読めばよいですか？
actFeeAmount と feeStatus は連動します。
成功した 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 ヘッダーで
署名されます。検証、レスポンス形式、リトライ動作は他のイベントと同一です。
署名検証と
Webhook リトライを参照してください。出金には独自の別イベント
WITHDRAW_NOTIFICATION があります。Payout の Webhook が出金の Webhook になることも、その逆もありません。
いつ発火しますか？ 中間の通知はありますか？
最後に 1 回だけで、途中では一切ありません。- Payout が
SUCCESSまたはFAILUREに達し、かつ手数料の会計処理が完了したときにプッシュされます。そのため ペイロードにはfeeStatusとactFeeAmountがすでに入っています。 IN_PROGRESSの通知はありません。内部ステージの通知もありません。- 返戻の通知もありません。
バッチ Payout で Webhook が届かないのはなぜですか？
Payout の Webhook は API 経由で作成された Payout に対してのみプッシュされるからです。Portal のバッチアップロードの 行として発生した Payout は、どのように終わっても Webhook を生成しません。バッチの結果は、バッチ記録とその結果ファイル （バッチ Payout のステータスと資金手当てを参照）、または各行のpayoutOrderId に対する
/api/v1/payout/inquiry で追跡してください。
Webhook を取りこぼしたり、200 以外を返したりした場合は？
Waffo は、ボディがfailed または unknown の場合、あるいは配信に失敗した場合に、固定のバックオフスケジュールで
リトライします。試行回数と間隔は Webhook リトライにあります。イベントを保存したら
{"message":"success"} を返してください。
Payout の Webhook は最後に 1 回だけ発火するため、処理しなかった Webhook は、二度と知らされない結果になります。
Payout を Webhook だけで運用しないでください。最終ステータスを把握していない注文については
/api/v1/payout/inquiry で照合してください。
Payout が長時間 IN_PROGRESS のままです。いつ心配すべきですか？
進行中の Payout が異常とみなされる時間は公開されておらず、答えはコリドーによって異なるため、経過時間だけでは
判断材料になりません。代わりに行うべきこと：
強制するために 2 件目の Payout を作成しないでください。進行中の Payout は完了しうるため、2 件目の注文は
2 件目の支払いになります。停滞した Payout は再送するのではなく、
payoutOrderId を添えて Waffo に提起してください。
Payout が失敗しました。元のものを再送しますか、新規作成しますか？
新しいpayoutRequestId で新規作成してください。同じ payoutRequestId を再送すると、元の注文が元の失敗コードとともに
返るだけで、Payout が再試行されることはありません。まず failureCode を読み、そこに示されたものを修正してください。
どのコードが再送の価値があるかは
Payout エラーコードとリトライを参照してください。
Payout 記録の payOption と channelId は何を意味しますか？
payOption は、その Payout に対して解決された具体的な受取オプションです。たとえば銀行コードの背後にあるラベルです。
Portal の Payout 詳細では Payment Option として表示され、複数ある経路のうちどれを通って銀行に届いたかを確認する
必要があるときに役立ちます。
channelId はマーチャント向けのフィールドではありません。Portal の Payout 詳細にも、Payout 照会のレスポンスにも
ありません。どこかで入手したとしても、照合に使う必要のあるものではありません。
どのような定期的な Payout レポートが得られますか？
3 つあり、すべて Portal の Payout → Payout Report の下にあります。
一覧にはレポートごとに Period、対象の Order Count、Generated Time（UTC+8）、およびダウンロードリンクである
File Name が表示されます。日付範囲でフィルターし、レポートの種類を選んでください。ファイルは CSV です。
当日のレポートを当日中に取得できますか？
日次レポートについては、はい。対象日当日に生成されうる唯一のレポートであり、その日の Payout の精算がすべて 完了した時点で生成されます。週次と月次のレポートは、期間が終了した後にのみ作成されます。週の途中に週次レポートは 存在しません。いずれの場合も、レポートには両方の条件が必要です。- 期間が終了していること（日次の場合は当日も該当します）。
- その期間のすべての Payout の精算が完了していること。期間は終了したがまだ未精算の Payout 活動が残っている場合は スキップされ、後で再試行されます。
Payout レポートを SFTP に配信したり、定期的にメール送信したりできますか？
SFTP — 個別対応で可能です。 Waffo は、貴社アカウントの Payout 請求ファイルを日次サイクルで SFTP の配置先に配信できます。 Portal で切り替えるものではなく、Waffo がマーチャントアカウントごとに設定します。アカウントと必要な SFTP の情報を添えて サポートに依頼してください。メール — 不可です。 Payout レポートのメール配信登録はありません。いずれの場合も、 Payout レポートは Portal のダウンロードとして引き続き利用できます。Payout → Payout Report を開いてファイル名をクリックすると、 有効期限付きのダウンロードリンクが得られます。精算レポートの配信は独自の SFTP およびメールオプションを持つ別機能なので （レポート配信とメール配信登録を参照）、精算の配信登録が Payout も カバーしていると仮定しないでください。レポートのダウンロードリンクが使えなくなりました。新しいリンクはどう取得しますか？
もう一度ファイル名をクリックしてください。リンクは毎回新しく生成され、意図的に短命です。保存したり転送したり ジョブに埋め込んだりするのではなく、すぐに使うことが想定されています。期限切れのリンクはエラー状態ではなく、 何も失われていません。 ダウンロードには、Portal ユーザーにレポートダウンロード権限が必要です。権限がない場合、レポートの行とファイル名は 見えますが、ファイル名はリンクではなく単なるテキストになります。アカウント管理者にご相談ください。Payout の一覧をエクスポートできますか？ 同期処理ですか？
はい、そして非同期です。単一 Payout の一覧もバッチの一覧もタスクとしてエクスポートされます。開始すると、 ブラウザでダウンロードされるのではなく、Portal のエクスポート領域にファイルが表示されます。ステータス、リトライ、 リンクの有効期限は他のすべてのエクスポートと同じです。 エクスポートとレポートのダウンロードを参照してください。 計画に入れるべき 2 つの制限：
非常に大きなエクスポートは切り捨てられるのではなく複数ファイルに分割されるため、データが欠けていると結論する前に
ファイルが 1 つだけでないか確認してください。
レポートと API のどちらで照合すべきですか？
照合対象の粒度に合う方を使い、両者が異なるものを記述していると想定してください。
両者が一致しない場合、通常それを説明するフィールドは、
prefundAmount と payoutAmount（前者は手数料を含み、
資金手当ての通貨）、actFeeAmount と feeStatus（失敗した Payout は手数料を返している場合とそうでない場合がある）、
そして subStatus（返戻は status を変えずに資金を動かす）です。不一致を提起する前にこの 3 つを確認してください。
Waffo は受取人にInvoiceや支払明細を発行できますか？
Payout について受取人向けの領収書やInvoiceが作成されることはありません。受取人が目にするのは、銀行またはウォレットの 明細上に表示される、貴社が送信したdescription です。貴社側で Payout の証跡となるのは、注文記録、Payout 一覧の
エクスポート、Payout レポートです。受取人に書類を渡す必要がある場合は、注文データから生成してください。支払いを特定する
フィールドは payoutOrderId、payeeAmount、payeeCurrency、payoutArrivalTime、description です。
ステータスやレポートが想定と一致しませんか？
payoutOrderId、またはレポートの期間と種類を添えて
サポートにお問い合わせください。