- Payin 契約と取引上限 — Service → Payin で Portal が描画する同じ設定：すべての列、手数料の表記、契約ステータス、フィルター、エクスポート。
- 上限、通貨、設定エラー —
A0008/A0020/A0021がそれぞれどの上限を指すのか、また日次上限の計算方法。 - 条件付き必須項目 — どの決済手段に対して、どの注文作成項目が必須になるか。
アカウントで利用できる決済手段を、コードからどう調べますか？
/api/v1/paymethodconfig/inquiry を呼び出します。意味のある項目は 1 つです。
レスポンスは加盟店 ID と
payMethodDetails で、アカウントで現在有効な決済手段の契約 1 件につき 1 エントリの配列です。
このエンドポイントを、自社のインテグレーションロジック — どの決済手段を提示するか、どの通貨を受け付けるか、注文作成前に
どの金額範囲で検証するか — の正となる情報源として扱ってください。仕様書から一度コピーしたリストをハードコードしないでください。
レスポンスの各項目は何を意味しますか？
最初から組み込んでおく価値のある解析ルールが 2 つあります。
- 金額は数値ではなく文字列です。 小数として解析してください。JSON ライブラリに浮動小数点数へ変換させないでください。
orderAmountMin/orderAmountMaxは存在しないことがあります。 契約に範囲が設定されていない場合、項目は単に 設定されず、その契約には金額範囲のチェックが適用されません。
同じ決済手段が複数回現れるのはなぜですか？
配列のキーが決済手段ではなく契約だからです。有効な契約ごとに 1 エントリが出力され、1 つの決済手段が正当に複数の契約の 下にあることがあります：通貨ごとに 1 つ、あるいは Payin プロダクトごとに 1 つ、という形です。 したがって、このレスポンスでpayMethodName は一意のキーではありません。参照テーブルを作る場合は、実際に必要な組み合わせ —
通常は payMethodName + currency、または productName + payMethodName + currency — をキーにしてください。
レスポンス内で重複排除は行われません。
currentStatus が空で返ってきました。決済手段が停止しているのですか？
いいえ — 空の currentStatus は「利用不可」ではなく、**「今は不明」**を意味します。
契約データとリアルタイムの利用可否は、2 つの異なる場所から来ます。契約の側は常に存在します。利用可否の側は別途参照され、
その参照がある契約をカバーしていない場合、そのエントリの currentStatus、fixedMaintenanceRules、
fixedMaintenanceTimezone は推測されるのではなく、いずれも未設定のままになります。
扱い方：
最後の行が最も重要です。「空」を「オフ」と読むクライアントは、利用可否の参照が一瞬不調になった途端、正常に動いている決済手段を
非表示にしてしまいます。「この決済手段はこの支払いを処理できるか」に対する正式な回答は、常に注文作成のレスポンスです。
終了した契約もレスポンスに含まれますか？
いいえ。このエンドポイントの背後にあるクエリは、ACTIVE ステータスでありかつ有効期間が現在時点をカバーする契約 —
開始日が現在以前で、終了日が現在以降であるか終了日がまったくない契約 — のみを選択します。
帰結：
INIT、SUSPENDED、TERMINATED、ON_BOARDINGステータスの契約は現れません。- まだ開始していない契約、または終了日が過ぎた契約は現れません。
- したがって、レスポンスから決済手段が消えるのは契約イベントであり、利用可否の一時的な変動ではありません。
契約はあるが一時的に使えない決済手段は、
currentStatusが0の状態でレスポンスに残ります。
currentStatus です。一方をもう一方の答えに使わないでください。
Portal が表示する契約ステータスについては
Payin 契約と取引上限 に記載されています。
4 つの refundAllowed の値は何を意味しますか？
これらは決済手段が許可する返金の形を表すものであり、特定の注文が今すぐ返金できるかどうかを表すものではありません。
Portal は同じ 4 つの値を、No、Only Full Refund、Full Refund or One-time Partial Refund、
Full Refund or Multiple Partial Refunds として表示します。
この値が教えてくれないことが 2 つあります。
- 返金の受付期間がまだ開いているかどうか。 これは別の設定です。 決済手段ごとの返金と上限 を参照してください。
- 注文が返金可能な状態かどうか。 未払いの注文やすでに全額返金済みの注文は、
refundAllowedに関係なく拒否されます。
fixedMaintenanceRules とは何ですか？どう読めばよいですか？
決済手段の予定された利用不可時間帯です。各ルールは cron 式のペア startRule と endRule で、時間帯の開始と終了を示します。
fixedMaintenanceTimezone はそれらが評価されるタイムゾーンです — お客様のタイムゾーンとは異なることが多いので、
想定せずに読んでください。
典型的な形：
これらは事前にわかっているため、UI で有用に先回りできる唯一の利用可否情報です。予定外の障害は代わりに
currentStatus が
0 として現れ、事前の予告はありません。
注文を作成する前に金額範囲を確認するにはどうすればよいですか？
一致するエントリからorderAmountMin と orderAmountMax を読み取ってください — 決済手段と通貨で一致させます。
範囲は契約ごとであり、同じ決済手段の下でも通貨が 2 つあれば範囲が異なることがあるためです。
クライアント側で検証すれば顧客が注文を拒否される事態を防げますが、上限はこれだけではありません。3 つの独立した上限があり、
3 つの異なるエラーコードがあり、このエンドポイントが公開するのは最初の 1 つだけです。
これらは独立しています：決済手段の範囲を通過したことはアカウントレベルの上限について何も意味せず、その逆も同じです。
日次合計の計算方法や余力が戻るタイミングを含む完全な説明は
上限、通貨、設定エラー にあります。
加盟店 ID に言及するパラメーターエラーが返されました。何が問題ですか？
署名を必要とするすべてのエンドポイントは、リクエストボディのmerchantId を、署名に使った API キーが属する
加盟店 ID と照合します。異なる場合、他の処理が始まる前にリクエストは拒否され、理由
mid in params is inconsistent with apiKey が A0003 の下で返されます。
これが汎用的なパラメーターエラーではなく専用のメッセージになっているのは意図的です。その 2 つの原因が、他のどのパラメーター問題とも
大きく異なるためです。
加盟店 ID が存在しないことを意味することは決してなく、リトライで解決することも決してありません。
A0003 が返ってきました。どの項目が誤っていたかをどう調べますか？
コードだけでなくメッセージを読んでください。A0003 に限っては、具体的な理由が汎用メッセージの後ろに括弧で追記されます。
A0003 は HTTP 400 とともに返ります。
エラー処理における 2 つの含意：
- コードだけでなくメッセージ全体をログに記録してください。
A0003しか記録しないログ行は、バグを特定できる唯一の部分を捨てています。 - 括弧内のテキストをプログラムで解析しないでください。 ログを読む人間のために書かれたものです。分岐はコードで行い、テキストは表示に使ってください。
A0003 以外のコードは、追加の文脈を持つと定義された特定の失敗を除き、標準のメッセージのみを追記なしで返します。
コールバック URL のルールは何ですか？
notifyUrl — Waffo が決済通知を POST する URL — は設定時に検証され、失敗の種類ごとに固有のエラーがあります。
いずれも
A0003 の下で返され、上記のとおり具体的な理由がメッセージに含まれます。
人がつまずくのは最後の 2 つです。非 ASCII 文字を含む URL — 国際化ドメイン名や、文書から貼り付けたパスセグメント — は、
ブラウザなら開けるものであっても拒否されます：先にパーセントエンコードしてください。また、コピー時に紛れ込んだ末尾の空白だけで
空白チェックに失敗し、URL 自体の問題であるかのようなエラーになります。
notifyUrl を空のままにすることは許可されています。検証は実行されず、通知も送信されません。
subscriptionManagementUrl は送る必要がありますか？どこで使われますか？
サブスクリプション作成時に必須として文書化されており、256 文字が上限です — ただし、現在の作成呼び出しが強制するのは
文字数だけであり、これを含まないリクエストが拒否されることはありません。それでも必須として扱ってください。
ある 1 つのアカウント設定（後述）では、これが顧客が受け取る唯一の管理リンクになるからです。何のためのものか、そして
アプリのディープリンクではなくデスクトップブラウザで開くページであるべき理由は
サブスクリプション FAQ で説明しています。
そのページが扱っていないのは、顧客が実際にどの管理リンクを受け取るかです。これはアカウントレベルの設定で、2 つの値があります。
2 つの帰結：
MERCHANT_API_URLでは、お客様の値がそのままリンクになります。 送信していない場合、または送信したページがその後移動した場合、 顧客のメール内のリンクは壊れ、それを補うものは何もありません。サブスクリプション照会で読み戻して、保存されている値を確認してください。INTERNALでは、古いメールのリンクは動作しなくなります。 新しいメールごとに新しいリンクが生成され、以前のものは無効化されるため、 先月のメールを掘り起こした顧客には最新のものが必要になります。生成されたリンクにはそれ自体にも有効期限があります。
取引と返金のエクスポートで、どの列が変わりましたか？
3 つの変更があり、そのうち 1 つは誤読しやすいものです。
罠は 3 行目です。
Merchant Original Order ID は共有の列セットに定義されていますが、取引エクスポートからは意図的に除外されています —
返金行でのみ意味を持ち、そこでは返金に対するお客様の ID と、それが取り消す決済に対するお客様の ID を区別します。
取引エクスポートのパーサーがこれを探していても、見つかりません。
Initiation Type について：しばしば空になります。その理由と、何が値を埋めるかは
取引・返金の項目リファレンス にあります。
エクスポートは即時ダウンロードではなくキューに入るバックグラウンドタスクです —
エクスポートとレポートのダウンロード を参照してください。
チャージバックや返金の一覧を、1 つのサブスクリプションや 1 つの注文に絞り込めますか？
はい。以下は最も見落とされがちなフィルターです。merchantOriginalOrderId は、顧客が購入に異議を申し立てていて、お客様自身の注文参照しかわからない場合に使うものです：
Waffo の識別子を先に調べることなく、お客様の注文 ID からその決済に対するすべての返金へ直接たどり着けます。
名前に注意してください。フィルターは subscriptionId ではなく relatedSubscriptionId です —
絞り込まれる行が、サブスクリプション自体ではなく、サブスクリプションから生じたチャージバック、返金、決済だからこその
「related」です。サブスクリプションそのものを一覧表示するには、サブスクリプション一覧を acqSubscriptionId または
merchantSubscriptionId で絞り込んでください。
顧客が古いチェックアウトリンクを開き直しました。何が表示されますか？
チェックアウトリンクはセッションであり、セッションは永遠には続きません。2 つの異なる有効期間が適用されます。- 支払い前、リンクは作成から限られた期間有効です。それを過ぎて開かれた場合、支払いを受け付けるのではなく、 チェックアウトが期限切れであると表示します。
- 注文が最終状態に到達した後、リンクは決済ページではなく結果ページになり、完了後の一定期間は閲覧できますが、 その後は閲覧できなくなります。