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

# Portal セルフサービスのセキュリティ設定

> 加盟店 Portal で API のセキュリティ設定を管理する方法：チャレンジ文字列の検証を伴う公開鍵の提出とローテーション、返金・チャージバック通知 URL の設定、IP ホワイトリストによる API アクセスの制限。

このページでは、**加盟店 Portal → Integration** でお客様自身が管理できるセキュリティ設定を説明します。
リクエスト署名の仕組みについては [認証と署名 FAQ](/docs/ja/support/auth-signature-faq) を参照してください。

## 加盟店 Portal で自分の公開鍵を追加・ローテーションできますか？

はい。本番環境の公開鍵は Integration ページからオンラインで提出します。提出のたびに、独自の API キーを持つ
**新しい**鍵レコードが登録されます — 既存の鍵をその場で編集するのではありません。提出は Waffo の審査を経ます。

| ステータス | 意味 |
| - | - |
| Pending | 提出済み、Waffo の審査待ち |
| Active | 承認済み — リクエスト署名の検証に使われます |
| Rejected | 承認されず — 修正して再提出できます |

鍵が有効化または却下されるとメールが届きます（却下のメールには理由が含まれます）。鍵をローテーションするには、
新しい公開鍵を提出し、Active になるのを待ってから、インテグレーションを新しい API キーに切り替えてください。

## 公開鍵の提出時にチャレンジ文字列への署名が必要なのはなぜですか？

アップロードする公開鍵とペアになる秘密鍵を実際に保持していることを証明するためです。Portal は
`WAFFO_VERIFY_{mid}` の形式の固定チャレンジ文字列を表示します。それを秘密鍵でローカルに署名し、署名を公開鍵とともに
提出してください。Waffo は受理する前に、提出された公開鍵で署名を検証します。

| 項目 | 要件 |
| - | - |
| 鍵の種類 | RSA 2048 ビット、X.509 形式、Base64 エンコード |
| 署名アルゴリズム | SHA256withRSA（RSASSA-PKCS1-v1\_5） |
| 署名のエンコード | Base64 |

同じ公開鍵を同じ加盟店に対して 2 回提出することはできません。

## API キーと公開鍵はいくつ持てますか？

各 API キーはちょうど **1 つ**の公開鍵に対応します。加盟店は API オペレーションタイプでスコープされた複数の API キーを保持できます。

| オペレーションタイプ | スコープ |
| - | - |
| `PAYIN_ONLY` | 決済、返金、照会の API |
| `PAY_OUT_ONLY` | 送金および振替の API |
| `PAYIN_AND_PAYOUT` | Payin と Payout のすべての API |
| `WITHDRAW` | 出金の API |

保持できる公開鍵の数にはオペレーションタイプごとの上限があります。ローテーション中に新旧の鍵を並行して有効に保つには
十分な数であり、上限に達すると Portal が通知します。この数には却下された提出も含まれるため、上限に近づいている場合は
放置した試行を整理してください。

## 返金とチャージバックの通知 URL はどこで設定しますか？

これも **加盟店 Portal → Integration** です。公開鍵とは異なり、通知 URL の変更に**承認は不要**です — URL が検証を通過すれば
即座に有効になります。検証ルール：URL は `http://` または `https://` で始まり、RFC 3986 に準拠し（スペースや非 ASCII 文字は不可）、
512 文字以内であること。項目を空にして保存すると設定が削除されます。

## API キーごとに異なる通知 URL を設定できますか？

いいえ。各 MID には全体で 1 つの Refund Notify URL と 1 つの Chargeback Notify URL があり、API オペレーションタイプごとに
保存されるわけではありません。Chargeback Notify URL はカード決済にのみ適用されます。出金の通知はこれらの設定を使いません：
出金の通知 URL は API リクエストで注文ごとに渡されます。

## API アクセスを自社サーバーの IP アドレスに制限するにはどうすればよいですか？

Portal で **IP ホワイトリスト**を有効にしてください — 任意の保護機能で、デフォルトはオフです。有効にすると、署名は有効だが
送信元 IP がホワイトリストにないリクエストはエラー `A0046`（「Access denied: the request IP is not in the whitelist」、HTTP 401）で
拒否されます。設定の変更は保存後まもなく有効になります — 保存時にキャッシュされた参照も無効化されるため、実務上はたいてい即時です。
有効にしていない加盟店には挙動の変化はありません。

ホワイトリストは署名検証の**後**に評価されるため、署名が誤っているリクエストは、その IP がリストにない場合でも
`A0046` ではなく署名エラー（`A0002`）で失敗します。

## IP ホワイトリストはどんな形式と上限をサポートしますか？

* エントリは **IPv4 アドレス**と **CIDR レンジ**を受け付けます（例：`203.0.113.7` や `198.51.100.0/24`）。
  IPv6 は現在サポートされていません。
* 加盟店あたり最大 **20 エントリ**。重複は拒否されます。
* 各エントリにはラベルを付けられ、個別にオン/オフを切り替えられます。
* 有効なエントリが 1 つもない状態ではホワイトリストをオンにできず、最後の有効なエントリを削除または無効化すると、
  マスタースイッチは自動的にオフになります。

## Waffo がリクエストの送信元 IP を判定できない場合はどうなりますか？

デフォルトでは、送信元 IP を判定できないリクエストは**許可**され、記録されます — ブロックされるのは、判定できて、かつ
ホワイトリストにない IP だけです。

Waffo はこのデフォルトより厳格な、あるいは緩やかな適用ポリシーもサポートしていますが、Portal が公開しているのは
マスターのオン/オフスイッチだけで、ポリシー自体は Waffo 側で設定されます。まず観測のみモードで運用したい場合や、
送信元 IP を判定できないリクエストもブロックしたい場合は、インテグレーションサポートにお問い合わせください。

## サインイン時の二段階認証チャレンジはどう機能しますか？

二段階認証は Integration の設定ではなく**サインイン**の制御です — アカウント側の疑問（誰が有効にできるか、
コードが届かないときどうするか）は [加盟店 Portal の運用](/docs/ja/support/portal-operations-faq) にあります。
仕組みとしては、ログイン呼び出しの*後*ではなく*最中*に確認されます。

1. 通常どおりサインインフォームを送信します。アカウントに確認済みの二段階認証方法がある場合、セッションは発行されません：
   サインインは**チャレンジが必要**というレスポンスで返り、コードはすでにアカウントのログインメールアドレスへ送信されています。
2. Portal は、そのサインイン試行に紐づく短命の再送トークンを持った *Verification* ダイアログを開きます。
3. コードを入力すると、Portal は今度はコードを添えて**同じサインイン**を繰り返します。そのときに初めてセッションが発行されます。

チャレンジの対象になるのはアカウントの**デフォルト**の方法だけです。誤ったコードや期限切れのコードはサインイン自体を失敗させます。
ダイアログがパスワードではなくコードの再入力を求めるのはこのためです。

## サインインページを開いたままにすると Resend が動かなくなるのはなぜですか？

その時点ではセッションがないため、Resend をセッションで認可することができません。認可はチャレンジとともに渡された
再送トークンによって行われます。そのトークンは単一のサインイン試行に属し、しばらくすると期限切れになります。
ページをリロードしたり新しい試行を開始したりすると破棄されます。Resend が失敗する場合は、もう一度サインインしてください —
新しいチャレンジと新しいトークンが発行されます。

## 二段階認証の各操作は実際に何をしますか？

以下はすべて、**Portal のセッション**で実行される Portal の操作です — API キーで署名する加盟店 API の一部ではなく、
インテグレーション用の鍵でスクリプト化することはできません。

| 操作 | 何をするか |
| - | - |
| **オン**にする（`Settings → Preference`） | メール方式のバインドを開始し、最初のコードを送信します |
| バインドダイアログ内の *Resend* | 同じバインドに対してもう一度コードを送信します |
| バインドダイアログ内の *Verify* | コードを確認し、バインドを完了します |
| **オフ**にする | 方式のバインドを解除します。アカウントのパスワードを求められます |
| サインインダイアログ内の *Resend* | 再送トークンを使い、現在のサインイン試行に対してもう一度コードを送信します |
| 操作者一覧の `2-Step Verification` 列（Admin） | 別の操作者に対してメール方式を有効化または無効化します |

知っておく価値のある帰結が 3 つあります。

* **バインドはコードが検証されて初めて成立します。** コード送信後にダイアログを閉じると、その試行は未確認のままで、
  二段階認証はオフのままです。トグルを再度オンにすると、新しいラウンドが始まります。
* **最初に確認した方式がデフォルトになります** — そしてサインインのチャレンジが使うのはそのデフォルトです。
* **オフにする操作はコードではなくパスワードで認可され**、サインインフォームのパスワードと同じ方法で暗号化されて送信されます。
  パスワードが誤っている場合は標準のパスワード誤りエラーが返り、方式はバインドされたままです。


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