> ## 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 の送金（Payout）に関する最もよくある質問への回答：送金の作成と追跡、通知、国ごとの受取人項目の要件、べき等性、エラーコード。

このページでは、Waffo の送金について加盟店から最もよく寄せられる質問に回答します。
項目レベルの仕様は [Payout API 仕様](/docs/api-reference/introduction) にあります。

## 送金を作成して完了まで追跡するにはどうすればよいですか？

3 つのインテグレーションポイントがあり、すべて必須です。

1. **作成** — 一意の `payoutRequestId`、送金金額と通貨、受取側の `country`、受取人情報を指定して
   `/api/v1/payout/create` を呼び出します。一部の送金経路（コリドー）ではさらに送金 `purpose` が必要です —
   中国本土向けの送金には固定リストからの値を必ず含める必要があります。レスポンスには Waffo の `payoutOrderId` と
   初期 `status` が返されます。
2. **照会** — `payoutRequestId` または `payoutOrderId` のいずれかを指定して `/api/v1/payout/inquiry` を呼び出すと、
   いつでも送金オブジェクト全体を取得できます。
3. **受信** — 指定した `notifyUrl` で**送金通知**の Webhook を受信します。送金が完了または失敗したときに送信されます。

## 送金にはどんなステータスがありますか？

| ステータス | 意味 |
| - | - |
| `IN_PROGRESS` | 送金は処理中です。 |
| `SUCCESS` | 送金は成功しました。 |
| `FAILURE` | 送金は失敗しました — `failureCode` と `failureReason` を確認してください。 |

`subStatus` フィールドは、成功後にリバーサル（取り消し）が発生した場合のみ現れます（`status` は `SUCCESS` のまま）：
`FULL_REVERSED` は全額がリバースされたこと、`PARTIAL_REVERSED` は一部のみがリバースされたことを意味します。
ほとんどの注文には `subStatus` は付きません。

## べき等性はどう機能しますか？作成リクエストをリトライするとどうなりますか？

`payoutRequestId` がべき等キーです。**同じ** `payoutRequestId` で `/api/v1/payout/create` をリトライすると：

* 金額、通貨、受取人口座が**同じ**場合、*元の*注文のデータを含む**通常の成功コード**が返されます — 現在のステータス、
  およびすでに失敗していた場合はその元の失敗コードを含みます。2 つ目の送金は作成されません。返された `payoutOrderId` を
  すでに保持しているものと比較してこれを検出してください。べき等性専用のコードはありません。
* 金額、通貨、受取人口座のいずれかが**異なる**場合、`A0011`（idempotent param mismatch）が返され、リクエストは
  拒否されます。比較対象はこの 3 つの項目のみであることに注意してください — 受取人を編集して再送する場合に何を
  意味するかは [送金リクエスト項目ガイド](/docs/ja/support/payout-request-field-guide) を参照してください。

`Exxxxx` の不明エラーを受け取った場合、最終結果はまだ確定していません — 最終的な `SUCCESS` または `FAILURE` ステータスを
受け取るまで照会をリトライし続けてください。不明な結果を失敗として扱わないでください。

## 受取人の氏名項目はどれが必須ですか？

`payeeFirstName`、`payeeMiddleName`、`payeeLastName` は**条件付き**です：必須かどうかは受取国と送金方法によって異なります。
`payeeIDType` も同様です：現在、要件が強制される国は `CHN` です（ID またはパスポートの提出が必要で、銀行送金にはさらに
現地のルールがあります）。他の国は国固有のルールではなくチャネルによって検証されるため、使用するコリドーの項目要件表に
従ってください。インドネシア（`IDN`）では、`IDN_BANK` の銀行送金でも `DANA` の電子ウォレット送金でも氏名項目は必須ではありませんが、
銀行送金では `payoutMethodProperty` 内に `bankCode` が必要です。

使用する国と方法については、[Payout API 仕様](/docs/api-reference/introduction) の Payout Creation Field Requirements 表を
確認してください。利用できる方法は契約済みの設定によって異なります。

## 送金通知はどう機能しますか？

送金が完了または失敗すると、Waffo は `eventType` を `PAYOUT_NOTIFICATION` に設定した HTTPS POST を `notifyUrl` に送信します。
`result` オブジェクトは `/api/v1/payout/inquiry` のレスポンスと同じ構造です。

処理後、`message` を `success` に設定して応答してください。Waffo が `failed` または `unknown` を受け取った場合、
固定のバックオフスケジュールで通知をリトライします。試行回数と間隔は [Webhook のリトライ](/docs/ja/developer-docs/webhook/retry) を参照してください。
ペイロードを信頼する前に、Waffo の公開鍵で `X-SIGNATURE` ヘッダーを検証してください（署名アルゴリズム：`SHA256WithRSA`）。

## よくあるエラーコードは何を意味しますか？

エラーコードは接頭辞でグループ化されています：`A` 加盟店関連、`B` ユーザー関連、`C` システム関連、`D` リスク拒否、
`E` 不明（最終結果までリトライ）。

| コード | 意味 | 対処 |
| - | - | - |
| `A0007` | Payout currency is not supported | 契約済みの設定でカバーされる通貨を使用してください。 |
| `A0012` | Merchant account insufficient balance | アカウントに入金してから再送信してください。 |
| `A0008` | Payout limit exceeded | 金額をアカウントの許容範囲内に収めてください。 |
| `A0013` | Too many requests | 間隔を空けて後でリトライしてください。 |
| `A0011` | Idempotent param mismatch | 同じ `payoutRequestId` が異なる金額、通貨、または受取人口座で再利用されました。 |
| `E0001` | Unknown status | 最終的な `SUCCESS` / `FAILURE` になるまで照会をリトライしてください。 |

送金のコードセットは決済のものと**同じではありません** — いくつかのコードは異なる意味を持ち、送金には `A0014` はありません。
安全にリトライできる 4 つのコードを含む完全な表は
[送金のエラーコードとリトライ](/docs/ja/support/payout-error-codes-and-retry-faq) にあります。

## 残高からはどの金額が引き落とされますか？

照会レスポンスでは金額が分けて返されます：`payoutAmount`（送金を依頼した金額）、`prefundAmount`（アカウントから引き落とされる金額、
**手数料込み**）、`payeeAmount`（受取人が受け取る金額 — 異通貨の送金では正確な受取金額が不明な場合があります）。
送金が失敗した場合、残額はお客様に返還されます。状況によって手数料は引き続き請求されることがあり、それは `feeStatus`
（`DEDUCTED`、`RETURNED`、または `NONE`）に反映されます。


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