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

# 決済手段ごとの条件付き必須フィールド

> /api/v1/order/create で Optional と記載されているフィールド — goodsId、goodsUniquePrice、skuName、userFirstName、userPhone、address など — がなぜ「不足」として拒否されることがあるのか、不足フィールド一覧にどのフィールドパスが現れうるのか、そして事前に予測するのではなく送信して一覧を読み取るのが正しいパターンである理由。

アクワイアリング仕様では `goodsInfo`、`addressInfo`、および `userInfo` のいくつかのフィールドが
任意と記載されており、実際に裏側のオブジェクトにも長さ制限しかなく、必須制約はありません。
それでも、スキーマ検証を通過したリクエストが、これらのフィールドのいずれかを名指しして
`A0003 Parameter validation failed` で返されることがあります。以下で使用する `payMethodType` の値は
[データリファレンス](/docs/ja/developer-docs/tools-and-references/references/data-reference) に一覧があります。

## Optional と記載されているフィールドが、なぜ「不足」として拒否されるのですか？

「必須」かどうかは API の属性ではなく、**実際に使用される決済手段**と、お客様が置かれている**シナリオ**の
属性だからです。ある連携ではカード決済を送信し `goodsInfo` から何も必要としませんが、別の連携では
分割払い決済を送信し、明細付きの完全なカート情報が必要になります。単一のスキーマで両方を表すことはできません。
このことから 2 つの結果が生じます。

* **要件は決済手段だけで安定的に決まるものではありません。** 同じ決済手段でも決済の処理方法によって
  異なるフィールドが要求されることがあり、お客様側の変更なしにその集合が変わることもあります。そのため、
  連携側にハードコードした決済手段ごとの一覧は、気づかないうちに古くなっていきます。
* **事前確認用の探索エンドポイントはありません。** `/api/v1/paymethodconfig/inquiry` は
  利用可否、メンテナンス時間帯、金額範囲、通貨、返金ポリシーを返しますが、
  フィールド要件は返**しません**。

## では、正しいパターンは何ですか？

送信し、一覧を読み取り、再送信します。予測はしないでください。

1. 手元にあるすべての情報を含めてリクエストを送信します。
2. 必須フィールドが不足している場合、呼び出しは `A0003` で失敗します。`A0003` に限っては、
   レスポンスの `msg` に括弧付きでフィールドレベルの詳細が付加されます。`/api/v1/order/refund` では、
   不足しているパスが `missingFields` の一覧としても返されます。
3. ちょうどそのパスを埋めて再送信します。

パスはドット区切りの形式で返されます — `userInfo.userFirstName`、`addressInfo.postcode`、
`goodsInfo.goodsUniquePrice` — そのため、リクエストボディにそのまま対応付けられます。

**ホスト型チェックアウトを使用している場合、通常これを目にすることはありません。** 選択された決済手段が
お客様の送信していないフィールドを必要とする場合、Waffo は注文をチェックアウトへルーティングし、
チェックアウトが購入者に対してそれらの入力欄を表示します。上記のループが最も重要になるのは、フォールバック先の
チェックアウトが存在しない場合です。つまり、加盟店起点の取引（`merchantInitiatedMode`）と、
直接処理されるエージェント決済です。

## 不足フィールド一覧には、どのフィールドパスが現れうるのですか？

| オブジェクト | 要求されうるパス |
| - | - |
| `userInfo` | `userFirstName`、`userLastName`、`userPhone`、`userEmail`、`userId`、`userIDNumber` |
| `userInfo.userBankInfo` | `bankAccountNo`、`bankCode`、`bankName`、`bankBranch`（送金で支払われる返金） |
| `addressInfo` | `address`、`city`、`region`、`postcode`、`addressCountryCode` |
| `goodsInfo` | `goodsId`、`goodsName`、`goodsUniquePrice`、`goodsQuantity`、`skuName`、`goodsCategory`、`goodsUrl` |
| `paymentInfo` | `payMethodUserAccountType`（`EMAIL` / `PHONE_NO` / `ACCOUNT_ID`）と `payMethodUserAccountNo` |
| `payMethodProperties` | 市場固有の識別子 — `cpf`、`curp`、`nin`、`cc`、`ci`、`bankCode`、`accountNumber`、`receiveBank`、`cryptoChain`、`cardToken`、`paymentToken` |
| `extendInfo` | `extendInfo` JSON 文字列内のキーとしての `refundAddress` |

## 大まかに、どの決済手段タイプが何を要求しますか？

方向性を示すものにすぎません — データ収集の規模を見積もるには有用ですが、契約では**ありません**。
返された一覧に判断を委ねてください。同じ決済手段タイプでも市場によって要件は異なり、
これが静的な一覧が成り立たないもうひとつの理由です。

| `payMethodType` | 一般的に要求されるもの |
| - | - |
| `BNPL` | 最も多い集合：明細付きのカート（`goodsId`、`goodsName`、`goodsUniquePrice`、`goodsQuantity`、`skuName`、`goodsCategory`、`goodsUrl`）に加え、購入者の氏名、電話番号、メールアドレス、完全な配送先住所 |
| `EWALLET` | 多くの場合追加は不要。購入者の電話番号を求めるもの、ウォレットアカウントのペア（`payMethodUserAccountType` + `payMethodUserAccountNo`）を求めるものがある |
| `ONLINE_BANKING`、`DIGITAL_BANKING` | 購入者の氏名と連絡先。これらの経路での**返金**では銀行口座情報が必要になることが多い |
| `VA`、`OTC` | 少数の集合 — 通常は購入者の姓と名 |
| `CREDITCARD`、`DEBITCARD` | `goodsInfo` からは不要。一部の市場では `payMethodProperties` 経由の国民識別番号 |

## これらのうち、実際に無条件で必須なのはどれですか？

単に必須であるフィールドに労力をかけないでください。`/api/v1/order/create` では、
`userInfo.userId`、`userInfo.userTerminal`、`orderDescription` がすべてのリクエストで必須です。
`userInfo.userEmail` は実質的に必須です。実際のアドレスを収集していない場合は、`userId@examples.com` の形式で
一意のフォールバック値を送信してください。共有値やプレースホルダー値はリスク管理に引っかかる可能性があるため、
決して使用しないでください。`goodsInfo` 内では、コンプライアンスとリスク審査のために、契約上 `goodsUrl` **または**
`appName` の**いずれか**（両方ではない）が期待されます。作成呼び出し自体はこれらの欠落を拒否しません。
拒否するのは決済手段の条件付きルールのみで、上記の不足フィールド一覧を通じて行われます。

## 決済手段ではなくシナリオによって決まる要件

*どのように*連携するかによって発生し、決済手段固有のルールが実行される前に検証されます。

| シナリオ | 追加で必須 |
| - | - |
| カードデータまたは `paymentTokenData` を API で直接渡す | `userInfo.userBrowserIp` と `userInfo.userAgent`、およびカードのフィールド — 番号、有効期限の月と年、CVV、カード名義人 |
| `merchantInitiatedMode` を設定 | `userPaymentAccessToken` |
| ホスト型モードでのエージェント決済 | `successRedirectUrl` |
| ステーブルコイン注文の返金 | `extendInfo` 内の `refundAddress` |

## 返金も同じ一覧を使用しますか？

いいえ。返金は独自の検証を行い、決済では決して必要としない本人確認情報や送金先情報を要求することがあります。
これは、資金が元の決済の取消ではなく送金によって戻されることが多いためです。そのため、返金リクエストは
`userInfo`（`userBankInfo` を含む）、`addressInfo`、`extendInfo` を受け付けます。送信して読み取るループは同じです。

## フィールドは存在しているのに拒否されます。なぜですか？

書式ルールは、要求されたかどうかにかかわらず、送信するすべてのフィールドに適用されます。

| フィールド | ルール |
| - | - |
| 任意の文字列フィールド | 空文字列は「未指定」として正規化されます。`""` を送信することは省略と同じであり、不足フィールドの要件を満たしません |
| `userPhone` | `+CountryCode-Number`、例：`+62-08990013157` — `+` で始まり `-` を含む必要があります |
| `userEmail` | 有効なメールアドレスである必要があります。無効なものは `A0003` では**ない**唯一の書式エラーで、`B0007 Invalid email format` として返されます |
| `goodsQuantity` | 整数、または数値文字列。それ以外は解析時に拒否されます |
| `userBirthDay`、`userIDIssueDate`、`userIDExpiryDate` | `dd/MM/yyyy` |
| `addressCountryCode`、`nationality` | 認識される ISO 国コード |
| `userIDType` | 現在は `ID` |

長さ制限はこれとは別で、アクワイアリング仕様にフィールドごとに記載されており、
同様にフィールド名を含む `A0003` を発生させます。

***

レスポンスが要求したとおりに再送信しても、まだブロックされますか？
`paymentRequestId` と完全な `A0003` メッセージを添えて
[サポートにお問い合わせください](mailto:support@waffo.com)。


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