stripe

Stripe Billing Operations

在 Stripe 上执行账单和支付操作：客户、产品、发票、支付链接、订阅、退款和争议。

**MCP 可选。**此技能可通过 MCP（自动）、Stripe CLI 或 Dashboard 使用。有关执行方式，请参阅 BACKENDS.md。

三条硬性规则

1. 先读后写 — 创建客户／产品／价格前，先检查是否已存在，以避免重复
2. 资金操作必须确认 — 退款、订阅变更、争议更新必须先确认再执行
3. 不确定时先搜索 — 如果不确定对象 ID 或参数，先搜索，不要猜测

安全规则

操作类型	规则
读取（列表、获取、搜索）	直接执行
创建（客户、产品、价格、发票）	先检查是否重复
资金（退款、取消／更新订阅、争议）	显示详情 → 等待确认 → 执行
模式	默认使用测试模式。实时模式需要明确指定“live mode”并进行二次确认

危险操作（需要确认）

执行以下操作前：

1. 显示 — 显示对象 ID 和关键字段
2. 说明影响 — 金额、时间安排、后果
3. 等待确认 — 等待明确回复“confirm”／“yes”／“proceed”
4. 执行并回执 — 返回结果 + 对象 ID + 状态

确认提示示例：

About to execute refund:
- PaymentIntent: pi_xxx
- Amount: $50.00 (full amount)
- Reason: requested_by_customer

Reply "confirm" to proceed, or "cancel" to abort.

常见工作流

创建客户

1. Search/list to check if customer exists (by email)
2. If not exists, create_customer(name, email, metadata)
3. Return cus_xxx + key info

创建产品和价格

1. List products to check if already exists
2. create_product(name, description)
3. create_price(product=prod_xxx, unit_amount=cents, currency)
4. Return prod_xxx + price_xxx

创建并发送发票

1. Confirm customer ID (list_customers if unknown)
2. create_invoice(customer=cus_xxx, collection_method, days_until_due)
3. create_invoice_item(invoice=inv_xxx, price=price_xxx, quantity)
4. finalize_invoice(invoice=inv_xxx)
5. Return inv_xxx + hosted_invoice_url

创建支付链接

1. Confirm price ID (list_prices if unknown)
2. create_payment_link(line_items=[{price, quantity}])
3. Return payment link URL

退款（危险）

1. list_payment_intents to find target payment
2. Display pi_xxx + amount + customer info
3. Request user confirmation
4. create_refund(payment_intent=pi_xxx, amount?, reason)
5. Return re_xxx + status

取消订阅（危险）

1. list_subscriptions(customer=cus_xxx) to find target
2. Display sub_xxx + status + next billing date
3. Ask: cancel immediately or at period end?
4. After confirmation, cancel_subscription(subscription=sub_xxx)
5. Return cancellation result

默认配置

• 货币：使用用户指定的货币；否则使用现有对象的货币；否则询问
• 金额：接受小数，自动转换为最小单位（例如，$19.99 → 1999）
• 输出：对象类型 + ID + 关键字段 + 后续步骤

限制

无法通过标准工具执行以下操作：

• ❌ 创建 PaymentIntent／直接扣款
• ❌ 创建订阅（仅支持列出／更新／取消）
• ❌ 创建 Promotion Code（仅支持优惠券）
• ❌ 删除对象

这些操作请直接使用 Dashboard 或 API。

基于文件的管道

集成到多步骤工作流时：

runs/<workflow>/active/<run_id>/
├── proposal.md                # Requirements / objective
├── context.json               # Known IDs (customer, invoice, etc.)
├── tasks.md                   # Checklist + approval gate
├── evidence/stripe-actions.md # Operations to execute (money ops written here first)
├── evidence/receipt.md        # Results + object IDs
└── logs/events.jsonl          # Optional tool call summary (no sensitive data)

错误处理

情况	操作
对象不存在	搜索以查找正确的 ID
参数错误	查阅文档以确认正确格式
权限不足	检查 API 密钥的权限范围
网络错误	重试或检查连接

相关文件

• BACKENDS.md — 执行方式（MCP／CLI／Dashboard）
• SETUP.md — MCP 配置（可选）
• tools.md — 工具参数详解