Stripe API キー設定（都度課金・Checkout 基盤）

Issue #2629 で導入した Stripe SDK と API キー管理の設定手順です。

前提

• カード情報（番号・CVC・有効期限）は自社サーバーを通過しません。 決済 UI は Stripe Checkout / Payment Element に委譲します（PCI DSS 対応）。
• API キーは wp-config.php の define() のみ が参照されます。テーマの config/local.env やシェル環境変数だけでは読み込まれません（IMAP の PWORLD_IMAP_* と同じパターン）。

wp-config.php に追加する定数

wp-settings.php より前に記述してください。

// Stripe Test mode（ローカル・ステージング）
define( 'STRIPE_SECRET_KEY', 'rk_test_...' ); // Restricted API key 推奨
define( 'STRIPE_PUBLISHABLE_KEY', 'pk_test_...' );
define( 'STRIPE_WEBHOOK_SECRET', 'whsec_...' ); // Webhook 実装（#2631）着手後に設定

// 本番（Live mode）では rk_live_* / pk_live_* に差し替え

STRIPE_SECRET_KEY には Restricted API key（rk_test_ / rk_live_）を推奨します。従来の Secret key（sk_test_ / sk_live_）も互換のため受け入れますが、通常運用では用途ごとに最小権限の Restricted API key を発行してください。

Checkout Session 作成用の Restricted API key には、少なくとも Checkout Sessions の書き込み権限が必要です。連携が利用する Prices / Products / Customers / Payment Links 等の追加 API がある場合は、Stripe Workbench のリクエストログと 403 エラーを確認し、必要な読み取り・書き込み権限だけを追加します。

定数名	用途	露出
STRIPE_SECRET_KEY	サーバー側 API 呼び出し（Checkout Session 作成等）	秘密（rk_* 推奨。リポジトリにコミットしない）
STRIPE_PUBLISHABLE_KEY	将来フロント連携用	公開可
STRIPE_WEBHOOK_SECRET	Webhook 署名検証（#2631）	秘密

定数名の正本: App\Constants\StripeConfigConstants

環境ごとの切り替え

環境	キー種別	備考
ローカル	Test (rk_test_ / pk_test_)	Stripe Dashboard → テストモード
ステージング	Test または Live（運用方針に従う）	ステージング用 wp-config に個別 define
本番	Live (rk_live_ / pk_live_)	本番 wp-config のみ。開発者 PC に live キーを置かない

テスト／本番の判定はキーのプレフィックス（rk_test_ / sk_test_ 等）から自動判定されます（StripeSettings::is_test_mode()）。

DI からの利用

// 例: 将来の Checkout Service から
$factory = $container->get( StripeClientFactoryInterface::class );
if ( $factory->is_available() ) {
    $client = $factory->create_client();
}

• 未設定時: is_available() は false、create_client() は RuntimeException
• DI 登録: core_src/config/di/commerce.php

関連

• Issue #2629 SDK 導入・API キー管理
• Issue #2630 Checkout セッション作成
• Issue #2631 Webhook 署名検証
• commerce-module.md
• Stripe Agent Skills（実装・レビュー時）: リポジトリ .agents/skills/stripe-best-practices（AGENTS.md 参照） / 照合結果