Stripe
Stripeサンドボックスでサブスク課金まで通す（2026）
税の先決め、Product／Price、鍵とWebhook、Checkout通し試験。live先走りやCheckout URLのチャット貼りを避ける通し手順。
SaaSの月額課金をStripeの テスト用サンドボックス で、アカウント作成からCheckout → Webhook → 台帳更新まで通す手順です。税を後回しにしたり、いきなりliveに進んだり、Checkout URLをチャットに貼ったりすると手戻りや試験失敗になります。読み終わると、サンドボックスで税→カタログ→鍵→Webhook→通し試験まで揃え、liveは別フェーズだと切り分けられる状態になります。
画面ラベルは変わります。迷ったら Stripeドキュメント を優先してください。アカウント名・金額・エンドポイントURL・鍵の値は載せません。
この記事でわかること
- 税（内税／外税）をProduct／Priceより前に決めること
- サンドボックスで揃えるもの（カタログ・鍵・Webhook・Customer Portal）
- アプリ側のCheckout／Webhook／Portalの要点
- Checkout URLのチャット貼りと、課金周期の取り違えを避けること
- 作業前にAIへ渡す入力（貼り付け文）
前提・環境
| 項目 | 内容 |
|---|---|
| 執筆時点 | 2026-09 |
| モード | テスト用サンドボックスのみ（liveはまだやらない） |
| 到達点 | Checkout → webhook → 台帳 active の1通し |
申込（自前の顧客ID＋規約同意）→ 課金ステータス pending
→ Checkout（メール登録＋初回決済）
→ webhook: checkout.session.completed → active
→ 以降: 開始日基準の毎月同日課金（Stripe 既定）
→ カード変更／解約: Customer Portal
→ webhook: subscription.updated / deleted → 台帳更新旧手順/Webナレッジとの手順差異
| 旧手順/Webナレッジ | 最新（この記事執筆時に確認したこと） |
|---|---|
| Product／Priceを先に作り、税は後で変える | Priceの tax_behavior は後から変えにくい。税を先に決める |
| 最初からlive鍵と本番Webhook | サンドボックスで通し試験してからliveは別フェーズ |
| Checkoutの長いURLをチャットに貼って試験 | 途中で切れやすい。アプリのボタンかローカルのフルURL |
| 「毎月1日課金」と文書のまま実装 | Stripe既定は 開始日基準の毎月同日。文書と揃える |
| Webhook署名を省略した試作を本番に残す | 署名検証必須。公開前の配信失敗は許容し、公開後に成功を見る |
手順
手順1: アカウントと正のサンドボックスを決める
- Stripeアカウントを作り、テスト用サンドボックス（またはテストモード）で作業する 2.似た名前の環境が並ぶときは、正の環境を人間が一言指定してから鍵や連携を有効化する
Dashboard上部がサンドボックス帯で、鍵の接頭辞が sk_test_／pk_test_ であることを確認してください。
手順2: 税（内税／外税・税率・対象市場）を1行で決める
Product／Priceより前に書きます。後から「やっぱり内税」だと、新Price・旧Price非アクティブ・秘密のPrice ID差し替え・Checkoutへの税率付与がセットになります。
メモに内税か外税か、税率、対象国が1行書いてあることを確認してください。
手順3: Product／Priceを作る
月額プランをProductとrecurring Priceとして作ります。プラン名や金額は事業ごとに違うのでここでは載せません。作成前の税方針に合わせます。
税を後から直すときの型は次です。
1.既存Priceの税挙動を確認（変更不可なら新規） 2. 同じ表示額で内税（inclusive）のPriceを作る 3. Tax Rateを作りCheckout／Subscriptionに付与する 4. Productの税コードを公式一覧から選ぶ 5.旧Priceをデフォルトから外して非アクティブ化 6.秘密保管と画面文言（「税込」など）を揃える 7. Checkoutで小計＝支払合計・税行ありを目視
DashboardにPriceが1つあり、税方針と表示額が一致していることを確認してください。
手順4: APIキーを秘密保管へ置く
開発者向けのAPIキー画面からPublishableとSecret（または制限付きキー）を取得し、チャットやGitに平文で出さず秘密保管へ入れます。
秘密保管に鍵があり、チャット・Git・スクショに鍵の平文が無いことを確認してください。
手順5: Webhookを登録する
最低限、次を購読します。
checkout.session.completedcustomer.subscription.updatedcustomer.subscription.deletedinvoice.payment_failed
Signing secretで署名検証します。エンドポイントURL・Destination IDは公開記事に出さないでください。ホスティングが後でも先に登録して構いません。公開前は配信失敗してよく、公開後に成功を確認します。
DashboardにWebhookエンドポイントがあり、Signing secretが秘密保管にあることを確認してください。
手順6: Customer Portalを有効化する
カード変更や解約はPortalに任せると実装が薄いです。DashboardでPortalを有効化し、解約タイミング（期間末など）を要件どおりにしてから、アプリでPortal Sessionを作ります。
DashboardでPortalが有効で、解約タイミング（例: 期間末）が要件どおりになっていることを確認してください。
手順7: アプリを配線する
| 項目 | 要点 |
|---|---|
| Checkout | customer／client_reference_id／metadata に自前の顧客ID |
| Webhook | 署名検証必須。上記イベントで台帳を更新 |
| 秘密 | ランタイムで読む。ビルド時注入だけに頼らない |
| Portal | Dashboard設定を有効化してからSessionを作る |
コードにCheckout Session作成と、署名検証付きwebhookハンドラがあることを確認してください。
手順8: テストカードで通し試験する
- Checkout URLはチャットに貼らない（欠けると次の画面になる）
2.テストカードで決済 → webhook成功 → 台帳が
active3.課金周期（月初か開始日基準か）が要件・画面・実装で一致しているか見る
テストカードでCheckout → webhook成功 → 自前の課金ステータスが active まで1回通ったことを確認してください。
うまくいかないとき
| 症状 | 見ること |
|---|---|
| Checkout画面が壊れる | URLがチャットで切れていないか |
| webhookが失敗し続ける | 署名秘密の取り違え、エンドポイントURL、まだ非公開か |
| 税行がおかしい | Priceのtax_behavior、Tax Rateの付与 |
| 別環境のPriceを触っている | サンドボックス名の取り違え |
| 文書は毎月1日なのに請求日がずれ | アニバーサリー課金と文書の不一致 |
作業前にAIへ渡す入力
次は、読者が AIへのプロンプト（またはrules）に出す指示のサジェストです。そのままコピーして使えます。長い人間向け手順は書きません。
AI向け：永続ルール（rules / AGENTS.md）
Stripe サンドボックスは手順解説型。鍵・Webhook 秘密・Price ID・アカウント固有値をチャットや Git に出すな。
Checkout URL をチャットに貼るな。税は Product／Price より前。live 切替・本人確認は別フェーズ。勝手に live に進むな。AI向け：この作業の開始時にチャットへ貼る文
Stripe サンドボックスでサブスク通しを手順解説で進める。秘密や Checkout の長い URL はチャットに貼るな。
前提→旧手順/Webナレッジとの手順差異→番号手順（各末尾に「〜ことを確認してください」）で案内し、確認後に実装せよ。live は触るな。人間向け
なし。上のAI向けサジェストをプロンプトに貼るだけでよい。
まとめ
- 税 → Product／Price → 鍵 → Webhook → Portal → 通し試験の順
- liveは別フェーズ（本番切替ガイド）
- Checkout URLはチャットに貼らない
- 課金周期は要件・画面・実装を揃える