From e7f989588ed6a036d6c0a1ba67af38061cac08bd Mon Sep 17 00:00:00 2001 From: wangjia <809946525@qq.com> Date: Sat, 11 Jul 2026 12:06:27 +0800 Subject: [PATCH] =?UTF-8?q?docs(pay):=20=E6=94=AF=E4=BB=98=E6=B8=A0?= =?UTF-8?q?=E9=81=93=E5=85=AC=E5=BC=80=E6=96=87=E6=A1=A3(=E5=93=AA?= =?UTF-8?q?=E5=90=92/=E6=94=AF=E4=BB=98=E5=AE=9D=20+=20stripe/crypto=20?= =?UTF-8?q?=E6=A1=86=E6=9E=B6)+=20=E7=99=BB=E8=AE=B0=20index?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 单一入口登记各支付渠道接入信息(类型/结算币种/官方文档/provider 位置/ Method 名/接入形态/凭证位置指针/状态),新渠道后续往这加。不含任何 商户号/密钥/私钥/地址等敏感值,凭证一律指向 Bitwarden 条目名。 Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_013nMthbVEmQquxBRKb9Fj8u --- docs/index.html | 5 ++ docs/payment-channels.html | 167 +++++++++++++++++++++++++++++++++++++ 2 files changed, 172 insertions(+) create mode 100644 docs/payment-channels.html diff --git a/docs/index.html b/docs/index.html index 5594b1e..fd47f8f 100644 --- a/docs/index.html +++ b/docs/index.html @@ -29,6 +29,11 @@

独立支付服务（Go·Gin·GORM），多业务 × 多渠道（支付宝先行，微信留接口）。新增文档请同步登记此处。

🎨 设计方案 / 技术方案

+ +
支付渠道接入登记 ⭐
+
公开文档：各支付渠道接入信息的单一登记入口（新渠道往这加）。哪吒支付（开发中）/ 支付宝 / Stripe / Crypto(USDT-TRC20) 四渠道，统一字段：类型/结算币种/官方文档/provider 位置/Method 名/接入形态概要/凭证管理位置指针/状态。不含任何商户号、密钥、私钥、地址等敏感值，凭证一律指向 Bitwarden 条目名。
+
v1.0 · 2026-07-11 · 公开 · 持续追加
+
pay v2 · 多产品统一支付 + 履约网关设计 ⭐
把 pay 干净重设计成 pangolin/jiu/dudu/未来共用的支付层。三个正交关注点：pay 收款（本设计核心）/ codes 兑换（平级共享内核）/ entitlement 开通（各产品自留）。核心模型 Order+Attempt+Account（一单 N 渠道只一个成功·可取消·可退款·多账户路由）；6 个 render_type 多态（pay 下发数据不下发 UI，样式归业务方；加同形态新渠道零改 client）；Provider adapter（verify_callback 吸收渠道差异）；webhook v2 加 event_type（退款/订阅/拒付，断代 v2.0.0）；退款三向（业务/人工 crypto/平台 IAP）；促销折扣归业务、金额权威归 pay；多币种 + 配置驱动渠道 + 国内外同码双部署；crypto(USDT-TRC20 自托管)抗风控兜底；recurring 设计进模型暂不实现。含 SVG 架构图 + 设计决策知识点。
diff --git a/docs/payment-channels.html b/docs/payment-channels.html new file mode 100644 index 0000000..b3f1817 --- /dev/null +++ b/docs/payment-channels.html @@ -0,0 +1,167 @@ + + + + + +pay · 支付渠道接入登记 + + + +
+
pay · Channel Registry
+

支付渠道接入登记

+

pay v2 支付渠道接入的单一登记入口——每接一个新渠道，在本文档追加一节。汇总各渠道的官方文档链接、pay 侧 provider 位置、接入形态概要、凭证存放位置指针。

+ +
+公开性声明：本文档公开可读，不含任何商户号 / API 密钥 / 私钥 / 证书 / 真实收款地址 / Bitwarden 具体取值。凭证一律只写「走 Bitwarden 某条目，经 rbw 灌 env」这类位置指针，实际值不出现在本文档或 git 仓库任何地方。 +
+ +

pay v2 Provider 接口

+

每个渠道在 internal/provider/<name>/ 下实现统一的 provider.Provider 接口（定义于 internal/provider/provider.go），网关侧不感知渠道差异：

+ + + + + + + + + +
方法作用
Method()渠道注册名（如 alipay/stripe/crypto），也是配置里 method 字段的值
Capabilities()渠道能力自述：支持的 render_type、是否支持退款/续订、结算币种、可服务区域
Create(ctx, CreateRequest)拿 pay 已定金额/币种/账户去渠道建单，产出 Session{ProviderRef, RenderType, Payload}
VerifyCallback(ctx, CallbackInput)解析并验签渠道异步回调（HTTP body/头/query），产出归一化 PaidEvent
Query(ctx, QueryRequest)主动查单兜底（回调丢失时的定时轮询/对账）
+

可选扩展接口：RefundingProvider（退款）、RecurringProvider / SubscriptionProvider（续订）、OrphanScanner（自托管渠道的孤儿到账扫描）。

+

render_type（客户端只认这 6 种付款意图形态，不下发任何 UI，样式归业务方自绘）：

+ + + + + + + + + + +
值含义当前用者
redirect跳转到渠道收银台 URLalipay（page/wap）、stripe（Checkout）
qr渠道二维码内容，前端自行渲染alipay（当面付 precreate）
crypto_address收款地址 + 精确到账金额crypto
native_pay原生支付组件拉起（如小程序/App SDK）暂无渠道使用
sdk_handoff交由客户端 SDK 处理支付流程暂无渠道使用
iap_receiptApp Store/Play 内购收据校验暂无渠道使用
+ +

渠道总览

+ + + + + + + + +
渠道类型结算币种Method()状态
哪吒支付第三方 RSA 聚合支付CNYnezha开发中
支付宝自有商户直连CNYalipay已接入
Stripe自有商户直连（海外网关）USDstripe已接入
Crypto（USDT-TRC20）链上自托管USDTcrypto已接入
+ +

① 哪吒支付（nezha）

+
+

哪吒支付 开发中

+
+
类型
第三方 RSA 聚合支付
+
结算币种
CNY
+
官方文档
https://nzzf.org/doc/index.html
+
provider 位置
internal/provider/nezha/（待建）
+
Method() 名
nezha
+
凭证管理
Bitwarden 条目 nzzf（商户号 pid + 商户私钥 + 平台公钥），仅按需 rbw get 取用，不入文档/git
+
+

接入形态概要（据官方文档）：

+
    +
  • 签名：SHA256WithRSA + Base64。签名串 = 非空参数（排除 sign/sign_type/数组）按参数名 ASCII 升序拼 key=value&...（不拼密钥）；商户私钥签、平台公钥验。
    • +
  • 下单：POST https://nzzf.org/api/pay/create（form-urlencoded）。字段：pid / type / out_trade_no / notify_url / return_url / name / money（元）/ timestamp / sign / sign_type；响应 JSON 含 payurl（收银台跳转，对应 render_type=redirect）+ qrcode（二维码，对应 qr）。
    • +
  • 异步通知：GET 回调，字段含 trade_no / out_trade_no / money / trade_status / sign；平台公钥验签；trade_status=TRADE_SUCCESS 为成功；商户须回纯文本 success（对应 VerifyCallback）。
    • +
  • 查单：POST https://nzzf.org/api/pay/query，status=1 表示已支付（对应 Query）。
    • +
  • 支持的支付方式：支付宝等（由 type=alipay 等参数选择，聚合渠道内部路由）。
    • +
+
+ +

② 支付宝（alipay）

+
+

支付宝 已接入

+
+
类型
自有商户直连
+
结算币种
CNY
+
官方文档
https://opendocs.alipay.com/（当面付 / 手机网站支付 / 电脑网站支付）
+
provider 位置
internal/provider/alipay/alipay.go
+
Method() 名
alipay
+
凭证管理
Bitwarden 条目 ali pay key（字段 app_private_key / alipay_public_key / appid），经 rbw get 灌服务器 env（见 上线状态与部署 Runbook）
+
+

接入形态概要（源自 internal/provider/alipay/alipay.go + 支付宝密钥申请与备案依赖 / 支付宝收款页时序图与架构）：

+
    +
  • 签名：RSA2（SHA256WithRSA），商户应用私钥签、支付宝公钥验（smartwalle/alipay/v3 SDK 封装）。
    • +
  • 下单：按 metadata["render"] 与端型三选一——当面付 alipay.trade.precreate（render=qr，出二维码，render_type=qr）；手机端 alipay.trade.wap.pay（TradeWapPay，QUICK_WAP_WAY）；PC 端 alipay.trade.page.pay（TradePagePay，FAST_INSTANT_TRADE_PAY），两者均产出跳转 URL（render_type=redirect）。渠道以 out_trade_no 归位，仅支持 CNY。
    • +
  • 异步通知：DecodeNotification 用支付宝公钥验签；交易状态归一化——WAIT_BUYER_PAY→pending，TRADE_SUCCESS/TRADE_FINISHED→succeeded，TRADE_CLOSED→failed；商户须回 success。
    • +
  • 查单兜底：alipay.trade.query（TradeQuery），用于回调丢失/超时时的定时轮询。
    • +
  • 退款：alipay.trade.refund（同步接口，TradeRefund），out_request_no 作幂等键支持部分退款。
    • +
+
+ +

③ Stripe（stripe）

+
+

Stripe 已接入

+
+
类型
自有商户直连（海外网关）
+
结算币种
USD
+
官方文档
https://docs.stripe.com/（Checkout Sessions / Webhooks / Subscriptions）
+
provider 位置
internal/provider/stripe/stripe.go
+
Method() 名
stripe
+
凭证管理
Bitwarden（Stripe API Secret Key + Webhook Signing Secret，账户级 CredentialEnvPrefix 对应 env 后缀 SECRET_KEY / WEBHOOK_SECRET），经 rbw 灌 env；具体条目名待生产上线时在 Bitwarden 建立，不写入本文档
+
+

接入形态概要：托管 Checkout（hosted Checkout Session），一次性支付走 mode=payment、订阅走 mode=subscription，均产出跳转 URL（render_type=redirect）。Webhook 验签用官方 SDK webhook.ConstructEvent（HMAC + 时间容差）；处理 checkout.session.completed（入账/订阅激活）、invoice.paid（续费）、customer.subscription.deleted（订阅取消）、invoice.payment_failed（逾期）、charge.dispute.created（拒付）。退款走 /v1/refunds（Idempotency-Key 幂等）；订阅续费由 Stripe 网关自身调度（RecurringKindGatewayScheduled），pay 不主动发起扣款。

+
+ +

④ Crypto · USDT-TRC20（crypto）

+
+

Crypto（USDT-TRC20） 已接入

+
+
类型
链上自托管
+
结算币种
USDT
+
官方文档
https://developers.tron.network/（TronGrid API，用于扫链查询）
+
provider 位置
internal/provider/crypto/crypto.go
+
Method() 名
crypto
+
凭证管理
Bitwarden（收款地址 watch-only + 可选 TronGrid API Key，账户级 env 后缀 ADDRESS / TRONGRID_KEY），私钥不由 pay 持有；具体条目名不写入本文档
+
+

接入形态概要：每账户一个固定收款地址（watch-only，pay 从不持有私钥），每单在基础价上叠加随机唯一尾数（微 USDT 级）区分订单身份，冷却窗防金额复用误配。无渠道异步回调（VerifyCallback 恒返回 ErrNotSupported），到账完全靠查单：定时扫 TronGrid only_confirmed 已确认交易，按「收款地址 + 精确金额 + 块时晚于建单时间」匹配（render_type=crypto_address）。另实现 OrphanScanner：扫描到账但不匹配任何在途订单的转账，供对账人工核对。资金归集（sweep 到冷存储）是独立的线下操作，不在 pay 范围内。

+
+ +

凭证管理约定

+

所有渠道凭证统一走 Bitwarden，按需 rbw get 取出灌入服务器环境变量（CredentialEnvPrefix + 字段名，如 ALIPAY_APP_PRIVATE_KEY），不落配置文件、不落 git 仓库、不进聊天记录。已上线渠道的具体 Bitwarden 条目名见各渠道小节；未上线渠道的条目在生产接入前另建，同样不预先写入本文档。部署细节参见 上线状态与部署 Runbook。

+ +
+ +