> ## 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 操作タイプ

> 本番環境の公開鍵をご自身で提出・ローテーションする方法 — フィールドが受け付ける正確な形式、Portal がチャレンジ文字列への署名を求める理由、3 つの API 操作タイプの意味と Withdraw を単独にしなければならない理由、ローテーション中に新旧の鍵がどのように共存するか。

連携セキュリティに関する内容は、3 つのページに分かれています。

| 質問 | ページ |
| - | - |
| リクエストへの署名、レスポンスの検証はどう行いますか？`A0001` / `A0002` は何を意味しますか？ | [認証と署名 FAQ](/docs/ja/support/auth-signature-faq) |
| 通知 URL の設定と IP によるアクセス制限はどう行いますか？ | [Portal セルフサービスのセキュリティ設定](/docs/ja/support/portal-security-config-faq) |
| **本番環境**の公開鍵の提出やローテーションはどう行いますか？API 操作タイプとは何ですか？ | 本ページ |

## 本番環境の公開鍵を自分で追加できますか？

はい。**Settings → Integration** の *Merchant Sign Configuration Details* テーブルの上に **Configure** ボタンがあります。誰かにファイルをメールで送ることなく、Portal からご自身で鍵を提出できます。

セルフサービスでの提出と Waffo による審査は、どちらか一方ではなく、両方が行われます。確認時にダイアログが明示的に表示します。*提出後は審査プロセスに入ります*。鍵は直ちに `Pending` の新バージョンとして登録され、`Active` になった時点で利用可能になります。その間も既存の鍵がトラフィックの検証を継続するため、提出によって稼働中の決済が中断されることはありません。

| ステータス | 意味 |
| - | - |
| `Pending` | 提出済み、審査待ち |
| `Active` | 承認済み — リクエスト署名を検証中 |
| `Rejected` | 未承認。理由は該当バージョンに記録されます |

## 公開鍵フィールドは正確には何を受け付けますか？

厳密です。ダイアログには必要な長さに対する文字数カウンターがリアルタイムで表示されるため、提出前に判断できます。

| 要件 | 値 |
| - | - |
| アルゴリズム | SHA256withRSA |
| 鍵長 | RSA 2048 ビット |
| エンコーディング | Base64、X.509 |
| 文字列長 | ちょうど **392 文字** |
| ラッパー | なし — `BEGIN PUBLIC KEY` / `END PUBLIC KEY` の行は不要 |
| 空白 | なし — スペースも改行も不可 |

392 は目安ではありません。入力がちょうどその長さになった時点でのみフィールドの検証が通り、それを超えるとカウンターが赤くなります。実務上の意味は次のとおりです。**PEM ファイルの 1 行の Base64 本体だけを取り出し、それ以外は含めないでください。** PEM ファイルをそのまま貼り付けると、ヘッダー、フッター、改行のために長さが合いません。[本番稼働チェックリスト](/docs/ja/developer-docs/getting-started/go-live)には PEM をこのフィールドが求める値まで削る方法が、[認証と署名 FAQ](/docs/ja/support/auth-signature-faq)には鍵ペアを生成する `openssl` コマンドが記載されています。

検証からは 3 種類の異なる拒否が返され、上記のどれに失敗したかが分かります。**長さ**の不一致、**不正な文字**（有効な Base64 ではないもの — 多くは余分なスペースやラッパー行）、そして**アルゴリズム**の不一致（有効な Base64 文字列だが、2048 ビットの RSA 公開鍵ではまったくないもの）です。

## Portal がチャレンジ文字列への署名を求めるのはなぜですか？

アップロードする公開鍵とペアになる秘密鍵を保持していることを証明するためです。これがなければ、フォームにアクセスできる誰でも、自分が管理していない鍵を登録できてしまいます。

ダイアログ内の流れは次のとおりです。

1. 公開鍵を貼り付けます。まず形式チェックが行われます。
2. 通過すると、**Ownership Verification** セクションが表示され、`WAFFO_VERIFY_{your merchant ID}` の形式のチャレンジ文字列がコピーボタン付きで示されます。
3. その文字列を、貼り付けた公開鍵とペアになる**秘密鍵**で SHA256withRSA を使ってローカルで署名し、結果を Base64 エンコードします。
4. 署名を **Signature Result** に貼り付けます。

操作タイプ、有効な公開鍵、署名の 3 つがすべて揃うまで、Confirm は無効のままです。その後、提出した公開鍵で署名が検証されます — ペアが一致しない場合は提出時点で拒否されるため、審査後ではなく直ちに分かります。

チャレンジ文字列には、末尾の改行を付けずに**表示されたとおり正確に**署名してください。実際には正しい鍵ペアで不一致が起きる原因として、これが最も多いものです。

## 3 つの API 操作タイプとは何ですか？

操作タイプは、鍵ペア — およびそれと共に発行される API キー — を何に使うことが許されるかの範囲を定めます。ダイアログには 3 つのボタンがあります。

| ボタン | 範囲 |
| - | - |
| Payin | 決済、返金および関連する照会 API |
| Payout | Payout および送金 API |
| Withdraw | 出金 API |

**Payin と Payout を同時に**選択でき、Portal はそれを両方をカバーする 1 つの結合スコープとして登録します。その後テーブルには、2 行ではなく Payin-and-Payout の 1 行として表示されます。

## Withdraw を Payin や Payout と組み合わせられないのはなぜですか？

Withdraw は別の種類の操作だからです。ユーザーの資金を受け入れたり第三者に支払ったりするのではなく、ご自身の精算済み資金を外に移動させます。Waffo はこれを独立した認証情報に置くことで、チェックアウトや Payout サービスで使われる鍵が残高を外に移すために使われることを決してなくし、一方が漏洩しても他方に影響が及ばないようにしています。

ダイアログはこれを警告ではなく強制として実装しています。**Withdraw** を選択すると Payin と Payout が解除され、そのいずれかを選択すると Withdraw が解除されます。Withdraw を他と組み合わせられる選択肢はありません。そのため、API で出金を行う場合は**少なくとも 2 つの認証情報** — 決済トラフィック用と、出金専用の別のもの — を用意し、シークレットストア内の別々の場所に保管してください。

## ダウンタイムなしに鍵をローテーションするにはどうすればよいですか？

重要な仕組みは、**提出によって鍵がその場で編集されることは決してない**という点です。受理された提出はそれぞれ新しいバージョンを作成し、各バージョンには**独自の API キー**が割り当てられます。あるリクエストをどの公開鍵で検証するかは、そのリクエストの `X-API-KEY` で決まります — 1 つの API キーに 1 つの公開鍵です。

同じ操作タイプの下で複数のバージョンが同時に `Active` になれるため、これによりクリーンなローテーションが可能になります。

1. 新しい鍵ペアを生成します。古い鍵はそのまま使い続けます。
2. Portal から新しい公開鍵を提出します。`Pending` の新バージョンとして表示されます。トラフィックは引き続き古い鍵で検証され、影響を受けません。
3. `Active` になったら、*Merchant Sign Configuration Details* テーブルからその **API キー**を読み取ります。
4. 連携側で、`X-API-KEY` **と**署名用秘密鍵を 1 つの変更として**同時に**切り替えます。両者はセットです。片方だけを入れ替えると `A0002` になります。
5. 新しい認証情報でトラフィックを確認したうえで、古いものの使用を停止します。

ステップ 4 の間は両バージョンが `Active` なので、どちらの認証情報も使えない時間帯を生じさせずに、サービス単位で切り替えたりカナリアを実行したりできます。また両者は対応するペアなので、ロールバックはヘッダーと秘密鍵を元に戻すだけです。

ステップ 3 を飛ばさないでください。新しく提出した公開鍵に既存の API キーを使い回すことが、ローテーション失敗の最も多い原因です — 古い API キーは依然として古い公開鍵を指しているため、Portal 上ではすべて正しく設定されているように見えながら、新しい署名は検証に失敗します。

## 同じ公開鍵を 2 回提出できますか？

いいえ。同じ操作タイプの下で既に登録されている公開鍵は、重複バージョンを作成せずに拒否されます。これは、既に使用中の鍵へ誤って「ローテーション」してしまうこと — ローテーションが成功したように見えながら何も変わらない状態 — を防ぐためのガードです。

同じ鍵を*別の*操作タイプの下で提出することは**可能**ですが、スコープごとに別の鍵ペアを用意するほうが望ましい方法です — スコープを分ける目的がそこにあります。

## 保持できる鍵の数に上限はありますか？

はい。操作タイプごとに上限があり、それを超える提出は専用のエラーで拒否されます。この件数には拒否されたバージョンも含まれるため、放置した試行も枠を消費します。上限に余裕を持つための習慣は 2 つです。探索的ではなく計画的にローテーションすること、そして拒否された提出の原因を修正してから再提出することです。

## 過去の提出と、拒否された理由はどこで確認できますか？

同じページの設定テーブルの下にある **Historical Versions** です。各行が 1 回の提出に対応します。

| 列 | 内容 |
| - | - |
| Version | 操作タイプごとの `V1`、`V2`、… |
| API Operation Type | 提出時のスコープ |
| Merchant Public Key | マスク表示された鍵、コピー操作付き |
| Status | `Pending` / `Active` / `Rejected` |
| Submission Time | 提出日時 |
| Reject Reason | 拒否されたバージョンの理由 |
| Action | 拒否されたバージョンの **View Reason**。全文を開きます |

拒否は最終ではなく、試行回数の上限もありません。理由を読み、修正し、新しいバージョンとして再提出してください。一覧は新しいものから順にページ分割されるため、長いローテーション履歴も読みやすい状態が保たれます。

## 鍵がアクティブ化または拒否されたとき、誰に通知されますか？

アカウントの **Super Admin** ユーザーが、いずれの場合もメールを受け取ります。アクティブ化のメールには操作タイプとマスク表示されたアクティブ化済みの鍵が、拒否のメールには理由が記載されます。

鍵を提出する担当者が Super Admin のメールボックスを保持する人と異なる場合は、この点に備えてください — 提出者は Portal で結果を知り、メールは別の場所に届きます。転送されたメールを待つのではなく、Historical Versions を確認してください。

## サンドボックスでも公開鍵を設定する必要がありますか？

いいえ。設定することもできません。Configure ボタンと Historical Versions はサンドボックス以外でのみ表示されます — サンドボックスでは、サンドボックスのプロビジョニング時に Waffo が鍵ペアを生成し、その鍵情報は Integration ページに直接表示されるため、すぐに署名を始められます。

本番稼働時には 2 つの点に注意が必要です。

* **サンドボックスの鍵情報を本番環境で再利用しないでください。** 新しいペアを生成してください。本番環境の公開鍵は、ご自身が提出し、その秘密鍵をご自身だけが保持するものでなければなりません。
* **API ドメインと認証情報を同時に切り替えてください。** 各環境には固有の API アドレスと固有の API キーがあります。アドレスは、現在いる環境の Integration ページに表示されます。

## 本番環境の公開鍵はマスク表示なのに、サンドボックスの秘密鍵はマスク表示されないのはなぜですか？

両者は同じ種類の秘密情報ではないからです。本番環境ではページ上の鍵情報はデフォルトでマスク表示され、表示／非表示の切り替えができるため、画面共有や録画された通話で Integration ページを開いても露出しません。マスクを解除せずにコピー操作は常に利用できるため、シークレットストアに移すためだけに値を表示する必要はありません。

**本番環境の秘密鍵はこのページには決して表示されず**、表示されるべきでもありません — Waffo は保持していません。紛失した場合、Portal のいかなる操作でも復元できません。新しいペアを生成し、上記の手順でローテーションしてください。

## Merchant Sign Configuration Details テーブルには何が含まれますか？

保持している操作タイプごとに 1 行あり、認証情報とそれが使用する URL を紐付けています。

| 列 | 内容 |
| - | - |
| API Operation Type | この行のスコープ |
| Merchant Public Key | このスコープのリクエストを現在検証している公開鍵。マスク表示 |
| API Key | このスコープのリクエストで送信する `X-API-KEY`。マスク表示 |
| Refund Notify URL | **Edit** 操作付き |
| Chargeback Notify URL | **Edit** 操作付き |
| Tokenization Notify URL | **Edit** 操作付き |

URL の列は鍵情報ではなく設定であり、審査なしに変更できます — 検証ルールと範囲については [Portal セルフサービスのセキュリティ設定](/docs/ja/support/portal-security-config-faq)を参照してください。カード情報収集用のクライアント側認証情報を保持している場合は、このテーブルに独立した行として表示されます。

***

ローテーション後も署名が失敗し続けますか？[認証と署名 FAQ](/docs/ja/support/auth-signature-faq)の `A0002` チェックリストを順に確認してください — ローテーション後の失敗では、原因はほぼ常に、対応しなくなった API キーと秘密鍵の組み合わせです。


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