API キーの管理
決済作成用の API キーと、通知を検証する Webhook 署名鍵は用途が異なります。
| 秘密情報 | 用途 | 保管先 |
|---|---|---|
| 決済 API キー | x-stbl-api-key で加盟店サーバーを認証 | サーバーのシークレット管理基盤 |
| Webhook 署名鍵 | raw body の HMAC を検証 | サーバーのシークレット管理基盤 |
HTML、ブラウザ JavaScript、Git、アクセスログへ秘密情報を出さないでください。接続先の URL とキーを環境ごとにセットで管理し、接頭辞だけで本番・検証環境を判別しないでください。
決済 API キーの発行と失効
決済 API キーは 店舗ごとに、加盟店コンソールで発行・失効します。加盟店コンソールのメニューの「お店と QR コード」から対象のネットショップを開き、「組み込みの準備」タブの「お支払いを作るための鍵」で「API キーを発行」を押します（ラベルは任意で、64 文字までです）。
- 形式は
stblpay_に、43 文字の base64url が続く文字列です。 - 平文は、発行したときに一度だけ表示されます。 サーバーは SHA-256 のハッシュしか保存しないため、画面を閉じたあとは再表示できません。加盟店のサーバーにだけ保存してください。保存できなかったときは、そのキーを失効させて発行し直します。
- 一覧には、先頭と末尾だけのマスク表示、発行日時、最終利用日時が出ます。
- 有効なキーは 1 店舗あたり 10 本までです。 超えて発行しようとすると、409
store/api_key_limit_reachedになります。使っていないキーを失効させてから発行してください。 - 失効は一覧の「失効」から行います。失効はすぐに効き、取り消せません。 そのキーを使っているサーバーからの要求は、拒否されます。
- 店舗を「停止する」で停止している間も、API キーの発行と失効はできます。停止中は新しい決済を受け付けません。
- 加盟店が STBLpay によって利用停止されている間は、API キーの発行も失効もできません（加盟店の利用停止）。
1 店舗で複数のキーを持てるのは、決済を止めずにキーを入れ替えるためです。たとえば次の順で入れ替えます。
- 新しいキーを発行する。
- サーバーを新しいキーに切り替える。
- 古いキーの最終利用日時が更新されなくなったのを確かめてから、古いキーを失効させる。
1 本しか持てないと、入れ替えの間は決済を作れません。サーバーごとにキーを分けておけば、1 台のキーが漏れても、そのキーだけを失効させれば他のサーバーは止まりません。
更新と漏洩時
漏洩したキーは、「失効」で止めてから新しいキーを発行し、サーバーのキーを入れ替えます。利用状況（最終利用日時）と対象の注文を確認してください。発行と失効は、加盟店コンソールにログインした加盟店本人の操作です。決済 API キーではできません。
Webhook の署名鍵は、加盟店コンソールのメニューの「お店と QR コード」から対象のネットショップを開き、「組み込みの準備」タブの「お支払い完了のお知らせ先」で管理します。初回の設定時に一度だけ表示され、URL を変更しても変わりません。「署名鍵を作り直す」と、新旧 2 つの鍵が 24 時間有効になり、その間ヘッダに v1 が 2 個並びます。鍵の漏洩が疑われるときは、作り直しではなく「webhook を解除」してから設定し直します。送信先の URL と署名鍵は加盟店で 1 つなので、作り直しも解除も、すべてのネットショップの通知に効きます。手順は 署名検証を参照してください。