stripe

Stripe の運用

このスキルでは、Stripe アカウントの状態を読み取り、明示的な確認を得たうえで、アカウント残高、PaymentIntent、サブスクリプション、サブスクリプションのキャンセルについて、保護された変更を実行できます。これは Stripe プラットフォーム向けのツールスキルです。アプリケーションへの Stripe 決済の組み込みはインテグレーション開発にあたります。このスキルが担うのは、「残高はいくらですか？」「成功した決済はどれですか？」「有効なサブスクリプションはどれですか？」といった日常的なエージェントのワークフローと、確認済みのキャンセルの実行です。

運用上の契約

1. まずは読み取り専用で実行します。 残高、決済、サブスクリプションの照会は自由に実行でき、変更は一切行いません。同梱の stripe-cli スクリプトの主な機能は、これらの読み取りです。
2. すべての変更を保護します。 サブスクリプションのキャンセルなど、状態を変更する操作には、明示的な人間の指示に加えて、stripe-cli での --dry-run によるプレビューと --yes による確認が必要です。キャンセルは請求に影響する財務上の操作です。実行前に、対象のサブスクリプション、タイミング、影響を確認してください。
3. 読み取り範囲を守ります。 Stripe は limit と has_more を使ってページネーションを行います。タスクに必要な範囲を超えてページを取得しないでください。stripe-cli --limit は、すべての一覧取得の上限を設定します。
4. 証拠の範囲を限定します。 短い ID、金額、ステータスを引用してください。API キー全体、顧客データ、生のペイロードをチャットに出力しないでください。金額は通貨に応じて書式化され、監査用に JSON には生の整数値と通貨が保持されます。
5. 金銭データを機密情報として扱います。 残高、決済、サブスクリプションの詳細は財務記録です。質問に必要な情報だけを引用し、カード情報や顧客データ全体を決して公開しないでください。

stripe-cli スクリプト

scripts/stripe-cli は、Stripe API を操作するエージェント向けの、標準ライブラリのみを使用した CLI です。まずは読み取り専用で実行する設計で、残高、決済、サブスクリプションを主な機能とし、唯一の変更操作も保護されています。

stripe/scripts/stripe-cli --help                          # no key or network needed
stripe/scripts/stripe-cli --json balance show
stripe/scripts/stripe-cli --json --limit 20 payments list
stripe/scripts/stripe-cli --json --limit 20 subscriptions list
stripe/scripts/stripe-cli --json subscriptions get --id sub_123
stripe/scripts/stripe-cli subscriptions cancel --id sub_123 --dry-run   # preview
stripe/scripts/stripe-cli subscriptions cancel --id sub_123 --yes       # confirmed

終了コード：0 は成功、1 は API エラーまたはチェックの失敗、2 は使用方法のエラーです。キャンセルは保護されています。--dry-run または --yes が指定されていない場合、スクリプトは終了コード 1 で処理を拒否し、API を呼び出しません。読み取りは --limit で制限されます（デフォルトは 20、最大は 100）。

運用の流れ

1. 質問の範囲を特定します：読み取り（残高、決済、サブスクリプション）ですか、それとも変更（キャンセル）ですか？まず読み取り機能を使って対象を特定します。
2. 範囲を限定して読み取ります：利用可能残高と保留中の資金には balance show、最近のPaymentIntentには payments list、有効なサブスクリプションとその項目には subscriptions list／subscriptions get を使います。
3. 回答に必要な情報を整理します：質問と証拠（金額、ステータス、顧客、期間終了日）を対応づけます。
4. 確認を得て実行します：変更を求める人間の指示がある場合に限り、--dry-run でプレビューし、--yes で確認して実行します。
5. 確認します：サブスクリプションを再度読み取り、cancel_at_period_end が設定されていること（期間終了時にキャンセルされること）を確認します。また、その日までは顧客がサービスを利用できることを伝えます。

読み取り範囲：残高、支払い、サブスクリプション

• 残高（GET /balance）：通貨ごとの利用可能残高と保留中残高です。アカウント資金の読み取り専用スナップショットです。
• 支払い（GET /payment_intents）：金額、通貨、ステータス（succeeded、requires_action など）、顧客を含む最近の支払いインテントです。件数は --limit で制限されます。has_more は、上限によってさらに記録が隠れているかどうかを示します。
• サブスクリプション（GET /subscriptions、GET /subscriptions/{id}）：ステータス、顧客、期間終了日、項目（価格、金額、間隔）を含む有効なサブスクリプションです。キャンセルの前に読み取ります。

Stripe の金額は最小通貨単位を使用します。JPY のような通常の小数点以下 0 桁の通貨は整数で表示され、それ以外の通貨は小数点以下 2 桁で表示されます。UGX と ISK は後方互換性のため、API の値を小数点以下 2 桁で保持するため、500 は 5.00 UGX または 5.00 ISK と表示されます。JSON では、元の整数（amount_minor、サブスクリプションの価格の場合は unit_amount_minor）と通貨が、書式設定された表示値とともに保持されます。HUF と TWD は、請求／価格の記録では小数点以下 2 桁を使用します（整数単位のルールは手動の支払いに適用されます）。Stripe が決済表示に対応していない小数点以下 3 桁の通貨は拒否されます。出典と詳細については、references/01-stripe-read-operations.md を参照してください。

保護された変更操作：サブスクリプションのキャンセル

• subscriptions cancel --id sub_... --dry-run でキャンセルをプレビューします。--yes で確定し、cancel_at_period_end=true を送信します。これは安全なデフォルトで、即時にキャンセルするのではなく、期間終了時にキャンセルを予約します（顧客はその時点までサービスを利用できます）。
• スクリプトは、Stripe が変更を確認したこと（レスポンスの cancel_at_period_end: true）を検証してから成功を報告します。一致しない場合はエラーになり、状態が変更されたとは見なされません。
• 期間終了時に予定されたキャンセルは、期間終了前に cancel_at_period_end=false を設定することで取り消せます。即時キャンセルと返金は、このスキルの変更操作の対象外です。これらには Stripe ダッシュボードでの人間による操作、または専用の連携が必要です。

アクセスモデルと認証情報

• Stripe の認証には、シークレットキー（sk_...）または制限付きキー（rk_...）を使用します。読み取り範囲には、読み取り専用に範囲を限定した制限付きキー（balance:read、payment_intents:read、subscriptions:read）を使用します。キャンセルが本当に必要な場合に限り、subscriptions:write を追加してください。
• キーには本番環境用とテスト環境用（sk_live_／sk_test_）があります。本番環境用キーをテストデータに使用したり、その逆を行ったりしないでください。実際の請求に影響する可能性がある操作を実行する前に、キーの種類を確認してください。
• キーは STRIPE_API_KEY に保存し、コード、チャット、コミットには決して含めないでください。キーが漏えいした場合は、Stripe ダッシュボードですぐにローテーションしてください。

参照先の案内

読み込むタイミング	参照資料
出典、更新手順	references/00-source-index.md
エンドポイント、ページネーション、キャンセルの仕様、エラー	references/01-stripe-read-operations.md

同梱ファイル

• scripts/stripe-cli：範囲を制限した標準ライブラリのみの CLI（残高、支払い一覧、サブスクリプション一覧／取得、保護されたキャンセル。--json、--limit に対応。変更操作は --dry-run／--yes で制御）。
• tests/test_stripe_cli.py：スタブ Stripe API を使用した、決定的な 14 件のテスト。USD／JPY の書式設定、特殊な通貨ルール、元の単位の保持、変更操作のゲートを含みます。
• references/：日付付きの出典インデックスと Stripe 読み取り操作のリファレンス。
• evals/evals.json：エージェントの実行に対する、出力品質評価ケース 7 件。

検証の境界

主張	最低限の証拠
残高が最新である	stripe-cli balance show --json が通貨ごとの利用可能額と保留中の金額を返す
支払いが成功した	stripe-cli payments list --json にステータス succeeded のインテントが表示される
サブスクリプションが有効である	stripe-cli subscriptions get --json がステータス active と期間終了日を返す
解約が受け付けられた	stripe-cli subscriptions cancel --yes が終了コード 0 で終了し、応答に cancel_at_period_end: true が含まれる
変更を安全に実行できる	stripe-cli subscriptions cancel --dry-run が正確なサブスクリプション ID を出力する

厳守すべき境界

• 人間からの指示、--dry-run によるプレビュー、--yes による確認なしに、サブスクリプションを解約してはいけません。解約には請求への影響があります。
• 変更操作の範囲は、期間終了時に解約するようスケジュールすることに限られます。返金、即時解約、請求処理は対象外です。
• --limit を超えて読み取りを続けてはいけません。完全な API キー、顧客データ、生のペイロードをチャットに出力してはいけません。
• このスキルは Stripe API を操作します。アプリケーションへの決済機能の組み込みや、ほかの決済処理サービスには対応しません。

使用しない場合

• アプリケーションへの Stripe 決済機能の組み込み（Checkout、コード内の Payment Intents、アプリ向け Webhook、請求ロジック）— これは統合開発です。backend-engineering を参照してください。
• Stripe ダッシュボードの管理（アカウント設定、銀行口座、異議申し立て、税務登録）— Stripe Dashboard を使用してください。
• 返金、即時解約、請求処理 — これらは意図的にこのスキルの保護対象となる変更操作の範囲外です。ダッシュボードまたは専用の統合を通じて、人間が判断してください。
• ほかの決済処理サービス（Braintree、Adyen、PayPal）— それぞれ独自の API とツールを備えています。このスキルが対応するのは Stripe です。