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

# 決済手段の設定を読む

> アカウントで利用できる決済手段をプログラムから把握する方法：決済手段設定レスポンスのすべての項目、currentStatus が空で返ることがある理由、4 つの refundAllowed コードの意味、加盟店 ID や notifyUrl を名指しするパラメーターエラー、そして変更されたエクスポート列と一覧フィルター。

このページは **API の契約**についてです：コードから決済手段の設定をどう読み取るか、そして設定項目が誤っているときに
返されるリクエストレベルのエラーについて説明します。

隣接する 3 つのページが同じ主題を別の角度から扱っており、このページはそれらを繰り返しません。

* [Payin 契約と取引上限](/docs/ja/support/payin-agreements-and-limits-faq) —
  **Service → Payin** で Portal が描画する同じ設定：すべての列、手数料の表記、契約ステータス、フィルター、エクスポート。
* [上限、通貨、設定エラー](/docs/ja/support/error-codes-and-limits-supplement) —
  `A0008` / `A0020` / `A0021` がそれぞれどの上限を指すのか、また日次上限の計算方法。
* [条件付き必須項目](/docs/ja/support/conditional-required-fields-faq) —
  どの決済手段に対して、どの注文作成項目が必須になるか。

## アカウントで利用できる決済手段を、コードからどう調べますか？

`/api/v1/paymethodconfig/inquiry` を呼び出します。意味のある項目は 1 つです。

| 項目 | 必須 | 備考 |
| - | - | - |
| `merchantId` | はい | 署名に使った API キーが属する加盟店 ID と同じでなければなりません — [後述の加盟店 ID エラー](#i-got-a-parameter-error-that-mentions-my-merchant-id-what-is-wrong) を参照 |

レスポンスは加盟店 ID と `payMethodDetails` で、**アカウントで現在有効な決済手段の契約 1 件につき 1 エントリ**の配列です。

このエンドポイントを、自社のインテグレーションロジック — どの決済手段を提示するか、どの通貨を受け付けるか、注文作成前に
どの金額範囲で検証するか — の正となる情報源として扱ってください。仕様書から一度コピーしたリストをハードコードしないでください。

## レスポンスの各項目は何を意味しますか？

| 項目 | 意味 |
| - | - |
| `productName` | 契約が属する Payin プロダクト：`ONE_TIME_PAYMENT`、`DIRECT_PAYMENT`、`SUBSCRIPTION`、`MINI_PROGRAM_PAYMENT` |
| `payMethodName` | 決済手段の名称。注文作成時に送り返す綴りそのもの |
| `country` | 決済手段の国。3 文字コード。国ではない値が 2 つあります：ヨーロッパ市場のグループを表す `EU_LIST` と、市場に紐づかない決済手段の `GLB` |
| `payMethodType` | 決済手段が属するカテゴリ。例：`EWALLET`、`CREDITCARD`、`ONLINE_BANKING` — [完全な一覧](/docs/ja/support/payment-method-coverage-faq#what-are-the-paymethodtype-categories) |
| `currency` | この契約がサポートする通貨。ISO 4217 コード |
| `orderAmountMin` / `orderAmountMax` | この契約が受け付ける注文金額の範囲。小数の文字列 |
| `refundAllowed` | この決済手段が許可する返金の形 — [4 つのコード、後述](#what-do-the-four-refundallowed-values-mean) |
| `currentStatus` | リアルタイムの利用可否：`1` 利用可、`0` 利用不可。**空になることがあります** — 後述 |
| `fixedMaintenanceRules` | 予定されたメンテナンス時間帯。cron 式のペアで表現 |
| `fixedMaintenanceTimezone` | メンテナンスの cron 式が評価されるタイムゾーン。例：`UTC+08:00` |

最初から組み込んでおく価値のある解析ルールが 2 つあります。

* **金額は数値ではなく文字列です。** 小数として解析してください。JSON ライブラリに浮動小数点数へ変換させないでください。
* **`orderAmountMin` / `orderAmountMax` は存在しないことがあります。** 契約に範囲が設定されていない場合、項目は単に
  設定されず、その契約には金額範囲のチェックが適用されません。

## 同じ決済手段が複数回現れるのはなぜですか？

配列のキーが決済手段ではなく**契約**だからです。有効な契約ごとに 1 エントリが出力され、1 つの決済手段が正当に複数の契約の
下にあることがあります：通貨ごとに 1 つ、あるいは Payin プロダクトごとに 1 つ、という形です。

したがって、このレスポンスで `payMethodName` は一意のキーでは**ありません**。参照テーブルを作る場合は、実際に必要な組み合わせ —
通常は `payMethodName` + `currency`、または `productName` + `payMethodName` + `currency` — をキーにしてください。

レスポンス内で重複排除は行われません。

## `currentStatus` が空で返ってきました。決済手段が停止しているのですか？

いいえ — 空の `currentStatus` は「利用不可」ではなく、\*\*「今は不明」\*\*を意味します。

契約データとリアルタイムの利用可否は、2 つの異なる場所から来ます。契約の側は常に存在します。利用可否の側は別途参照され、
その参照がある契約をカバーしていない場合、そのエントリの `currentStatus`、`fixedMaintenanceRules`、
`fixedMaintenanceTimezone` は推測されるのではなく、いずれも未設定のままになります。

扱い方：

| `currentStatus` | 意味 | 妥当な挙動 |
| - | - | - |
| `1` | 利用可 | その決済手段を提示する |
| `0` | 現在利用不可 | 非表示にするか、一時的に利用不可として表示する |
| 空 / なし | 利用可否を判定できなかった | **利用不可として扱わないでください。** 通常の挙動にフォールバックし、注文作成を正とする |

最後の行が最も重要です。「空」を「オフ」と読むクライアントは、利用可否の参照が一瞬不調になった途端、正常に動いている決済手段を
非表示にしてしまいます。「この決済手段はこの支払いを処理できるか」に対する正式な回答は、常に注文作成のレスポンスです。

## 終了した契約もレスポンスに含まれますか？

いいえ。このエンドポイントの背後にあるクエリは、**`ACTIVE` ステータス**であり*かつ*有効期間が現在時点をカバーする契約 —
開始日が現在以前で、終了日が現在以降であるか終了日がまったくない契約 — のみを選択します。

帰結：

* `INIT`、`SUSPENDED`、`TERMINATED`、`ON_BOARDING` ステータスの契約は現れません。
* まだ開始していない契約、または終了日が過ぎた契約は現れません。
* したがって、レスポンスから決済手段が消えるのは**契約**イベントであり、利用可否の一時的な変動ではありません。
  契約はあるが一時的に使えない決済手段は、`currentStatus` が `0` の状態でレスポンスに残ります。

つまり、このレスポンスでは 2 つの問いに 2 つの異なる答えがあります：\*「契約しているか？」\*はエントリが存在するかどうか、
\*「今すぐ支払いを受け付けられるか？」\*は `currentStatus` です。一方をもう一方の答えに使わないでください。

Portal が表示する契約ステータスについては
[Payin 契約と取引上限](/docs/ja/support/payin-agreements-and-limits-faq) に記載されています。

## 4 つの `refundAllowed` の値は何を意味しますか？

これらは決済手段が許可する返金の**形**を表すものであり、特定の注文が今すぐ返金できるかどうかを表すものではありません。

| コード | 意味 | 返金呼び出しの結果 |
| - | - | - |
| `0` | この決済手段では返金は許可されていません | いかなる返金も拒否されます |
| `1` | 全額返金を 1 回のみ | 一部金額は拒否されます。2 回目の返金も拒否されます |
| `21` | 返金 1 回、全額または一部 | 一部返金は受理されますが、1 回のみです |
| `22` | 複数回の返金、全額または一部 | 元の金額を使い切るまで受理されます |

Portal は同じ 4 つの値を、*No*、*Only Full Refund*、*Full Refund or One-time Partial Refund*、
*Full Refund or Multiple Partial Refunds* として表示します。

この値が**教えてくれない**ことが 2 つあります。

* **返金の受付期間がまだ開いているかどうか。** これは別の設定です。
  [決済手段ごとの返金と上限](/docs/ja/support/payment-method-refund-limits-faq) を参照してください。
* **注文が返金可能な状態かどうか。** 未払いの注文やすでに全額返金済みの注文は、`refundAllowed` に関係なく拒否されます。

## `fixedMaintenanceRules` とは何ですか？どう読めばよいですか？

決済手段の**予定された**利用不可時間帯です。各ルールは cron 式のペア `startRule` と `endRule` で、時間帯の開始と終了を示します。
`fixedMaintenanceTimezone` はそれらが評価されるタイムゾーンです — お客様のタイムゾーンとは異なることが多いので、
想定せずに読んでください。

典型的な形：

| 開始 / 終了のペア | 時間帯 |
| - | - |
| `0 30 1 * * ?` / `0 30 2 * * ?` | 毎日 01:30 から 02:30 |
| `0 00 23 ? * 1,2,3,4,5` / `0 59 23 ? * 1,2,3,4,5` | 平日 23:00 から 23:59 |
| `0 00 0 1,15 * ?` / `0 59 23 1,15 * ?` | 毎月 1 日と 15 日の終日 |

これらは事前にわかっているため、UI で有用に先回りできる唯一の利用可否情報です。予定外の障害は代わりに `currentStatus` が
`0` として現れ、事前の予告はありません。

## 注文を作成する前に金額範囲を確認するにはどうすればよいですか？

一致するエントリから `orderAmountMin` と `orderAmountMax` を読み取ってください — 決済手段**と通貨**で一致させます。
範囲は契約ごとであり、同じ決済手段の下でも通貨が 2 つあれば範囲が異なることがあるためです。

クライアント側で検証すれば顧客が注文を拒否される事態を防げますが、上限はこれだけではありません。3 つの独立した上限があり、
3 つの異なるエラーコードがあり、このエンドポイントが公開するのは最初の 1 つだけです。

| コード | どの上限 | ここで読めるか |
| - | - | - |
| `A0008` | 決済手段自身の金額範囲 | はい — `orderAmountMin` / `orderAmountMax` |
| `A0020` | アカウントの取引ごとの上限（注文通貨ごと） | いいえ |
| `A0021` | アカウントの日次累計の上限（注文通貨ごと） | いいえ |

これらは独立しています：決済手段の範囲を通過したことはアカウントレベルの上限について何も意味せず、その逆も同じです。
日次合計の計算方法や余力が戻るタイミングを含む完全な説明は
[上限、通貨、設定エラー](/docs/ja/support/error-codes-and-limits-supplement) にあります。

## 加盟店 ID に言及するパラメーターエラーが返されました。何が問題ですか？

署名を必要とするすべてのエンドポイントは、**リクエストボディ**の `merchantId` を、**署名に使った API キー**が属する
加盟店 ID と照合します。異なる場合、他の処理が始まる前にリクエストは拒否され、理由
`mid in params is inconsistent with apiKey` が `A0003` の下で返されます。

これが汎用的なパラメーターエラーではなく専用のメッセージになっているのは意図的です。その 2 つの原因が、他のどのパラメーター問題とも
大きく異なるためです。

| 原因 | 見え方 | 修正 |
| - | - | - |
| 環境に対して誤った認証情報 | 本番の加盟店 ID に対してサンドボックスのキー、またはその逆 | キーと加盟店 ID を 1 つの環境に揃える |
| サブ加盟店の混同 | `merchantId` にサブ加盟店の ID を送っている | `merchantId` は API キーが属する ID です。サブ加盟店は専用の項目で識別します — [マルチブランドとサブ加盟店](/docs/ja/support/multi-brand-and-sub-merchant-faq) を参照 |
| アカウントをまたいだコピー＆ペースト | あるアカウントの設定と、別のアカウントのキー | 認証情報と ID をアカウントごとに 1 か所にまとめる |

加盟店 ID が存在しないことを意味することは決してなく、リトライで解決することも決してありません。

## `A0003` が返ってきました。どの項目が誤っていたかをどう調べますか？

コードだけでなくメッセージを読んでください。`A0003` に限っては、具体的な理由が**汎用メッセージの後ろに括弧で追記**されます。

```
Parameter validation failed ( refundAmount must be greater than 0 )
```

括弧の外は常に一定です。括弧の中が実際の問題 — 通常は問題の項目と、それに期待されていた内容 — を示します。
`A0003` は HTTP `400` とともに返ります。

エラー処理における 2 つの含意：

* **コードだけでなくメッセージ全体をログに記録してください。** `A0003` しか記録しないログ行は、バグを特定できる唯一の部分を捨てています。
* **括弧内のテキストをプログラムで解析しないでください。** ログを読む人間のために書かれたものです。分岐はコードで行い、テキストは表示に使ってください。

`A0003` 以外のコードは、追加の文脈を持つと定義された特定の失敗を除き、標準のメッセージのみを追記なしで返します。

## コールバック URL のルールは何ですか？

`notifyUrl` — Waffo が決済通知を POST する URL — は設定時に検証され、失敗の種類ごとに固有のエラーがあります。

| ルール | 失敗 |
| - | - |
| 最大 **512 文字** | `notify url exceeds maximum length of 512 characters` |
| `http://` または `https://` で始まること | `invalid notify url format` |
| URL 全体で **ASCII 文字のみ、空白なし** | `invalid notify url format` |
| スキームとホストの両方を持つ URL として解析できること | `invalid notify url format` |

いずれも `A0003` の下で返され、上記のとおり具体的な理由がメッセージに含まれます。

人がつまずくのは最後の 2 つです。非 ASCII 文字を含む URL — 国際化ドメイン名や、文書から貼り付けたパスセグメント — は、
ブラウザなら開けるものであっても拒否されます：先にパーセントエンコードしてください。また、コピー時に紛れ込んだ末尾の空白だけで
空白チェックに失敗し、URL 自体の問題であるかのようなエラーになります。

`notifyUrl` を空のままにすることは許可されています。検証は実行されず、通知も送信されません。

## `subscriptionManagementUrl` は送る必要がありますか？どこで使われますか？

サブスクリプション作成時に**必須として文書化**されており、**256 文字**が上限です — ただし、現在の作成呼び出しが強制するのは
文字数だけであり、これを含まないリクエストが**拒否されることはありません**。それでも必須として扱ってください。
ある 1 つのアカウント設定（後述）では、これが顧客が受け取る唯一の管理リンクになるからです。何のためのものか、そして
アプリのディープリンクではなくデスクトップブラウザで開くページであるべき理由は
[サブスクリプション FAQ](/docs/ja/support/subscription-faq) で説明しています。

そのページが扱っていないのは、**顧客が実際にどの管理リンクを受け取るか**です。これはアカウントレベルの設定で、2 つの値があります。

| 設定 | サブスクリプションのメールに含まれる管理リンク |
| - | - |
| `INTERNAL` | Waffo がホストする管理ページ。メールごとに生成されます |
| `MERCHANT_API_URL` | 作成時に送信した `subscriptionManagementUrl` そのもの |

2 つの帰結：

* **`MERCHANT_API_URL` では、お客様の値がそのままリンクになります。** 送信していない場合、または送信したページがその後移動した場合、
  顧客のメール内のリンクは壊れ、それを補うものは何もありません。サブスクリプション照会で読み戻して、保存されている値を確認してください。
* **`INTERNAL` では、古いメールのリンクは動作しなくなります。** 新しいメールごとに新しいリンクが生成され、以前のものは無効化されるため、
  先月のメールを掘り起こした顧客には最新のものが必要になります。生成されたリンクにはそれ自体にも有効期限があります。

いずれにせよ管理ページはリアルタイムの決済フローの一部ではありません — サブスクリプションの決済が成功した*後*に顧客を案内する場所です。
そもそもどのイベントでメールが送信されるかは
[サブスクリプションの通知](/docs/ja/support/subscription-notifications-faq) を参照してください。

## 取引と返金のエクスポートで、どの列が変わりましたか？

3 つの変更があり、そのうち 1 つは誤読しやすいものです。

| 列 | どこにあるか | 何を持つか |
| - | - | - |
| `Initiation Type` | 取引エクスポート | `CIT` または `MIT` — カード取引を誰が起動したか |
| `Pay Method Country/Region` | 取引エクスポート | 決済手段の国。**従来の `Country/Region` 列を置き換えます** |
| `Merchant Original Order ID` | **返金エクスポートのみ** | 返金行において、元の決済に対するお客様自身の注文 ID |

罠は 3 行目です。`Merchant Original Order ID` は共有の列セットに定義されていますが、**取引エクスポートからは意図的に除外**されています —
返金行でのみ意味を持ち、そこでは返金に対するお客様の ID と、それが取り消す決済に対するお客様の ID を区別します。
取引エクスポートのパーサーがこれを探していても、見つかりません。

`Initiation Type` について：しばしば空になります。その理由と、何が値を埋めるかは
[取引・返金の項目リファレンス](/docs/ja/support/transaction-field-reference-faq) にあります。

エクスポートは即時ダウンロードではなくキューに入るバックグラウンドタスクです —
[エクスポートとレポートのダウンロード](/docs/ja/support/export-center-faq) を参照してください。

## チャージバックや返金の一覧を、1 つのサブスクリプションや 1 つの注文に絞り込めますか？

はい。以下は最も見落とされがちなフィルターです。

| 一覧 | フィルター | 照合 |
| - | - | - |
| チャージバック | `relatedSubscriptionId` | 1 つのサブスクリプションから生じたすべてのチャージバック |
| 返金 | `relatedSubscriptionId` | 1 つのサブスクリプションから生じたすべての返金 |
| 返金 | `merchantOriginalOrderId` | 元の決済に対するお客様自身の注文 ID の**完全一致** |
| 取引 | `relatedSubscriptionId` | 1 つのサブスクリプションに属するすべての決済 |

`merchantOriginalOrderId` は、顧客が購入に異議を申し立てていて、お客様自身の注文参照しかわからない場合に使うものです：
Waffo の識別子を先に調べることなく、お客様の注文 ID からその決済に対するすべての返金へ直接たどり着けます。

名前に注意してください。フィルターは `subscriptionId` ではなく `relatedSubscriptionId` です —
絞り込まれる行が、サブスクリプション自体ではなく、サブスクリプション*から生じた*チャージバック、返金、決済だからこその
「related」です。サブスクリプションそのものを一覧表示するには、サブスクリプション一覧を `acqSubscriptionId` または
`merchantSubscriptionId` で絞り込んでください。

## 顧客が古いチェックアウトリンクを開き直しました。何が表示されますか？

チェックアウトリンクは**セッション**であり、セッションは永遠には続きません。2 つの異なる有効期間が適用されます。

* 支払い前、リンクは作成から限られた期間有効です。それを過ぎて開かれた場合、支払いを受け付けるのではなく、
  チェックアウトが期限切れであると表示します。
* 注文が最終状態に到達した後、リンクは決済ページではなく**結果**ページになり、完了後の一定期間は閲覧できますが、
  その後は閲覧できなくなります。

どちらの期間も、顧客体験を組み立てる土台にすべきものではありません。顧客が完了した購入を確認する必要があるなら、
自社の記録から表示するか、領収書を送ってください —
[領収書の設定とダウンロード](/docs/ja/support/receipt-configuration-and-download-faq) を参照してください。
また、顧客が支払う必要があるなら、古いリンクを再送するのではなく新しい注文を作成してください。開き直されたリンクの先にある注文が
どうなるかは [チェックアウト注文のライフサイクル](/docs/ja/support/cashier-order-lifecycle-faq) で説明しています。

## 次にどこを見ればよいですか？

| 質問 | ページ |
| - | - |
| Portal での同じ設定を列ごとに | [Payin 契約と取引上限](/docs/ja/support/payin-agreements-and-limits-faq) |
| そもそも Waffo が何を取り扱っているか、および完全な項目一覧 | [どの決済手段と市場を受け付けられるか？](/docs/ja/support/payment-method-coverage-faq) |
| 各エラーコードがどの上限を指すか | [上限、通貨、設定エラー](/docs/ja/support/error-codes-and-limits-supplement) |
| ある決済手段がどの注文項目を必要とするか | [条件付き必須項目](/docs/ja/support/conditional-required-fields-faq) |
| 返金の受付期間と決済手段ごとの返金挙動 | [決済手段ごとの返金と上限](/docs/ja/support/payment-method-refund-limits-faq) |
| リクエストへの署名と、署名された加盟店 ID とは何か | [認証と署名](/docs/ja/support/auth-signature-faq) |
| 通知の配信、リトライ、再送 | [Webhook のイベントと再送](/docs/ja/support/webhook-events-and-resend-faq) |
| サブ加盟店の識別 | [マルチブランドとサブ加盟店](/docs/ja/support/multi-brand-and-sub-merchant-faq) |


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