> ## 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 の作成リクエストを構築するためのフィールドごとの回答：payoutRequestId の冪等性が実際にどのようにリクエストを比較するか、国によって条件付きになる受取人フィールド、2 つの異なる日付形式、電話番号と PIX キーの形式、コリドーごとの銀行プロパティ、purpose の値、金額の精度、そして API が拒否するフィールド。

このページは [Payout FAQ](/docs/ja/support/payout-faq) のフィールドレベルの補足です。Payout の作成リクエストの各フィールドに
何を入れるか、そして正しく見える値が拒否される理由を扱います。そもそもどのコリドーへ Payout できるかは
[Payout ウォレットとカバレッジ](/docs/ja/support/payout-wallet-and-coverage-faq) を、拒否内容の解読は
[Payout のエラーコードと再試行](/docs/ja/support/payout-error-codes-and-retry-faq) を参照してください。

## `payoutRequestId` は自分で生成しますか？ 制限は何ですか？

はい。お客様が生成するもので、冪等キーです。制約：

| 項目 | 値 |
| - | - |
| 生成者 | お客様 |
| 最大長 | 64 文字 |
| 必須 | はい、作成のたびに必要 |
| 一意性の範囲 | 加盟店アカウントごと、かつリクエストチャネルごと（API の Payout と Portal の一括 Payout は別の空間） |

Waffo は併せて独自の `payoutOrderId` を返します。照会にはどちらも使用できます。`/api/v1/payout/inquiry` は
`payoutRequestId` **または** `payoutOrderId` を受け付け、両方を送信した場合は `payoutOrderId` が優先されます。

## 同じ `payoutRequestId` を再利用すると、正確には何が起きますか？

Waffo は既存の注文を参照し、新しいリクエストの**3 つ**のフィールドと比較します。

* `payoutAmount`
* `payoutCurrency`
* `payoutInfo.payoutMethodUserAccountNo`

その結果：

| ケース | 結果 |
| - | - |
| 3 つすべてが一致 | **元の**注文が現在のステータスとともに返されます。2 つ目の Payout は作成されません。 |
| 3 つのいずれかが異なる | `A0011`（冪等性パラメーターの不一致）で拒否されます。何も作成されません。 |
| 元の注文がすでに失敗で終了している | 新しい試行ではなく、元の注文が**元の失敗コードとともに**返されます。 |
| 同一の作成リクエストが同時に 2 件届く | 一方が `A0013` で拒否され、もう一方が処理されます。 |

つまずきやすい 2 つの結果：

* **金額、通貨、口座番号を同一に保ったまま受取人の氏名、ID、住所、国、決済手段を変更しても `A0011` にはなりません。**
  比較はそれらのフィールドを対象としないため、元の注文が返され、編集した内容は黙って無視されます。同じ
  `payoutRequestId` で受取人を編集して再送信しないでください。新しい ID を発行してください。
* **失敗した Payout を同じ `payoutRequestId` で再送信することはできません。** 古い失敗が返されます。失敗した Payout を
  再試行するには、新しい `payoutRequestId` で新しい注文を作成してください。

## 作成リクエストが `A0013`「Too many requests」を返しました。レート制限を受けているのですか？

Payout の作成においては違います。そこでの `A0013` は、**同じ `payoutRequestId`** に対する 2 つ目の作成リクエストが
すでに処理中であったことを意味します。リクエストはリクエスト ID ごとに直列化され、負けた方が拒否されます。
これはスループットの制限ではなく、重複送信のガードです。少し待って同じ呼び出しを再試行するか、より良いのは先に照会することです。
最初の試行が成功している可能性が十分にあります。

## 受取人のフィールドで実際に必須なのはどれですか？

リクエストスキーマが必須としているのは `payeeInfo` 内の `payeeId` と `payeeType` だけです。それ以外はすべて条件付きで、
受取国、Payout の決済手段、または受取側自身のルールによって必須になります。

| フィールド | 制約 |
| - | - |
| `payeeId` | 必須。受取人に対するお客様独自の識別子。 |
| `payeeType` | 必須。`INDIVIDUAL` または `BUSINESS`。それ以外の値は拒否されます。 |
| `payeeFirstName` / `payeeMiddleName` / `payeeLastName` | 各最大 60 文字。コリドーによって条件付き。 |
| `payeeFullName` | 分割しない単一の氏名を受け付けるコリドーで使用可能。 |
| `nationality` | 3 文字の国コード、最大 3 文字。 |
| `payeePhone` | 形式は `+{国番号}-{番号}`、例：`+62-08990013157`。存在する場合は検証されます。 |
| `payeeEmail` | 存在する場合は検証されます。 |
| `payeeBirthDay`、`payeeIDIssueDate`、`payeeIDExpiryDate` | `dd/mm/yyyy`。存在する場合は検証されます。 |
| `payeeIDType`、`payeeIDNumber` | 国によって条件付き — 下記参照。 |

`addressInfo`（`address`、`city`、`region`、`postcode`、`addressCountryCode`）は独立した任意のオブジェクトです。
一般的な検証でこれが必須になることはありません。必要とするコリドーでは、事前チェックの段階でそれを名指しした
必須フィールド不足のエラーで Payout が拒否されるため、手元にある場合は送信してください。

## なぜ日付形式が 2 種類あるのですか？

受取人の書類とリクエストのエンベロープが異なるルールで検証されるためで、これは `A0003` のよくある原因です。

| フィールド | 形式 | 例 |
| - | - | - |
| `payeeBirthDay` | `dd/mm/yyyy` | `05/09/1990` |
| `payeeIDIssueDate` | `dd/mm/yyyy` | `12/01/2021` |
| `payeeIDExpiryDate` | `dd/mm/yyyy` | `12/01/2031` |
| `payoutRequestedAt` | ISO 8601、`yyyy-MM-dd'T'HH:mm:ss.SSS'Z'` | `2026-09-07T02:15:30.000Z` |
| `payoutArrivalTime`、`payoutUpdatedAt`（レスポンス） | ISO 8601、同じ形式 | |

## 電話番号に国番号は必要ですか？ 先頭のゼロはどうしますか？

`+{国番号}-{番号}` の形式で送信してください。国内番号の先頭の `0` は、落とすコリドーと落とさないコリドーがあるため、
一般的なルールではなくコリドー自身のガイダンスに従ってください。eウォレットの Payout では電話番号が口座識別子を兼ねることがあり、
その場合の形式はこのフィールドではなく受取ウォレットが定めます。下記の口座番号の項を参照してください。

## `payeeIDType` にはどの値が受け付けられますか？ なぜ `PASSPORT` が拒否されたのですか？

定義されている値は `ID`、`PASSPORT`、`CPF`、`CNPJ` ですが、受け付けられる**集合は国ごとに絞り込まれ**、その国の集合外の値は
有効な列挙メンバーであっても拒否されます。

| 受取国 | 受け付けられる `payeeIDType` | 必須か |
| - | - | - |
| 中国本土（`CHN`） | `ID`、`PASSPORT` | はい — 指定がないとリクエストは拒否されます |
| ブラジル（`BRA`） | `CPF`、`CNPJ` | はい、`payeeIDNumber` と併せて |
| その他の国 | 国レベルの制限なし。受取側が検証します | コリドーによる |

したがって、ブラジル向け Payout で `PASSPORT` が拒否されるのは、ブラジルの受け付け集合が `CPF` / `CNPJ` のみだからです。
拒否メッセージはフィールド名と許可される値の一覧を示します。

## ブラジル：CPF と CNPJ はどう使い分けますか？

`payeeType` に従い、両者は一致している必要があります。

| `payeeType` | 書類の種類 | `payeeIDNumber` の形式 |
| - | - | - |
| `INDIVIDUAL` | `CPF` | 11 桁 |
| `BUSINESS` | `CNPJ` | 14 桁 |

`payeeIDType` を省略した場合、この基準に基づいて `payeeType` から推定されます。送信した値が `payeeType` と矛盾する場合
（たとえば `INDIVIDUAL` に `CNPJ`）、Payout は拒否されます。`payeeIDNumber` はこのコリドーでは常に必須で、
上記の桁数パターンに対して検証されます。

## `INDIVIDUAL` と `BUSINESS` の違いは何ですか？

`payeeType` は、どの Payout の取り決めがそのリクエストを処理できるかを選択します。契約している決済手段は個人、法人、
またはその両方を受け付けることがあり、`payeeType` をどのコリドーも受け付けない Payout は未契約として拒否されます。
ルーティング以外の実務的な違いは上記の書類ルールです。ブラジルでは `BUSINESS` は `CNPJ` を意味します。
記入すべき「法人向け Payout」の独立したオブジェクトはありません。

## 支払う前に受取人を登録する必要がありますか？

いいえ。受取人のボールトも受取人登録の呼び出しもありません。Payout の作成のたびに受取人の情報を完全に送信し、
Waffo が以前の注文の情報を再利用することはありません。受取人の記録はお客様側で保持し、毎回そこからリクエストを
組み立ててください。

## `payoutMethodType` はどれを選びますか？ `payoutMethodName` はいつ必要ですか？

| `payoutMethodType` | `payoutMethodName` | `payoutMethodProperty` |
| - | - | - |
| `EWALLET` | **必須** — ウォレットの名前。空の値は拒否されます | 不要 |
| `BANK_ACCOUNT` | 空のままにする | **必須** — JSON オブジェクト。空の値は拒否されます |

値はこの 2 つだけです。`productName` はアカウントが保有するプロダクトに対して検証されるため、設定されていない Payout の
プロダクトはこのフィールドで拒否されます。`ONE_TIME_PAYOUT` は単発で反復しない Payout の値です。

## 銀行 Payout の `payoutMethodProperty` には何を入れますか？

JSON 文字列です。重要なキーと、それがどこで強制されるか：

| キー | 必須になる条件 |
| - | - |
| `bankCode` | 中国本土を**除く**すべての `BANK_ACCOUNT` Payout で必須 |
| `bankName` | 中国本土では必須。中国語の文字を含む必要があります |
| `bankSub` | 中国本土でカード番号が `62` で始まら**ない**場合に必須。中国語の文字を含む必要があります。他のコリドーでは支店の識別子として使用されます。 |
| `accountType` | 一部のコリドーで必須 — ブラジルでは `CRN`、`PAC`、`SVN` のいずれか |
| `accountName` | 任意。`payeeInfo` の氏名フィールドで表現できない名義で口座が保有されている場合に指定します |

このフィールドの不正な JSON は、それ自体が `A0003` になります。コリドーが銀行ごとの支店や口座番号のパターンを保持している場合、
事前チェックのステップでそれらに対して検証され、不一致は `bankSub` または口座番号を名指しした必須フィールド不足・不正の
エラーで拒否されます。

## 銀行コードはどこから入手しますか？

公開された銀行コードの照会エンドポイントはなく、ドキュメントにダウンロード可能な銀行一覧もありません。銀行コードは
コリドー固有です。構築を始める前に、Payout 契約のコリドーをカバーする一覧を Waffo にご依頼ください。中国本土は例外で、
`bankCode` はまったく不要です。`bankName`（中国語で）と、`62` で始まらないカードの場合は `bankSub` を送信してください。

## 中国の銀行 Payout では、口座名義は中国語である必要がありますか？

`bankName` は中国語の文字を含む必要があり、`bankSub` が適用される場合はそれも同様です。口座名義人の氏名自体は
`payeeInfo` の氏名フィールドに入れます。`payoutMethodProperty` 内の `accountName` は、それらのフィールドでは表せない
名義で口座が保有されている場合にのみ使用してください。

## `payoutMethodUserAccountNo` には何を入れますか？

決済手段によって異なります。

| 決済手段 | 値 |
| - | - |
| `BANK_ACCOUNT` | 受取人の銀行口座番号 |
| `EWALLET` | そのウォレットにおける受取人の公開ユーザー識別子、または — ウォレットが受け付ける場合 — そのウォレットが指定する形式での受取人の携帯電話番号 |

電話番号を受け付けるウォレットでは、数字は `payeePhone` の形式ではなくウォレット自身の形式に従います。国内の先頭のゼロは
落とし、国番号を含めます。したがってインドネシアの番号は `0` や `+62-0` ではなく `628` で始まる形で送信します。

## ブラジルの PIX：どのキータイプが使えますか？ ランダム（EVP）キーは許可されますか？

標準の 5 つのキータイプすべてが受け付けられ、タイプは値そのものから推定されます。設定するキータイプのフィールドはありません。

| キータイプ | 受け付けられる形式 |
| - | - |
| CPF | 11 桁 |
| CNPJ | 14 桁 |
| 電話番号 | E.164、例：`+5511987654321` |
| メールアドレス | 有効なメールアドレス |
| EVP（ランダムキー） | 受取人の銀行が発行した UUID |

したがって EVP も使えます。5 つのいずれにも一致しない値は `payoutMethodUserAccountNo` で拒否されます。

## 口座番号と受取人の氏名が一致しない場合はどうなりますか？

受取側が事前チェックで口座名義人の氏名を返す場合、Waffo はそれを送信された内容と比較し、不一致であれば
`B0004`（"User info does not match"）で Payout を失敗させます。この比較は想像より狭い範囲です。

* 比較されるのは**名**と**姓**のみです。`payeeMiddleName` は比較されません。
* 比較は**大文字小文字を区別しません**。
* どちらかの値が空の場合、そのチェックは通過します。

したがってチェックは実在しますが、完全な氏名照合としては頼れません。氏名を返さないコリドーではチェックはまったく行われず、
送信した氏名と異なる名義人の口座に Payout が成功することもあります。送信前にお客様側で受取人の情報を確認してください。

## `purpose` は必須ですか？ 有効な値は何ですか？

**中国本土**向けの Payout では必須で、固定の一覧に対して検証されます。他の国では国レベルの検証で必須にはなりませんが、
個々のコリドーがこれのない Payout を拒否することはあります。

| `purpose` |
| - |
| `SALARY_PAYMENT` |
| `SERVICE_CHARGES` |
| `ADVISORY_FEES` |
| `ADVERTISING_EXPENSES` |
| `CONSTRUCTION_EXPENSES` |
| `PROPERTY_RENTAL` |
| `TAX_PAYMENT` |
| `LIBERALIZED_REMITTANCE` |

一覧にない値は、その値がそのまま返された状態で拒否されます。支払いを正直に説明するものを選んでください。これはラベルではなく
規制上の申告です。

## `description` は受取人に表示されますか？ 切り詰められますか？

はい。受取人の銀行またはウォレットの明細に表示されます。そのため必須フィールドです。最大 128 文字ですが、それよりずっと短く
書いてください。受取側の銀行やウォレットは切り詰めるため、英語でおよそ 16 単語、中国語で 10 文字程度を目安にし、
重要な識別情報を先頭に置いてください。Waffo は切り詰めません。切り詰めるのは受取側で、その挙動は予測できません。

## `extendInfo` には何を入れられますか？ 返ってきますか？

JSON オブジェクトを文字列にシリアライズしたもの、たとえば `{"key1":"value1","key2":"value2"}` です。
`/api/v1/payout/inquiry` と Payout の Webhook でそのまま返されます。JSON として解析できない値は `A0003` で拒否されます。
自社の相関 ID を入れるのに適した場所であり、受取人には伝わりません。

## 金額の小数点以下は何桁まで使えますか？

`payoutAmount` は文字列で、受け付けられる精度は固定の桁数ではなく**受取通貨自身の精度**です。その通貨が許す桁数より
小数が多い値は `payoutAmount` を名指しした `A0003` で**拒否されます** — 黙って丸められることはありません。
フィールド自体のパターンは小数 8 桁まで許容するため、コードが満たすべきなのはパターンではなく通貨のチェックです。

金額は、そのコリドーの Payout 契約の最小値と最大値でも制限されます。範囲内に見える金額が代わりに `A0008` になるのは
そのためです。どちらの境界も Portal の Service → Payout ページにあります。

## 受取人が受け取る通貨を指定できますか？

リクエストでは指定できません。単件の Payout API では、`payeeCurrency` と `payeeAmount` は**送信すると拒否されます** —
これらは入力ではなく出力です。お客様が設定するのは `payoutCurrency` と `payoutAmount` であり、受取人の通貨は
そのコリドーの Payout 契約にある通貨ペアから決まります。

クロスカレンシーの Payout では、注文作成時に正確な受取額が分からないことがあるため、`payeeAmount` は最初の照会では
空で返り、後から値が入ることがあります。リクエスト時点で受取人に正確な金額を約束しないでください。お客様から差し引かれるのは
`prefundAmount` — 換算後の金額にその注文の手数料を加えたもの — であり、
[Payout ウォレットとカバレッジ](/docs/ja/support/payout-wallet-and-coverage-faq) で説明しています。

## `notifyUrl` は任意ですか？ Portal で設定したものを上書きしますか？

API 経由で作成される Payout では `notifyUrl` は**必須**です。指定のない作成は拒否されます。`http://` または `https://` で
始まる必要があります。フォールバックとなるアカウントレベルの Payout 通知 URL はなく、上書きするものもありません。
Payout の Webhook はその注文の URL にのみ送信されるため、これを指定せずに作成した Payout は、通知を受け取ることのない
Payout です。

## `merchantInfo` は何のためにありますか？

`merchantInfo.merchantId` は必須で、お客様の Waffo 加盟店 ID です。`merchantInfo.subMerchantId` は任意で、アカウントが
サブ加盟店を持つ構成の場合にのみ関係します。どちらも照会時にそのまま返されます。

***

このページで説明されていないフィールドで拒否されましたか？ `A0003` のメッセージがフィールド名を示します。読み方は
[Payout のエラーコードと再試行](/docs/ja/support/payout-error-codes-and-retry-faq) を参照するか、`payoutRequestId` を添えて
[サポートにお問い合わせください](mailto:support@waffo.com)。


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