OpenClaw Skills Stripe 支付集成技能使用参考手册

概述

Stripe API 是用于集成 Stripe 支付服务的 OpenClaw 技能，通过托管的 OAuth 认证来管理客户、订阅、发票、产品、价格和支付流程。当用户需要处理支付、管理账单或处理 Stripe 订阅时，可以使用该技能。对于其他第三方应用，可以使用 api-gateway 技能（https://clawhub.ai/byungkyu/api-gateway）。

该技能需要网络访问权限和有效的 Maton API 密钥，能够让 AI 代理直接通过 Stripe API 完成各类支付相关的操作，适用于电商网站、订阅服务、账单管理等场景。

技能信息

• 名称：stripe-api
• 描述：通过托管的 OAuth 认证访问 Stripe API，管理客户、订阅、发票、产品、价格并处理支付。
• 版本：1.0.8
• 作者：byungkyu
• 许可证：MIT License
• 依赖：
  • 需要网络访问权限
  • 需要有效的 Maton API 密钥（MATON_API_KEY）
• 触发词："Stripe 支付处理"、"Stripe 客户管理"、"Stripe 订阅管理"、"Stripe 账单管理"、"Stripe 产品管理"

👤 作者：byungkyu
🦞 官方地址：https://clawhub.ai/byungkyu/stripe-api
👉 Skills 下载地址：stripe-api-1.0.8.zip

快速开始

## 列出客户
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/stripe/v1/customers?limit=10')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

基础 URL

https://gateway.maton.ai/stripe/{native-api-path}

将{native-api-path}替换为实际的 Stripe API 端点路径。网关会将请求代理到api.stripe.com，并自动注入你的 OAuth 令牌。

认证

所有请求都需要在 Authorization 头中包含 Maton API 密钥：

Authorization: Bearer $MATON_API_KEY

环境变量

将你的 API 密钥设置为MATON_API_KEY环境变量：

export MATON_API_KEY="你的API密钥"

获取 API 密钥

1. 访问maton.ai注册或登录账户
2. 进入maton.ai/settings页面
3. 复制你的 API 密钥

连接管理

列出连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=stripe&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

创建连接

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'stripe'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

API 参考

所有 Stripe API 端点都遵循以下模式：

/stripe/v1/{resource}

余额

获取余额

GET /stripe/v1/balance

列出余额交易

GET /stripe/v1/balance_transactions?limit=10

客户

列出客户

GET /stripe/v1/customers?limit=10

查询参数：

参数	描述
limit	结果数量（1-100，默认：10）
starting_after	分页游标
ending_before	反向分页游标
email	按邮箱过滤
created	按创建日期过滤

响应：

{
"object": "list",
"data": [
{
"id": "cus_TxKtN8Irvzx9BQ",
"object": "customer",
"email": "customer@example.com",
"name": null,
"balance": 0,
"currency": "usd",
"created": 1770765579,
"metadata": {}
}
]
}

获取客户

GET /stripe/v1/customers/{customer_id}

创建客户

POST /stripe/v1/customers
Content-Type: application/x-www-form-urlencoded
email=customer@example.com&name=John%20Doe&metadata[user_id]=123

更新客户

POST /stripe/v1/customers/{customer_id}
Content-Type: application/x-www-form-urlencoded
name=Jane%20Doe&email=jane@example.com

删除客户

DELETE /stripe/v1/customers/{customer_id}

产品

列出产品

GET /stripe/v1/products?limit=10

查询参数：

参数	描述
active	按活跃状态过滤
type	按类型过滤：good或service

响应：

{
"object": "list",
"data": [
{
"id": "prod_TthCLBwTIXuzEw",
"object": "product",
"active": true,
"name": "Premium Plan",
"description": "Premium subscription",
"type": "service",
"created": 1769926024,
"metadata": {}
}
],
"has_more": true
}

获取产品

GET /stripe/v1/products/{product_id}

创建产品

POST /stripe/v1/products
Content-Type: application/x-www-form-urlencoded
name=Premium%20Plan&description=Premium%20subscription&type=service

更新产品

POST /stripe/v1/products/{product_id}
Content-Type: application/x-www-form-urlencoded
name=Updated%20Plan&active=true

删除产品

DELETE /stripe/v1/products/{product_id}

价格

列出价格

GET /stripe/v1/prices?limit=10

查询参数：

参数	描述
active	按活跃状态过滤
product	按产品 ID 过滤
type	过滤：one_time或recurring
currency	按货币过滤

响应：

{
"object": "list",
"data": [
{
"id": "price_1SvtoVDfFKJhF88gKJv2eSmO",
"object": "price",
"active": true,
"currency": "usd",
"product": "prod_TthCLBwTIXuzEw",
"unit_amount": 1999,
"recurring": {
"interval": "month",
"interval_count": 1
},
"type": "recurring"
}
],
"has_more": true
}

获取价格

GET /stripe/v1/prices/{price_id}

创建价格

POST /stripe/v1/prices
Content-Type: application/x-www-form-urlencoded
product=prod_XXX&unit_amount=1999¤cy=usd&recurring[interval]=month

更新价格

POST /stripe/v1/prices/{price_id}
Content-Type: application/x-www-form-urlencoded
active=false

订阅

列出订阅

GET /stripe/v1/subscriptions?limit=10

查询参数：

参数	描述
customer	按客户 ID 过滤
price	按价格 ID 过滤
status	过滤：active、canceled、past_due等

响应：

{
"object": "list",
"data": [
{
"id": "sub_1SzQDXDfFKJhF88gf72x6tDh",
"object": "subscription",
"customer": "cus_TxKtN8Irvzx9BQ",
"status": "active",
"current_period_start": 1770765579,
"current_period_end": 1773184779,
"items": {
"data": [
{
"id": "si_TxKtFWxlUW50cR",
"price": {
"id": "price_1RGbXsDfFKJhF88gMIShAq9m",
"unit_amount": 0
},
"quantity": 1
}
]
}
}
],
"has_more": true
}

获取订阅

GET /stripe/v1/subscriptions/{subscription_id}

创建订阅

POST /stripe/v1/subscriptions
Content-Type: application/x-www-form-urlencoded
customer=cus_XXX&items[0][price]=price_XXX

更新订阅

POST /stripe/v1/subscriptions/{subscription_id}
Content-Type: application/x-www-form-urlencoded
items[0][id]=si_XXX&items[0][price]=price_YYY

取消订阅

DELETE /stripe/v1/subscriptions/{subscription_id}

发票

列出发票

GET /stripe/v1/invoices?limit=10

查询参数：

参数	描述
customer	按客户 ID 过滤
subscription	按订阅 ID 过滤
status	过滤：draft、open、paid、void、uncollectible

获取发票

GET /stripe/v1/invoices/{invoice_id}

创建发票

POST /stripe/v1/invoices
Content-Type: application/x-www-form-urlencoded
customer=cus_XXX

完成发票

POST /stripe/v1/invoices/{invoice_id}/finalize

支付发票

POST /stripe/v1/invoices/{invoice_id}/pay

作废发票

POST /stripe/v1/invoices/{invoice_id}/void

收费

列出收费

GET /stripe/v1/charges?limit=10

查询参数：

参数	描述
customer	按客户 ID 过滤
payment_intent	按支付意图过滤

响应：

{
"object": "list",
"data": [
{
"id": "ch_3SyXBvDfFKJhF88g1MHtT45f",
"object": "charge",
"amount": 5000,
"currency": "usd",
"customer": "cus_TuZ7GIjeZQOQ2m",
"paid": true,
"status": "succeeded",
"payment_method_details": {
"card": {
"brand": "mastercard",
"last4": "0833"
},
"type": "card"
}
}
],
"has_more": true
}

获取收费

GET /stripe/v1/charges/{charge_id}

创建收费

POST /stripe/v1/charges
Content-Type: application/x-www-form-urlencoded
amount=2000¤cy=usd&source=tok_XXX

支付意图

列出支付意图

GET /stripe/v1/payment_intents?limit=10

响应：

{
"object": "list",
"data": [
{
"id": "pi_3SyXBvDfFKJhF88g17PeHdpE",
"object": "payment_intent",
"amount": 5000,
"currency": "usd",
"customer": "cus_TuZ7GIjeZQOQ2m",
"status": "succeeded",
"payment_method": "pm_1SyXBpDfFKJhF88gmP3IjC8C"
}
],
"has_more": true
}

获取支付意图

GET /stripe/v1/payment_intents/{payment_intent_id}

创建支付意图

POST /stripe/v1/payment_intents
Content-Type: application/x-www-form-urlencoded
amount=2000¤cy=usd&customer=cus_XXX&payment_method_types[]=card

确认支付意图

POST /stripe/v1/payment_intents/{payment_intent_id}/confirm

取消支付意图

POST /stripe/v1/payment_intents/{payment_intent_id}/cancel

支付方式

列出支付方式

GET /stripe/v1/payment_methods?customer=cus_XXX&type=card

获取支付方式

GET /stripe/v1/payment_methods/{payment_method_id}

附加支付方式

POST /stripe/v1/payment_methods/{payment_method_id}/attach
Content-Type: application/x-www-form-urlencoded
customer=cus_XXX

分离支付方式

POST /stripe/v1/payment_methods/{payment_method_id}/detach

优惠券

列出优惠券

GET /stripe/v1/coupons?limit=10

获取优惠券

GET /stripe/v1/coupons/{coupon_id}

创建优惠券

POST /stripe/v1/coupons
Content-Type: application/x-www-form-urlencoded
percent_off=25&duration=once

删除优惠券

DELETE /stripe/v1/coupons/{coupon_id}

退款

列出退款

GET /stripe/v1/refunds?limit=10

获取退款

GET /stripe/v1/refunds/{refund_id}

创建退款

POST /stripe/v1/refunds
Content-Type: application/x-www-form-urlencoded
charge=ch_XXX&amount=1000

分页

Stripe 使用基于游标的分页方式，使用starting_after和ending_before参数：

GET /stripe/v1/customers?limit=10&starting_after=cus_XXX

响应包含：

{
"object": "list",
"data": [...],
"has_more": true,
"url": "/v1/customers"
}

使用最后一项的 ID 作为下一页的starting_after参数。

代码示例

JavaScript

const response = await fetch(
'https://gateway.maton.ai/stripe/v1/customers?limit=10',
{
headers: {
'Authorization': `Bearer ${process.env.MATON_API_KEY}`
}
}
);
const data = await response.json();
console.log(data.data);

Python

import os
import requests
response = requests.get(
'https://gateway.maton.ai/stripe/v1/customers',
headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
params={'limit': 10}
)
data = response.json()
for customer in data['data']:
print(f"{customer['id']}: {customer['email']}")

注意事项

• Stripe API 的 POST 请求使用application/x-www-form-urlencoded格式（而非 JSON）
• 金额以货币的最小单位表示（例如，美元使用美分）
• ID 使用前缀标识：cus_（客户）、prod_（产品）、price_（价格）、sub_（订阅）、in_（发票）、ch_（收费）、pi_（支付意图）
• 时间戳使用 Unix 时间戳
• 重要提示：使用 curl 命令时，如果 URL 包含括号，请使用curl -g来禁用 glob 解析
• 重要提示：当将 curl 输出通过管道传递给jq或其他命令时，在某些 shell 环境中，$MATON_API_KEY等环境变量可能无法正确展开

错误处理

状态码	含义
400	请求无效或参数错误
401	Maton API 密钥无效或缺失
402	卡片被拒绝或需要支付
404	资源未找到
429	请求频率超限
500	Stripe 内部错误

故障排除：API 密钥问题

1. 检查MATON_API_KEY环境变量是否已设置：

echo $MATON_API_KEY

1. 通过列出连接来验证 API 密钥是否有效：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

故障排除：无效的应用名称

确保 URL 路径以stripe开头。例如：

• 正确：https://gateway.maton.ai/stripe/v1/customers
• 错误：https://gateway.maton.ai/v1/customers

许可证信息

该技能采用 MIT License，完整的许可条款如下：

The MIT License (MIT)
Copyright (c) 2026 Maton
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

元数据信息

该技能的元数据信息如下：

{
"ownerId": "kn75240wq8bnv2qm2xgry748jd80b9r0",
"slug": "stripe-api",
"version": "1.0.8",
"publishedAt": 1770766965851
}