Stripe: 托管 OAuth 支付集成 - Openclaw Skills

什么是 Stripe？

Stripe 技能通过托管 OAuth 网关在 AI 智能体和 Stripe 生态系统之间提供了一个坚实的桥梁。开发人员无需手动处理复杂的令牌刷新和敏感凭据，而是可以利用 Openclaw Skills 通过安全代理与客户、产品和发票进行交互。这种集成简化了财务工作流的实现，允许智能体以最小的配置处理支付和管理定期计费，同时保持高安全标准。

下载入口:https://github.com/openclaw/skills/tree/main/skills/byungkyu/stripe-api

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

npx clawhub@latest install stripe-api

2. 手动安装

将技能文件夹复制到以下位置之一

全局模式 ~/.openclaw/skills/ 工作区 <project>/skills/

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

请帮我使用 Clawhub 安装 stripe-api。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。

Stripe 应用场景

• 自动化客户入驻和订阅生命周期管理。
• 为 B2B 或 SaaS 平台生成和跟踪发票。
• 处理单次收费并管理复杂的支付意向。
• 查询实时账户余额和交易历史记录以进行财务报告。
• 处理客户退款并管理促销优惠券代码。

Stripe 工作原理

1. 开发人员获取 Maton API 密钥并将其配置为环境变量。
2. 向控制平面发送连接请求，以启动 Stripe 的 OAuth 流程。
3. 用户通过提供的 URL 授权连接，以安全地链接其 Stripe 账户。
4. API 请求被定向到网关，该网关镜像了原生的 Stripe API 结构。
5. 网关在转发给 Stripe 之前，会自动在请求头中注入适当的 OAuth 令牌。
6. Stripe 处理请求（例如，创建客户或扣款）并通过网关返回数据。

Stripe 配置指南

首先，将您的 API 密钥设置为环境变量：

export MATON_API_KEY="YOUR_API_KEY"

接下来，创建一个新的 Stripe 连接以接收授权 URL：

curl -X POST https://ctrl.maton.ai/connections r
-H "Authorization: Bearer $MATON_API_KEY" r
-H "Content-Type: application/json" r
-d '{"app": "stripe"}'

在浏览器中打开响应中返回的 URL 以完成 OAuth 流程。激活后，您可以开始向网关 https://gateway.maton.ai/stripe/v1/ 发起请求。

Stripe 数据架构与分类体系

该技能利用了原生的 Stripe 对象模型。所有金额均以最小货币单位处理（例如，美元为分）。

资源	前缀	描述
客户	cus_	存储用户资料和信息。
产品	prod_	定义待售商品或服务。
价格	price_	设置成本和计费周期。
订阅	sub_	跟踪定期计费周期。
发票	in_	记录付款请求。
收款	ch_	代表单次资金变动。

注意：所有 POST 请求必须格式化为 application/x-www-form-urlencoded。

name: stripe
description: |
  Stripe API integration with managed OAuth. Manage customers, subscriptions, invoices, products, prices, and payments.
  Use this skill when users want to process payments, manage billing, or handle subscriptions with Stripe.
  For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway).
  Requires network access and valid Maton API key.
metadata:
  author: maton
  version: "1.0"
  clawdbot:
    emoji: ??
    homepage: "https://maton.ai"
    requires:
      env:
        - MATON_API_KEY

Stripe

Access the Stripe API with managed OAuth authentication. Manage customers, subscriptions, invoices, products, prices, and process payments.

Quick Start

# List customers
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

Base URL

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

Replace {native-api-path} with the actual Stripe API endpoint path. The gateway proxies requests to api.stripe.com and automatically injects your OAuth token.

Authentication

All requests require the Maton API key in the Authorization header:

Authorization: Bearer $MATON_API_KEY

Environment Variable: Set your API key as MATON_API_KEY:

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

1. Sign in or create an account at maton.ai
2. Go to maton.ai/settings
3. Copy your API key

Connection Management

Manage your Stripe OAuth connections at https://ctrl.maton.ai.

List Connections

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

Create Connection

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

Get Connection

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

Response:

{
  "connection": {
    "connection_id": "c3c82a73-4c86-4c73-8ebd-1f325212fde6",
    "status": "ACTIVE",
    "creation_time": "2026-02-01T06:04:02.431819Z",
    "last_updated_time": "2026-02-10T22:40:01.061825Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "stripe",
    "metadata": {}
  }
}

Open the returned url in a browser to complete OAuth authorization.

Delete Connection

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

Specifying Connection

If you have multiple Stripe connections, specify which one to use with the Maton-Connection header:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/stripe/v1/customers')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', 'c3c82a73-4c86-4c73-8ebd-1f325212fde6')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

If omitted, the gateway uses the default (oldest) active connection.

API Reference

All Stripe API endpoints follow this pattern:

/stripe/v1/{resource}

---

Balance

Get Balance

GET /stripe/v1/balance

Response:

{
  "object": "balance",
  "available": [
    {
      "amount": 0,
      "currency": "usd",
      "source_types": {"card": 0}
    }
  ],
  "pending": [
    {
      "amount": 5000,
      "currency": "usd",
      "source_types": {"card": 5000}
    }
  ]
}

List Balance Transactions

GET /stripe/v1/balance_transactions?limit=10

---

Customers

List Customers

GET /stripe/v1/customers?limit=10

Query Parameters:

Response:

{
  "object": "list",
  "data": [
    {
      "id": "cus_TxKtN8Irvzx9BQ",
      "object": "customer",
      "email": "[email protected]",
      "name": null,
      "balance": 0,
      "currency": "usd",
      "created": 1770765579,
      "metadata": {}
    }
  ],
  "has_more": true,
  "url": "/v1/customers"
}

Get Customer

GET /stripe/v1/customers/{customer_id}

Create Customer

POST /stripe/v1/customers
Content-Type: application/x-www-form-urlencoded

[email protected]&name=John%20Doe&metadata[user_id]=123

Update Customer

POST /stripe/v1/customers/{customer_id}
Content-Type: application/x-www-form-urlencoded

name=Jane%20Doe&[email protected]

Delete Customer

DELETE /stripe/v1/customers/{customer_id}

---

Products

List Products

GET /stripe/v1/products?limit=10

Query Parameters:

Response:

{
  "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 Product

GET /stripe/v1/products/{product_id}

Create Product

POST /stripe/v1/products
Content-Type: application/x-www-form-urlencoded

name=Premium%20Plan&description=Premium%20subscription&type=service

Update Product

POST /stripe/v1/products/{product_id}
Content-Type: application/x-www-form-urlencoded

name=Updated%20Plan&active=true

Delete Product

DELETE /stripe/v1/products/{product_id}

---

Prices

List Prices

GET /stripe/v1/prices?limit=10

Query Parameters:

Response:

{
  "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 Price

GET /stripe/v1/prices/{price_id}

Create Price

POST /stripe/v1/prices
Content-Type: application/x-www-form-urlencoded

product=prod_XXX&unit_amount=1999&currency=usd&recurring[interval]=month

Update Price

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

active=false

---

Subscriptions

List Subscriptions

GET /stripe/v1/subscriptions?limit=10

Query Parameters:

Response:

{
  "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 Subscription

GET /stripe/v1/subscriptions/{subscription_id}

Create Subscription

POST /stripe/v1/subscriptions
Content-Type: application/x-www-form-urlencoded

customer=cus_XXX&items[0][price]=price_XXX

Update Subscription

POST /stripe/v1/subscriptions/{subscription_id}
Content-Type: application/x-www-form-urlencoded

items[0][id]=si_XXX&items[0][price]=price_YYY

Cancel Subscription

DELETE /stripe/v1/subscriptions/{subscription_id}

---

Invoices

List Invoices

GET /stripe/v1/invoices?limit=10

Query Parameters:

Response:

{
  "object": "list",
  "data": [
    {
      "id": "in_1SzQDXDfFKJhF88g3nh4u2GS",
      "object": "invoice",
      "customer": "cus_TxKtN8Irvzx9BQ",
      "amount_due": 0,
      "amount_paid": 0,
      "currency": "usd",
      "status": "paid",
      "subscription": "sub_1SzQDXDfFKJhF88gf72x6tDh",
      "hosted_invoice_url": "https://invoice.stripe.com/...",
      "invoice_pdf": "https://pay.stripe.com/invoice/.../pdf"
    }
  ],
  "has_more": true
}

Get Invoice

GET /stripe/v1/invoices/{invoice_id}

Create Invoice

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

customer=cus_XXX

Finalize Invoice

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

Pay Invoice

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

Void Invoice

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

---

Charges

List Charges

GET /stripe/v1/charges?limit=10

Query Parameters:

Response:

{
  "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 Charge

GET /stripe/v1/charges/{charge_id}

Create Charge

POST /stripe/v1/charges
Content-Type: application/x-www-form-urlencoded

amount=2000&currency=usd&source=tok_XXX

---

Payment Intents

List Payment Intents

GET /stripe/v1/payment_intents?limit=10

Response:

{
  "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 Payment Intent

GET /stripe/v1/payment_intents/{payment_intent_id}

Create Payment Intent

POST /stripe/v1/payment_intents
Content-Type: application/x-www-form-urlencoded

amount=2000&currency=usd&customer=cus_XXX&payment_method_types[]=card

Confirm Payment Intent

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

Cancel Payment Intent

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

---

Payment Methods

List Payment Methods

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

Get Payment Method

GET /stripe/v1/payment_methods/{payment_method_id}

Attach Payment Method

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

customer=cus_XXX

Detach Payment Method

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

---

Coupons

List Coupons

GET /stripe/v1/coupons?limit=10

Get Coupon

GET /stripe/v1/coupons/{coupon_id}

Create Coupon

POST /stripe/v1/coupons
Content-Type: application/x-www-form-urlencoded

percent_off=25&duration=once

Delete Coupon

DELETE /stripe/v1/coupons/{coupon_id}

---

Refunds

List Refunds

GET /stripe/v1/refunds?limit=10

Get Refund

GET /stripe/v1/refunds/{refund_id}

Create Refund

POST /stripe/v1/refunds
Content-Type: application/x-www-form-urlencoded

charge=ch_XXX&amount=1000

---

Pagination

Stripe uses cursor-based pagination with starting_after and ending_before:

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

Response includes:

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

Use the last item's ID as starting_after for the next page.

Code Examples

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']}")

Notes

• Stripe API uses application/x-www-form-urlencoded for POST requests (not JSON)
• Amounts are in the smallest currency unit (e.g., cents for USD)
• IDs start with prefixes: cus_ (customers), prod_ (products), price_ (prices), sub_ (subscriptions), in_ (invoices), ch_ (charges), pi_ (payment intents)
• Timestamps are Unix timestamps
• IMPORTANT: When using curl commands, use curl -g when URLs contain brackets to disable glob parsing
• IMPORTANT: When piping curl output to jq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments

Error Handling

Troubleshooting: API Key Issues

1. Check that the MATON_API_KEY environment variable is set:

echo $MATON_API_KEY

2. Verify the API key is valid by listing connections:

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

Troubleshooting: Invalid App Name

1. Ensure your URL path starts with stripe. For example:

• Correct: https://gateway.maton.ai/stripe/v1/customers
• Incorrect: https://gateway.maton.ai/v1/customers

Resources

• Stripe API Reference
• Stripe Dashboard
• Stripe Testing
• Maton Community
• Maton Support