このページはスコープ一覧とトリアージのフローチャートです — どの認証情報が
どのエンドポイントを呼び出せるのか、そして呼び出せないときに返されるエラーをどう読むかを説明します。
関係するキーはいくつあり、それぞれ誰が保持するのですか？
4 つあり、そのうちお客様が秘密に保つべきものは 2 つだけです。
運用上重要な関係は次の 1 点です。1 つの API キーは、ちょうど 1 つの公開鍵に対応します。
送信した
X-API-KEY によって、署名がどの公開鍵に対して検証されるかが決まります。
つまり API キーと秘密鍵はペアであり、片方だけを入れ替えると失敗します。
Integration ページに複数の API キーと公開鍵が表示されるのはなぜですか？どれを使えばよいですか？
認証情報はオペレーションの種類ごとにスコープが区切られており、利用する種類ごとに 1 つずつ保持するためです。 使うべき行は、API Operation Type が実行しようとしている呼び出しに一致するものです。 各種類がどのエンドポイントを正確にカバーするかは以下のとおりです。
この表から確定する 2 つの細部があります。
- 残高照会は Payout スコープと Withdraw スコープの両方に含まれます。 どちらの認証情報でも 到達できる唯一のエンドポイントであり、残高確認のためにスコープを追加する必要が生じないのはこのためです。
- アカウント履歴は Withdraw 専用です。 Payout の認証情報では読み取れません。
Payin のキーを Payout のエンドポイントで使ったら権限エラーになりました。なぜですか？
スコープは加盟店単位ではなく、リクエストパス単位で適用されるためです。認証情報自体は有効でしたが、 そのエンドポイントを呼び出す権限がなかっただけであり、リクエストはA0004 Permission denied（HTTP 401）で拒否されます。
デバッグ時に覚えておくべき区別は次のとおりです。A0004 は「このキーは正しいが、エンドポイントが違う」を意味します。
キーが間違っている、署名が間違っている、アカウントにその商品が含まれていない、という意味ではありません。
上の表でエンドポイントを探し、それを含むオペレーションタイプの認証情報の行を使用してください。
Withdraw を Payin や Payout と組み合わせられないのはなぜですか？両方必要なのですが。
出金はお客様自身の精算済み資金を外へ移動させる操作であり、Payin と Payout は顧客の資金を受け入れる、 または第三者へ支払う操作だからです。出金を独立した認証情報に分けておくことで、チェックアウトサービスや 送金サービスが保持するキーが残高の引き出しに使われることは決してなく、片方の漏洩が他方の漏洩を意味しなくなります。 Portal は警告ではなく強制でこれを実現します。Withdraw を選択すると Payin と Payout の選択が解除され、 Payin または Payout を選択すると Withdraw の選択が解除されます。 そのため、API 経由で出金を行う場合は、少なくとも 2 つの認証情報を用意してください — 決済トラフィック用に 1 つ、出金用に別途 1 つ — そして、シークレットマネージャー内では別の場所に、 異なるアクセスリストで保管してください。それが分離の目的であり、両方を同じ環境ファイルに置いてしまえば 分離の意味が失われます。2 つ目の認証情報の提出は、1 つ目と同じセルフサービスのフローです。 本番環境の公開鍵と API オペレーションタイプ を参照してください。API キー・スコープ・署名・IP はどの順序で確認されるのですか？
以下の順序です。この順序を知っていれば、複数の問題が同時にある場合にどのエラーが最初に返るかがわかります。X-API-KEYが存在するか？ なければ →A0001。- 既知の
Activeな認証情報か？ そうでなければ →A0001。 - その認証情報のオペレーションタイプがこのエンドポイントを許可しているか？ していなければ →
A0004。 X-SIGNATUREがその認証情報の公開鍵で検証できるか？ できなければ →A0002。- ホワイトリストを有効にしている場合、送信元 IP がリストに含まれているか？ 含まれていなければ →
A0046。
A0046 ではなく A0002 を返します。 したがって、A0046 を見たことがないからホワイトリストは問題ないと
結論づけないでください — 単に署名チェックを通過したことがないだけかもしれません。上記の順序でエラーを修正してください。
「invalid API key」と「invalid signature」の違いは何ですか？
同じペアの異なる半分を指しており、それぞれに固有の確認項目があります。
キーのローテーション後の
A0002 は、ほぼ常に X-API-KEY と署名用秘密鍵が対応しなくなったことを意味します —
両方を 1 回の変更として同時に切り替えてください。
「merchant status abnormal」や「contract does not allow this operation」は認証の問題ですか？
いいえ。これらはアカウントおよび契約の状態であり、認証情報が受理された後に返されます。
トリアージの近道：
A0001 / A0002 / A0004 / A0046 はすべてお客様自身で修正できる認証情報の問題です。
A0006、A0010、A0018 は*権限（エンタイトルメント）*の問題であり、Waffo 側での設定変更か、
別のリクエストが必要です。完全な一覧は
エラーコード を参照してください。
API バージョンヘッダーは必ず送信する必要がありますか？
はい。生の HTTP 呼び出しではX-API-VERSION: 1.0.0 を送信してください。SDK はこのヘッダーを
自動で管理するため、SDK 側では設定や上書きをしないでください。
変更履歴から誤解しやすいため、あえて挙げておく落とし穴があります。API バージョン履歴に表示される
バージョン番号はドキュメントおよび契約のリビジョンを識別するものであり、このヘッダーで送信してはいけません。
ヘッダーの値は 1.0.0 です。API 概要 を参照してください。
キーを有効化またはローテーションしてから、どれくらいで使えるようになりますか？
しばらくお待ちください — 即時ではありません。署名を検証できるのはActive な認証情報のみで、
リクエストパスで使われる参照は一定間隔で更新されます。そのため、Active になった直後のキーは短時間拒否される
ことがあり、逆に有効でなくなった直後のキーは同じ時間だけまだ使える場合があります。
ローテーションの手順としては、新しいバージョンが Active になった後、この時間が経過するまで待ってから
トラフィックを切り替え、新しい認証情報が実トラフィックで検証できるまで古い認証情報を残しておいてください。
複数のバージョンを同時に Active にできるため、どちらも使えない空白期間を作る必要はありません。
IP ホワイトリストの挙動はこれとは異なり、より速く反映されます — 後述を参照してください。
1 つの API キーを複数の加盟店アカウントで使えますか？
いいえ。各 API キーは 1 つの加盟店アカウントに属し、アカウント A の認証情報で認証されたリクエストは アカウント A のデータに対してのみ操作できます。アカウント B に属する注文を照会すると、キー自体は完全に有効でも失敗します。 複数の加盟店 ID を運用している場合は、アカウントごとに認証情報のセットを 1 つずつ保持し、常にそのオブジェクトを 作成したアカウントの認証情報で呼び出してください。このルーティングを最初から組み込んでおくほうが、後から 組み替えるよりはるかに低コストです。マルチブランドとサブ加盟店の構成 を参照してください。IP ホワイトリストにはどんな形式が登録でき、編集はどれくらいで反映されますか？
20 件では足りない場合は、個々のホストを列挙するのではなく CIDR レンジにまとめてください —
/24 1 つで
最大 254 件のエントリを置き換えられ、安定したレンジはスケールアウトのたびに変わるリストより保守も楽です。
有効化の方法と Portal の各項目は
Portal セルフサービスのセキュリティ設定 を参照してください。
サーバーがプロキシの背後にある、または動的 IP を使っています。実際には何が照合されるのですか？
照合されるアドレスは、リクエストが Waffo に到達した時点での forwarded-for チェーンの先頭エントリです — つまり最終ホップではなく、発信元クライアントのアドレスです。この値が IPv4 アドレスとして解釈できない場合、 チェックは「不一致」ではなく「判定不能」として扱われます。 この区別が結果を左右し、適用ポリシーは 3 種類あります。
Portal で操作できるのはマスターのオン/オフスイッチだけで、ポリシー自体は Waffo が設定します。
そのため、送信元 IP が動的、マルチリージョン、または多層構成のコンテナ環境の背後にある場合は、
まずインテグレーションサポートに観測のみへの設定を依頼し、記録された不一致を確認したうえで、
リストが完成してから強制に切り替えてください。何も確認せずに強制をオンにすることが、正しく設定された
インテグレーションが障害を起こす典型パターンです。
送信元 IP を一定のレンジに固定することが本当に不可能な場合、ホワイトリストはお客様に適した制御ではありません —
これは任意の機能でデフォルトはオフであり、署名検証はすべてのリクエストで既に必須になっています。
自分の送信元（egress）IP はどうやって調べればよいですか？
Waffo からは調べられません — Waffo が見るアドレスはお客様のインフラが提示するアドレスであり、 それを確実に知る情報源はお客様自身のプラットフォームです。クラウド環境の NAT ゲートウェイや ロードバランサーの設定であり、これが安定が保証される唯一の場所でもあります。 設定から取得できない場合の実務的な方法が 2 つあります。- 決済サービスが稼働する環境の egress レンジをプラットフォームチームに確認し、観測したアドレスではなく レンジをホワイトリストに登録してください。観測したアドレスは、次にスケールしたときに古くなります。
- 上述のとおりまず観測のみで運用し、何かがブロックされる前に、不一致の記録そのものからどのアドレスが 使われているかを把握してください。
Portal のパスワードは通信中に暗号化されていますか？Waffo のスタッフに見えますか？
パスワードは TLS に加えて、Waffo の公開鍵を使って送信前にブラウザ内で暗号化されます — そのため、 フォームが平文のパスワードを回線に載せることはなく、暗号化されたチャネルの中であっても平文は流れません。 パスワードの設定や変更時も同様です。 保存側では一方向ハッシュとしてのみ保持されるため、読み出せる復元可能なコピーは存在しません。 Waffo の誰もお客様のパスワードを取得できず、パスワードリセットでは旧パスワードを伝えるのではなく リンクが発行されます。 パスワードのルール、有効期限、ロックアウト、サインイン履歴については Portal サインイン、リンク、アカウント状態 と 加盟店 Portal の運用 を参照してください。秘密鍵が漏洩したかもしれません。何をどの順番で行えばよいですか？
まずローテーション、調査はその後です — そして、漏洩した秘密鍵があれば誰かがお客様として リクエストに署名できるということを忘れないでください。文字どおり深刻な事態です。- 新しいキーペアを生成し、Portal から新しい公開鍵を提出します。審査中も既存の認証情報は 引き続き動作するため、この手順でダウンタイムは発生しません。
- 新しいバージョンが
Activeになったら、Integration ページでその API キーを確認し、X-API-KEYと署名用秘密鍵を同時に切り替えます。 - 古い認証情報の使用を停止し、自社のログで古い API キーを付けたトラフィックが残っていないことを確認します。
- まだであれば IP ホワイトリストを有効にします。盗まれた認証情報をお客様のインフラ外から使えなくする 唯一の制御であり、必要になる前に設定しておくべき理由でもあります。
- 自社での取り扱いを見直します。秘密鍵をソース管理、イメージ、ログ、ブラウザに置いてはいけません。 本番稼働チェックリスト では、環境設定または 鍵管理サービスに保管することを求めています。
- インテグレーションサポートに、何がいつ起きたかを伝えます。Waffo 側で古い認証情報の アクティビティを確認できるようにするためです。
署名の問題をデバッグするために、リクエストとレスポンスのペイロードを記録してもよいですか？
はい。むしろ記録すべきです — ただし、パースして再シリアライズしたコピーではなく生のバイト列を 記録してください。JSON ライブラリを一往復させること自体が、署名が検証できない主要な原因の 1 つだからです。 記録すべきもの、記録してはいけないもの：
本番稼働チェックリストでは、2 列目は助言ではなく要件です。ログにキー全体や機密性の高い決済情報を
記録してはいけません。短期間かつアクセス制御されたデバッグ用の記録がこの用途に適した形であり、
恒久的なログ行にすべきではありません。