支付集成专家

支付集成专家——基于Stripe官方优选实践实现全流程支付集成,覆盖支付意图创建、订阅管理、Webhook处理、退款分账全链路。同时提供微信支付/支付宝/银联国内替代方案。适用于电商支付、SaaS订阅、退款处理、平台分账、发票管理、Webhook集成场景。触发关键词:支付集成、Stripe、订阅、Webhook、退款、发票、支付意图、3D 功能涵盖: integrator。功能涵盖: integrator。 Secure、微信支付、支付宝、分账、支付网关

天轰穿@thcjp

Install

openclaw skills install @thcjp/stripe-payment-integrator

支付集成专家

基于 Stripe 官方优选实践,实现安全、合规、可扩展的支付集成。同时提供国内支付(微信支付/支付宝/银联)替代方案,支持跨境与国内双场景。从支付意图到订阅管理,从 Webhook 到退款,全链路覆盖。

核心功能特点

支付意图管理:PaymentIntent 创建/确认/3D Secure 认证(SCA 合规)、自动 vs 手动捕获
订阅全生命周期:产品/价格管理、试用期、升级降级、催收(Dunning)、客户门户
Webhook 安全处理:签名验证、幂等去重、事件路由、失败重试
退款与争议处理:全额/部分退款、争议证据提交、Radar 防欺诈
国内支付适配:微信支付(JSAPI/Native/APP)、支付宝(电脑网站/手机网站/APP)、银联全渠道

功能边界条件

以下表格列出了支付集成专家技能特有的功能边界条件，以及对应的场景描述。

边界条件	场景描述	备注
最低订单金额	对于订单金额低于设定阈值的支付请求，系统将拒绝处理。	通常用于防止小额欺诈。
最大订单金额	对于订单金额超过设定阈值的支付请求，系统将拒绝处理。	通常用于防止大额欺诈。
订单重复处理	当系统检测到重复的订单请求时，将拒绝处理并返回错误。	防止重复支付。
订单取消限制	对于已完成的订单，系统不允许取消。	确保交易一致性。
订阅取消限制	对于处于试用期或已激活的订阅，系统不允许取消。	确保订阅管理的一致性。
退款限制	对于已完成的订单，系统不允许退款。	确保交易一致性。
Webhook事件限制	系统仅处理特定类型的Webhook事件。	确保事件处理的精确性。

快速开始

确认运行环境满足依赖说明中的要求
在AI Agent对话中调用本技能,提供必要的输入参数
检查输出结果,根据需要进行后续处理

详细的输入输出格式请参考下方章节说明。

错误处理方案

以下表格列出了支付集成专家技能可能遇到的错误类型、原因分析、解决方案和恢复策略。

错误类型	原因分析	处理方式	恢复策略
API认证失败	API密钥错误或过期	检查密钥配置，重新生成token	重新配置API密钥。
接口限流	请求频率超出限制	降低调用频率，启用重试退避策略	调整请求频率。
响应超时	网络延迟或服务端负载过高	增加超时阈值，检查网络连接	优化网络连接或服务端配置。
文件不存在	路径错误或文件未创建	检查路径拼写，确认文件已生成	检查文件路径和文件系统。
文件格式不支持	扩展名不在支持列表中	转换为支持的格式后重试	转换文件格式。
权限不足	当前用户无读写权限	检查文件权限，以管理员身份运行	调整文件权限。
命令执行失败	参数错误或环境依赖缺失	检查命令语法，确认依赖已安装	检查命令参数和依赖库。
进程超时	命令执行时间过长	增加超时设置，优化命令参数	优化命令参数或脚本。
网络连接失败	DNS解析失败或防火墙拦截	检查网络配置，确认代理设置	检查网络配置和防火墙设置。

输入输出参数说明

以下表格列出了支付集成专家技能的输入输出参数说明。

参数名	类型	必填	默认值	取值范围	示例值	备注
input	string	是	-	-	-	输入数据或指令。
options	object	否	-	-	-	附加配置选项。
callback_url	string	否	-	-	-	异步处理完成后的回调通知URL。
amount	number	是	-	-	1000	订单金额，单位为分。
currency	string	是	-	-	usd	货币类型。
description	string	否	-	-	Order 001	订单描述。
metadata	object	否	-	-	{ order_id: 'ORD-001' }	业务数据。
payment_intent_id	string	否	-	-	pi_001	PaymentIntent ID。
client_secret	string	否	-	-	pi_001_secret_001	PaymentIntent 客户端密钥。
status	string	否	-	-	requires_payment_method	PaymentIntent 状态。

快速熟悉

确认运行环境满足依赖说明中的要求
在AI Agent对话中调用本技能,提供必要的输入参数
检查输出结果,根据需要进行后续处理

详细的输入输出格式请参考下方章节说明。

应用场景

场景	输入	输出
电商一次性支付	订单金额、货币、商品信息	PaymentIntent + 前端支付表单 + 后端确认逻辑
SaaS 订阅集成	产品定价、计费周期、试用期	订阅创建/管理 API + 客户门户配置
退款处理	订单 ID、退款金额、退款原因	退款 API 调用 + 财务对账记录
平台分账	卖家列表、分账比例、金额	Connect 账户配置 + 分账 API + 佣金报表
Webhook 集成	业务事件清单	Webhook 端点 + 签名验证 + 事件处理器
国内支付改造	Stripe 改为微信/支付宝	SDK 替换方案 + 接口映射 + 测试用例
不适用于:

数字货币/区块链支付(非传统支付通道)
P2P 转账与个人收款(专注于商户收款)
银行核心系统对接(支付网关层面,不涉及清算)
线下 POS 收款(专注于线上支付)
跨境资金合规咨询(需专业法律/财务顾问)
信用评分与风控建模(仅使用支付平台的风控规则)

使用指南

Step 1: 支付集成规划

确定支付模式:一次性支付 / 订阅 / 分账 / 混合
确定目标市场:海外(Stripe 为主)/ 国内(微信+支付宝)/ 双市场
选择集成方式:Payment Elements / Checkout Session / 嵌入式表单 / 原生 SDK
设计数据模型:客户/产品/价格/订阅/支付方式
规划 Webhook 事件:列出需要监听的关键事件
安全合规检查:PCI DSS 合规范围确认

Step 2: 核心支付流程实现

创建支付意图(PaymentIntent)
- 设置金额、货币、描述
- 配置自动捕获 vs 手动捕获
- 添加 metadata 关联业务数据
- 启用 3D Secure 认证(SCA 合规)
前端收集支付信息
- 使用 Stripe.js / Payment Elements
- 绝不将卡号传到自有服务器
- 处理支付确认回调
后端确认支付
- 服务端确认 PaymentIntent
- 处理 requires_action 状态(3D Secure)
- 处理支付成功/失败/待定

Step 3: 订阅管理

创建订阅:定义产品/价格/计费周期/试用期
生命周期管理:升级/降级(按比例计算)/暂停/恢复/取消
催收流程:续费失败重试 + 邮件通知
客户门户:Stripe Customer Portal 自助管理

Step 4: Webhook 处理

端点创建:注册 Webhook URL,选择事件类型
签名验证:验证 Stripe-Signature 头,防止伪造
幂等处理:基于事件 ID 去重,防止重复处理
事件路由:根据事件类型分发到对应处理器
错误重试:失败事件自动重试,记录重试日志

Step 5: 退款与争议

退款流程:全额/部分退款,退款原因记录
争议处理:接收争议通知,提交证据,跟踪状态
防欺诈:Radar 规则配置,风险评分监控

Step 6: 国内支付适配(可选)

评估是否需要国内支付(微信/支付宝)
选择国内支付 SDK 替换 Stripe
实现接口适配层(统一抽象)
国内支付测试与上线

国内外支付方案对照

维度	Stripe(海外)	微信支付(国内)	支付宝(国内)
一次性支付	PaymentIntent	JSAPI/Native/APP	电脑网站/手机网站/APP
订阅	Subscriptions	委托代扣	周期扣款
分账	Connect	分账功能	分账功能
Webhook	Stripe Webhook	支付结果通知	异步通知
3D Secure	内置支持	微信密码/指纹	支付宝密码
测试模式	sk_test_	沙箱环境	沙箱环境
凭证	Secret Key	mchid + apiV3Key	appid + 私钥
货币	多币种	CNY	CNY
费率	2.9% + $0.30	0.6%	0.6%

输入定义

参数名	类型	必填	说明
input	string	是	支付集成专家处理的输入数据或指令
options	object	否	附加配置选项,如模式选择、格式偏好等
callback_url	string	否	异步处理完成后的回调通知URL

text

用户请求:为一笔 $99.00 的订单创建支付意图,支持 3D Secure
订单ID: ORD-001

输出:

javascript

// 后端:创建 PaymentIntent
const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);
// ...
const paymentIntent = await stripe.paymentIntents.create({
  amount: 9900, // 美分
  currency: 'usd',
  description: 'Order ORD-001',
  metadata: { order_id: 'ORD-001' },
  automatic_payment_methods: { enabled: true } // 自动启用 3D Secure
});
// ...
// 返回给前端
{
  payment_intent_id: 'pi_未指定',
  client_secret: 'pi_未指定_secret_未指定',
  status: 'requires_payment_method',
  amount: 9900,
  currency: 'usd'
}

javascript

// 前端:确认支付
const stripe = Stripe('pk_live_未指定');
const result = await stripe.confirmCardPayment(clientSecret, {
  payment_method: { card: elements.getElement('card') }
});
// 处理 result.error 或 result.paymentIntent

示例2: 国内支付 - 微信支付 JSAPI(输入→输出)

输入:

text

用户请求:为 ¥99.00 的订单创建微信支付(公众号内)
订单ID: ORD-002
openid: oUpF8未指定

输出:

javascript

// 后端:创建微信支付订单
const { WechatPay } = require('wechatpay-node-v3');
const pay = new WechatPay({
  appid: process.env.WX_APPID,
  mchid: process.env.WX_MCHID,
  publicKey: process.env.WX_PUBLIC_KEY,
  privateKey: process.env.WX_PRIVATE_KEY
});
// ...
const result = await pay.transactions_jsapi({
  out_trade_no: 'ORD-002',
  description: 'Order ORD-002',
  amount: { total: 9900, currency: 'CNY' }, // 分
  payer: { openid: 'oUpF8未指定' },
  notify_url: 'https://api.example.com/wx/notify'
});
// ...
// 返回给前端(用于调起微信支付)
{
  timeStamp: '1627000000',
  nonceStr: 'abc123',
  package: 'prepay_id=wx20240101未指定',
  signType: 'RSA',
  paySign: '<参数>'
}

示例3: 创建月度订阅(输入→输出)

输入:

text

用户请求:创建每月 $29 的 Pro 订阅,7天试用期
客户: cus_未指定
价格: price_未指定 (monthly $29)

输出:

javascript

const subscription = await stripe.subscriptions.create({
  customer: 'cus_未指定',
  items: [{ price: 'price_未指定' }],
  trial_period_days: 7,
  payment_behavior: 'default_incomplete',
  expand: ['latest_invoice.payment_intent']
});
// ...
// 输出
{
  subscription_id: 'sub_未指定',
  status: 'trialing',
  current_period_end: 1700000000, // 7天后
  trial_end: 1700000000,
  latest_invoice: 'in_未指定',
  customer: 'cus_未指定'
}

环境要求

运行环境

Agent平台: Claude Code / Cursor / Codex / Gemini CLI / Windsurf 等支持SKILL.md的任意Agent
操作系统: Windows / macOS / Linux
运行时: Node.js 18+ 或 Python 3.10+

第三方依赖

依赖项	类型	是否必需	获取方式	国内替代
Stripe SDK	SDK	海外必需	`npm install stripe` / `pip install stripe`	-
微信支付 SDK	SDK	国内必需	`npm install wechatpay-node-v3`	-
支付宝 SDK	SDK	国内必需	`npm install alipay-sdk`	-
Node.js	运行时	必需	nodejs.org	npmmirror 国内镜像
公网 HTTPS 端点	网络	必需	用于接收 Webhook	国内云厂商 SLB

API Key 配置

Stripe: Secret Key (sk_live_/sk_test_) 从 Stripe Dashboard 获取
微信支付: mchid + apiV3Key + 商户证书(私钥 + 公钥)
支付宝: appid + 应用私钥 + 支付宝公钥
安全要求:
- 所有 API Key 仅存储在环境变量或密钥管理服务
- 禁止硬编码在源码中
- 禁止提交到版本控制(.gitignore 配置 .env)
- Webhook 签名密钥与 API Key 分离管理

可用性分类

分类: MD+EXEC
说明: 纯Markdown方法论,需 exec 能力运行 SDK 与测试

案例展示

以下案例展示了skill的工作流程和预期输出效果，由LLM按照skill定义的流程生成。

案例1: 电商一次性支付(PaymentIntent+3D Secure+Webhook确认)

输入:

text

场景: 电商网站一次性支付
订单: ORD-2024-001, 金额 $299.00 USD
要求: 支持3D Secure(SCA合规),Webhook确认支付状态
前端: React + Stripe.js
后端: Node.js + Express

LLM生成输出 (output/ecommerce-payment/server.js):

javascript

// 后端: 创建PaymentIntent
const express = require("express");
const stripe = require("stripe")(process.env.STRIPE_SECRET_KEY);
const app = express();
app.use(express.json());
// ...
app.post("/api/create-payment-intent", async (req, res) => {
  try {
    const { orderId, amount, currency = "usd" } = req.body;
// ...
    // 服务端金额校验(不信任客户端金额)
    const order = await getOrderFromDB(orderId);
    if (!order || order.amount !== amount) {
      return res.status(400).json({ error: "金额不匹配" });
    }
// ...
paymentIntents.create({
      amount: Math.round(amount * 100), // 转为分
      currency,
      description: `Order ${orderId}`,
      metadata: {
        order_id: orderId,
        customer_id: order.customerId,
      },
      automatic_payment_methods: { enabled: true }, // 自动启用3D Secure
    });
// ...
    res.json({
      clientSecret: paymentIntent.client_secret,
      paymentIntentId: paymentIntent.id,
    });
  } catch (error) {
    console.error("创建PaymentIntent失败:", error);
    res.status(500).json({ error: "支付初始化失败" });
  }
});
// ...
// Webhook端点(签名验证+幂等处理)
app.post("/api/stripe/webhook", express.raw({ type: "application/json" }), async (req, res) => {
  const sig = req.headers["stripe-signature"];
  let event;
// ...
  try {
    event = stripe.webhooks.constructEvent(
      req.body, sig, process.env.STRIPE_WEBHOOK_SECRET
    );
  } catch (err) {
    console.error("签名验证失败:", err.message);
    return res.status(400).send(`Webhook Error: ${err.message}`);
  }
// ...
  // 幂等检查:基于事件ID去重
  const processed = await checkEventProcessed(event.id);
  if (processed) {
    return res.json({ received: true, duplicate: true });
  }
  await markEventProcessed(event.id);
// ...
  // 事件路由
  switch (event.type) {
    case "payment_intent.succeeded":
      await handlePaymentSuccess(event.data.object);
      break;
      await handlePaymentFailure(event.data.object);
      break;
      // 3D Secure需要用户认证
      console.log("需要3D Secure认证:", event.data.object.id);
      break;
  }
// ...
  res.json({ received: true });
});
// ...
async function handlePaymentSuccess(paymentIntent) {
  const { order_id } = paymentIntent.metadata;
  await updateOrderStatus(order_id, "paid", {
    paidAt: new Date(),
  });
  await sendOrderConfirmationEmail(order_id);
}
// ...
async function handlePaymentFailure(paymentIntent) {
  await updateOrderStatus(order_id, "failed", {
    failureReason: paymentIntent.last_payment_error?.message,
  });
}
// ...
app.listen(3000);

LLM生成输出 (output/ecommerce-payment/Checkout.jsx):

jsx

// 前端: React支付组件
import { useState } from "react";
import { loadStripe } from "@stripe/stripe-js";
import { Elements, PaymentElement, useStripe, useElements } from "@stripe/react-stripe-js";
const stripePromise = loadStripe(process.env.REACT_APP_STRIPE_PUBLISHABLE_KEY);
function CheckoutForm({ clientSecret, orderId }) {
  const stripe = useStripe();
  const elements = useElements();
  const [processing, setProcessing] = useState(false);
  const [error, setError] = useState(null);
  const handleSubmit = async (e) => {
    e.preventDefault();
    if (!stripe || !elements) return;
    setProcessing(true);
    const { error, paymentIntent } = await stripe.confirmPayment({
      elements,
      confirmParams: {
        return_url: `${window.location.origin}/payment-result?order=${orderId}`,
      },
      redirect: "if_required",
    });
    if (error) {
      setError(error.message);
      setProcessing(false);
    } else if (paymentIntent.status === "succeeded") {
      // 支付成功,跳转订单页(Webhook也会同步更新)
      window.location.href = `/orders/${orderId}?status=success`;
status === "requires_action") {
      // 3D Secure认证由Stripe.js自动处理
      setError("需要进行3D Secure认证,请完成验证");
    }
  };
  return (
    <form onSubmit={handleSubmit}>
      <PaymentElement />
      {error && <div className="error">{error}</div>}
      <button type="submit" disabled={!stripe || processing}>
        {processing ? "处理中..." : "支付 $299.00"}
      </button>
    </form>
  );
}
export default function Checkout({ orderId, amount }) {
  const [clientSecret, setClientSecret] = useState(null);
  const createIntent = async () => {
    const res = await fetch("/api/create-payment-intent", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ orderId, amount }),
    });
    const data = await res.json();
    setClientSecret(data.clientSecret);
  };
  return (
    <div>
      <button onClick={createIntent}>开始支付</button>
      {clientSecret && (
        <Elements stripe={stripePromise} options=<动态配置>>
          <CheckoutForm clientSecret={clientSecret} orderId={orderId} />
        </Elements>
      )}
    </div>
  );
}

效果验证: ✓PaymentIntent创建含服务端金额校验 ✓3D Secure自动启用(automatic_payment_methods) ✓Webhook签名验证+幂等去重 ✓前端confirmPayment处理requires_action ✓React+Stripe.js集成完整

安全保障说明

风险类型	防范措施
API密钥泄露	通过环境变量配置，禁止硬编码到代码或配置文件中
命令执行风险	仅执行白名单命令，避免拼接用户输入到命令行参数中
网络通信安全	使用HTTPS协议，验证SSL证书有效性
敏感数据暴露	输出结果中不包含密钥、令牌等敏感信息
使用前请确认已阅读依赖说明章节，确保运行环境满足安全要求。

常见疑问汇编

Q1: 支付集成专家支持哪些支付方式？

A: 支付集成专家支持Stripe官方优选实践，同时提供微信支付、支付宝和银联的国内替代方案。

Q2: 如何使用支付集成专家进行订阅管理？

A: 支付集成专家提供订阅管理功能，您可以通过配置订阅计划、设置自动续订和灵活调整订阅设置来管理用户订阅。

Q3: 支付集成专家如何处理Webhook？

A: 支付集成专家能够处理Webhook，确保您能够实时接收支付事件通知，如支付成功、退款等，并据此执行相应的业务逻辑。

Q4: 支付集成专家如何处理退款？

A: 支付集成专家支持退款功能，您可以通过系统提供的接口发起退款请求，并跟踪退款状态，确保退款流程的顺利进行。

Q5: 支付集成专家适用于哪些场景？

A: 支付集成专家适用于电商支付、SaaS订阅、退款处理、平台分账、发票管理、Webhook集成等多种场景，能够满足不同业务需求。

注: 本SKILL.md超过500行上限, 已截断尾部非核心章节以满足L1格式要求。完整内容见版本库历史。

支付集成专家

Install

支付集成专家

核心功能特点

功能边界条件

功能边界条件

快速开始

错误处理方案

错误处理方案

输入输出参数说明

输入输出参数说明

快速熟悉

应用场景

使用指南

Step 1: 支付集成规划

Step 2: 核心支付流程实现

Step 3: 订阅管理

Step 4: Webhook 处理

Step 5: 退款与争议

Step 6: 国内支付适配(可选)

国内外支付方案对照

输入定义

示例2: 国内支付 - 微信支付 JSAPI(输入→输出)

示例3: 创建月度订阅(输入→输出)

环境要求

运行环境

第三方依赖

API Key 配置

可用性分类

案例展示

案例1: 电商一次性支付(PaymentIntent+3D Secure+Webhook确认)

安全保障说明

常见疑问汇编

Q1: 支付集成专家支持哪些支付方式？

Q2: 如何使用支付集成专家进行订阅管理？

Q3: 支付集成专家如何处理Webhook？

Q4: 支付集成专家如何处理退款？

Q5: 支付集成专家适用于哪些场景？

Related skills