【ITニュース解説】Stripe test mode vs live mode: a 15-minute check before your first real payment

Stripeのテストモードとライブモードに関するニュース記事の解説を始める。システムエンジニアを目指す初心者にとって、Stripeのような決済システムは、開発したアプリケーションを実際に運用する上で非常に重要な要素だ。特に、テスト環境と本番環境の切り替えは、多くの開発者が間違いやすいポイントであり、この記事はその注意点を具体的に教えてくれる。

Stripeでは、アプリケーションに組み込む決済機能を開発し、テストするために「テストモード」、そして実際に顧客からお金を受け取るために「ライブモード」という二つの環境が用意されている。この二つの環境は完全に独立しており、決済を処理するために必要な「キー」、販売する「製品」や「価格」、決済完了などのイベントをアプリに通知する「Webhooks」、顧客が利用する「決済リンク」や「顧客ポータル」など、Stripeで扱う全ての要素がそれぞれテスト用とライブ用で別々に存在する。

多くの開発者が初めてアプリを公開する際に直面する問題は、このテストモードとライブモードの切り替えが不完全なことだ。開発中はテストモードで問題なく動作していても、本番環境に移行した際に、どこか一部の設定がテストモードのまま残ってしまうと、実際の顧客からの決済が失敗したり、顧客は支払いをしたのにアプリがその支払いを受け取ったと認識しないといった深刻なバグに繋がることがある。しかも、この手のバグは表面化しにくく、顧客からの問い合わせで初めて発覚することも少なくないため、リリース前にしっかり確認することが非常に重要になる。

まず確認すべきは、ライブサイトがどの「キー」を使っているかだ。Stripeのキーには大きく分けて二種類ある。「公開可能キー（Publishable key）」はフロントエンド、つまりユーザーが直接操作するウェブページなどに配置され、一般に公開されても問題ない。一方、「秘密キー（Secret key）」はサーバーサイド、つまりユーザーからは見えない裏側のシステムに厳重に保管されるべきもので、決して公開してはならない。これらのキーは、それぞれ「pk_test_」または「pk_live_」で始まる公開可能キー、「sk_test_」または「sk_live_」で始まる秘密キーとして、どちらのモードに属するかが明確に示されている。

ウェブサイトのライブ環境で、ブラウザの開発者ツールを開き、読み込まれているJavaScriptコードの中から「pk_test_」を検索してみよう。もしこの文字列が見つかったら、それはフロントエンドがまだテストモードの公開可能キーを使っていることを意味する。この状態では、ユーザーはテスト決済しかできないことになる。また、その場で「sk_」も検索してみることを強くお勧めする。もしブラウザ上で秘密キーが見つかった場合、それはセキュリティ上の重大な問題だ。秘密キーが公開されると、悪意のある第三者にStripeアカウントを操作される危険があるため、発見した場合は直ちにStripeダッシュボードでそのキーを無効化し、新しいキーに交換する必要がある。次に、サーバーサイドの設定を確認する。アプリケーションが利用している環境変数や、Supabase Edge Functionsのシークレットなど、秘密キーが保存されている場所を確認し、そこが「sk_live_」で始まるライブモードの秘密キーを使用していることを確認する。公開可能キーと秘密キー、どちらか一方だけをライブモードに切り替えて、もう一方を忘れてしまうというミスは非常によくあるので、両方がライブモードのキーになっているか丁寧に確認しなければならない。

次に、販売する「製品」と「価格」の設定を確認する。テストモードで作成した製品や価格は、ライブモードには自動的にコピーされない。つまり、テストモードで作成した製品のID（例えば「price_xyz123」のような形式）は、ライブモードでは全く無効となる。もしアプリケーションのコードや、AIビルダーなどのツールが、テストモードの価格IDを直接記述（ハードコード）している場合、キーの設定が正しくても、ライブ決済時に「そのような価格は存在しない」というエラーが発生し、決済は失敗する。この問題を確認するには、Stripeダッシュボードにログインし、テストモードをオフにした状態で「製品カタログ」の項目を開く。ここで、アプリケーションの料金ページで販売している全てのプランが、ライブモードの製品カタログに正しく登録されており、金額、通貨、支払い間隔（例: 月額、年額）が全て一致しているかを確認する。さらに、アプリケーションのコードやサーバー側の設定で利用している価格ID（「price_」で始まる文字列）を検索し、それらがStripeダッシュボードのライブモードで表示されている価格IDと完全に一致しているか確認する必要がある。テストモードとライブモードのIDは異なる文字列になるのが普通なので、コード内のIDがライブモードのものであることを確認するのだ。また、金額や支払い間隔のチェックも重要だ。テストモードでは19ドルのプランだったものが、ライブモードでは誤って190ドルになっていたり、月額が年額になっていたりといったミスは、テストカードでの確認では見過ごされやすいため、特に注意が必要だ。

Stripeの「Webhooks」も忘れずに確認しよう。Webhooksは、顧客の支払い完了やサブスクリプションの変更など、Stripe側で発生した重要なイベントを、アプリケーションにリアルタイムで通知するための仕組みだ。このWebhooksも、テストモードとライブモードでそれぞれ個別に設定する必要がある。テストモードで設定したWebhookエンドポイントは、ライブ決済からの通知を一切受け取らない。また、Webhookの通知がStripeから送られた正当なものであることを確認するための「署名シークレット」も、テストモードとライブモードで異なる。この設定ミスが発生すると、顧客はStripeを通じて料金を支払ったにもかかわらず、アプリケーション側ではその支払いを認識できず、結果として顧客のアカウントが有効化されないという最悪の事態が発生する。これを防ぐためには、Stripeダッシュボードのライブモードから「開発者」メニューの「Webhooks」セクションを開く。そこに、本番環境のアプリケーションURLを指すWebhookエンドポイントが登録されており、アプリケーションが必要とするイベント（例えば「checkout.session.completed」やサブスクリプション関連のイベント）を購読していることを確認する。次に、そのライブモードのWebhookエンドポイントの署名シークレットをコピーし、アプリケーションのサーバー側が、テストモードのものではなく、このライブモードのシークレットを使っていることを確認する。

Stripeの「決済リンク」や「顧客ポータル」を利用している場合も、モードの切り替えに注意が必要だ。もしStripeの決済リンクを使って商品を販売しているのであれば、ウェブサイトの「購入」ボタンなどに設定されているリンク先URLを確認しよう。テストモードの決済リンクは、URLの中に「test_」という文字列が含まれており、表示される決済ページには「Test mode」というバッジが表示される。ライブサイトにテストモードの決済リンクが設定されている場合、実際の支払いは一切行われない。また、顧客が自分のサブスクリプションを管理したり、クレジットカード情報を更新したり、プランをキャンセルしたりする際に利用する「顧客ポータル」も、テストモードとライブモードでそれぞれ設定が必要だ。もし顧客が「サブスクリプションを管理」しようとしてエラーが発生する場合、それは顧客ポータルがテストモードでしか設定されていない可能性が高い。

ここまで様々な設定を確認してきたが、これら全ての連携が正しく機能しているかを最終的に証明する唯一の方法は、「実際の決済を一度行い、その後返金する」ことだ。このステップを省略する開発者は多いが、これは絶対に飛ばしてはならない最も重要なチェックだ。まず、アプリケーションで提供している中で最も安価なプランを、実際のクレジットカードを使って、新規ユーザーとして購入してみる。この「本物の支払い」を行った後、以下の四点を確認する。一つ目は、Stripeダッシュボードのライブモードに、購入した金額の決済履歴が正しく表示されるか。二つ目は、設定したWebhookエンドポイントが、支払い完了イベントをアプリケーションに正常に配信し、Stripeダッシュボードでイベントが「配信済み」として表示されているか。三つ目は、アプリケーションがその支払いイベントを正しく処理し、購入したプランに応じて顧客のアカウントが有効化されたか、または提供されるべきサービスが利用可能になったか。そして四つ目は、Stripeから領収書メールが届いたかだ。Stripeはテスト決済に対して領収書メールを送信しないため、このメールが届くかどうかは、実際にライブ決済が行われたかどうかの重要な指標になる。これらの確認が全て完了したら、Stripeダッシュボードから自分への返金処理を行い、これでこの確認プロセスは完了だ。さらに、ライブ決済が完全にテストモードから切り離されていることを確認するために、アプリケーションのライブ決済ページで、テストカード番号「4242 4242 4242 4242」を入力して決済を試してみよう。このカードは拒否されるのが正しい挙動だ。もしこのテストカードで決済が成功してしまった場合、それはまだライブ決済がテストモードで動作していることを意味し、全ての設定を再度見直す必要がある。

一度アプリケーションがライブ稼働した後は、今後の全てのテストは必ずテストモードか、Stripeサンドボックスと呼ばれる別のテスト環境で行うべきだ。そして、テスト用に用意したアプリのステージング環境で、テストモードのキーを使って開発を進める。リリース直後に避けるべき逆のミスは、デバッグのために「5分だけ」ライブ環境のキーをテストモードのキーに切り替えてしまい、そのまま元に戻すのを忘れることだ。もし万が一そのような操作をしてしまった場合は、ログオフする前に必ずキーの確認作業を再度実行し、ライブモードのキーに戻っていることを確認する習慣をつけよう。

以上のチェックリストは、Stripeを利用したアプリケーションが初めて本番環境で決済を受け付ける際に、最も基本的な項目を網羅している。これらの確認を怠ると、予期せぬトラブルや顧客の不満に繋がりかねないため、システムエンジニアを目指す上では、このような環境設定の重要性を理解し、丁寧な確認作業を行う習慣を身につけることが非常に大切である。顧客の信頼を得るためにも、リリース前の最終チェックは入念に行う必要がある。