qianyubtcandClaude Fable 5
f87ec65541
- Go 服务端：唯一金额/备注码/回填订单编号三路匹配、托管收银页、HMAC 回调七级重试、SQLite 单二进制 - SDK：Go / Java / PHP / Python，共享签名测试向量（docs/test_vectors.json） - 跨语言 e2e（真实二进制 × Python SDK × mock 币安）、GitHub Actions CI、Dockerfile - 协议文档 docs/protocol.md、调研与实测结论 docs/research.md Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
3.4 KiB
3.4 KiB
调研与实测结论（为什么这样设计）
时间：2026-09。以下结论来自币安官方文档、官方开发者论坛与真实个人账号实测。
官方能力边界
| 事实 | 来源 |
|---|---|
| Binance Pay Merchant API 功能完整（下单/退款/webhook/收银台），但入驻需企业实体账户+ 公司注册文件 | 商户申请 FAQ |
| 个人商户账户 2024-11-05 停止新申请、2025-02-28 终止 | 多家集成商公告转述 |
| 商户后台的「收款链接」只能后台手工创建，无 API | merchant.binance.com 文档 |
| 个人版收款链接（可设币种金额、30 天过期）与定额收款码存在，但无创建 API | 官方 FAQ |
| 网页/App 的私有 bapi 接口被官方明确表态「非公开、不建议使用」；条款禁止脚本化访问非公开功能 | 官方论坛、Terms §28(i) |
个人账户可用现货 API Key（只读）调 GET /sapi/v1/pay/transactions 读取 Pay 流水 |
官方文档 |
| Pay ID 已于 2025-01-01 停用；收款标识为 UID / 邮箱 / 手机号 / 二维码 | 官方公告 |
| Pay 内部转账 0 手续费、即时到账、不可撤销；接收无限额 | 官方 FAQ |
→ 结论：个人账户唯一合规的程序化通道是只读流水接口，所以本网关是「被动对账」模型， 不创建支付单、不发起任何资金操作。
关键实测（真实个人账号 + 真实转账）
文档没写或写错、但被实测确认的行为：
| 实测项 | 结果 |
|---|---|
| 返回字段比文档多 | 实测有 orderId（18 位数字）、note（付款备注原文）、counterpartyId（对方 Pay 账户 ID，每条都有） |
| 付款方 App 显示的「订单编号」 | = 接口返回的 orderId（现场对照确认）→ 回填核验直接比对该字段 |
| 金额精度 | 0.1234 USDT 原样到账 → 至少 4 位小数，唯一尾数容量充足 |
| 备注 | 付款方填的备注通过 note 原样回传 → 备注码匹配成立 |
| 到账延迟 | 到账即出现在接口，检测延迟 ≈ 轮询间隔 |
| 方向 | amount 收款为正、付款为负 |
payerInfo.binanceId |
不一定返回（部分记录缺失）→ 网关用 counterpartyId 兜底标识付款方 |
文档示例的 M_P_ 前缀 transactionId、"无备注字段" |
与实测不符，实测为 P_ 前缀且有 note 字段 |
接口约束（设计输入）
- 签名接口，权重 3000（按 UID 计，限额 180000/分钟 → 理论最高约 1 次/秒）
- 不传时间返回最近 90 天；时间跨度最长 90 天；最多查 18 个月；
limit最大 100、无游标分页 → 网关用时间窗口滑动 + 满页向前翻页 - 有地区差异风险：论坛有账号反馈该接口恒返回空 → 部署前先跑
tools/pay_history_probe.py自测
被否决的方案
| 方案 | 否决原因 |
|---|---|
| cookie / JWT 监听网页流水 | 有官方只读 API 平替；登录态会过期；违反条款；风控风险 |
| 程序化创建个人收款链接 | 无公开 API，只能逆向私有 bapi，官方明确不建议 |
| 让付款方必须回填订单号 | 体验差、漏填率高 → 降级为兜底入口，主链路零动作 |