本番環境の公開鍵を自分で追加できますか？
はい。Settings → Integration の Merchant Sign Configuration Details テーブルの上に Configure ボタンがあります。誰かにファイルをメールで送ることなく、Portal からご自身で鍵を提出できます。 セルフサービスでの提出と Waffo による審査は、どちらか一方ではなく、両方が行われます。確認時にダイアログが明示的に表示します。提出後は審査プロセスに入ります。鍵は直ちにPending の新バージョンとして登録され、Active になった時点で利用可能になります。その間も既存の鍵がトラフィックの検証を継続するため、提出によって稼働中の決済が中断されることはありません。
公開鍵フィールドは正確には何を受け付けますか？
厳密です。ダイアログには必要な長さに対する文字数カウンターがリアルタイムで表示されるため、提出前に判断できます。
392 は目安ではありません。入力がちょうどその長さになった時点でのみフィールドの検証が通り、それを超えるとカウンターが赤くなります。実務上の意味は次のとおりです。PEM ファイルの 1 行の Base64 本体だけを取り出し、それ以外は含めないでください。 PEM ファイルをそのまま貼り付けると、ヘッダー、フッター、改行のために長さが合いません。本番稼働チェックリストには PEM をこのフィールドが求める値まで削る方法が、認証と署名 FAQには鍵ペアを生成する
openssl コマンドが記載されています。
検証からは 3 種類の異なる拒否が返され、上記のどれに失敗したかが分かります。長さの不一致、不正な文字（有効な Base64 ではないもの — 多くは余分なスペースやラッパー行）、そしてアルゴリズムの不一致（有効な Base64 文字列だが、2048 ビットの RSA 公開鍵ではまったくないもの）です。
Portal がチャレンジ文字列への署名を求めるのはなぜですか？
アップロードする公開鍵とペアになる秘密鍵を保持していることを証明するためです。これがなければ、フォームにアクセスできる誰でも、自分が管理していない鍵を登録できてしまいます。 ダイアログ内の流れは次のとおりです。- 公開鍵を貼り付けます。まず形式チェックが行われます。
- 通過すると、Ownership Verification セクションが表示され、
WAFFO_VERIFY_{your merchant ID}の形式のチャレンジ文字列がコピーボタン付きで示されます。 - その文字列を、貼り付けた公開鍵とペアになる秘密鍵で SHA256withRSA を使ってローカルで署名し、結果を Base64 エンコードします。
- 署名を Signature Result に貼り付けます。
3 つの API 操作タイプとは何ですか？
操作タイプは、鍵ペア — およびそれと共に発行される API キー — を何に使うことが許されるかの範囲を定めます。ダイアログには 3 つのボタンがあります。
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 になれるため、これによりクリーンなローテーションが可能になります。
- 新しい鍵ペアを生成します。古い鍵はそのまま使い続けます。
- Portal から新しい公開鍵を提出します。
Pendingの新バージョンとして表示されます。トラフィックは引き続き古い鍵で検証され、影響を受けません。 Activeになったら、Merchant Sign Configuration Details テーブルからその API キーを読み取ります。- 連携側で、
X-API-KEYと署名用秘密鍵を 1 つの変更として同時に切り替えます。両者はセットです。片方だけを入れ替えるとA0002になります。 - 新しい認証情報でトラフィックを確認したうえで、古いものの使用を停止します。
Active なので、どちらの認証情報も使えない時間帯を生じさせずに、サービス単位で切り替えたりカナリアを実行したりできます。また両者は対応するペアなので、ロールバックはヘッダーと秘密鍵を元に戻すだけです。
ステップ 3 を飛ばさないでください。新しく提出した公開鍵に既存の API キーを使い回すことが、ローテーション失敗の最も多い原因です — 古い API キーは依然として古い公開鍵を指しているため、Portal 上ではすべて正しく設定されているように見えながら、新しい署名は検証に失敗します。
同じ公開鍵を 2 回提出できますか？
いいえ。同じ操作タイプの下で既に登録されている公開鍵は、重複バージョンを作成せずに拒否されます。これは、既に使用中の鍵へ誤って「ローテーション」してしまうこと — ローテーションが成功したように見えながら何も変わらない状態 — を防ぐためのガードです。 同じ鍵を別の操作タイプの下で提出することは可能ですが、スコープごとに別の鍵ペアを用意するほうが望ましい方法です — スコープを分ける目的がそこにあります。保持できる鍵の数に上限はありますか？
はい。操作タイプごとに上限があり、それを超える提出は専用のエラーで拒否されます。この件数には拒否されたバージョンも含まれるため、放置した試行も枠を消費します。上限に余裕を持つための習慣は 2 つです。探索的ではなく計画的にローテーションすること、そして拒否された提出の原因を修正してから再提出することです。過去の提出と、拒否された理由はどこで確認できますか？
同じページの設定テーブルの下にある Historical Versions です。各行が 1 回の提出に対応します。
拒否は最終ではなく、試行回数の上限もありません。理由を読み、修正し、新しいバージョンとして再提出してください。一覧は新しいものから順にページ分割されるため、長いローテーション履歴も読みやすい状態が保たれます。
鍵がアクティブ化または拒否されたとき、誰に通知されますか？
アカウントの 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 を紐付けています。
URL の列は鍵情報ではなく設定であり、審査なしに変更できます — 検証ルールと範囲については Portal セルフサービスのセキュリティ設定を参照してください。カード情報収集用のクライアント側認証情報を保持している場合は、このテーブルに独立した行として表示されます。
ローテーション後も署名が失敗し続けますか？認証と署名 FAQの
A0002 チェックリストを順に確認してください — ローテーション後の失敗では、原因はほぼ常に、対応しなくなった API キーと秘密鍵の組み合わせです。