平台概览
Web3SDK 是一个面向全球中小商家的 Web3 支付平台。商家通过平台收取 USDT / USDC, 平台负责盯链、确认、回调与对账;商家在自己的系统里完成下单、发货与对账。
平台由四块拼成,理解它们的分工之后,文档里任何一页都能对上位置。
四块拼图
| 组成 | 面向谁 | 用什么访问 | 认证方式 |
|---|---|---|---|
| 开放接口(Open API) | 你的服务端 | POST /api/pay/open/createOrder、GET /api/pay/open/queryOrder | 请求头 X-Pay-Api-Key |
| 收银台(买家侧) | 你的买家 | 收款台链接与二维码、收银页公开接口 | 无登录态,靠一次性票据与限流自保 |
| 商户后台 | 你的运营 | 商户号登录后的后台页面与商户侧接口 | 账号密码换 JWT |
| 平台侧配置 | 我们 | 链与代币、费率与规则、商户授权 | 平台内部,不对外 |
对商家来说,日常只需要碰前两块;第三块用来配收款地址、看订单与对账。
数据流
一笔支付的完整路径:
你的服务端 ──(1) 创建订单──▶ 开放接口
│ │
│ ▼
│ 平台订单 + 收款地址 + 识别信息
│ │
买家 ◀──(2) 扫码付款──────────┘
│
▼
链上交易 ──(3) 平台扫块识别──▶ 订单:已提交 → 已确认
│
你的服务端 ◀──(4) 回调 notifyUrl────┘
│
└──(5) 你的服务端用查询接口核对(以查询结果为准)从这里开始
5 分钟接入
注册拿 KEY → 配收款地址 → 创建第一张订单 → 收回调。每一步都有可直接照做的示例。
术语与概念
商户号、收款地址、收银台、开放接口、链与代币、回调 —— 先建立词汇表再读接口。
认证与签名
开放接口怎么认证、回调怎么验签、密钥怎么轮换。
创建订单
下单接口的字段、金额约定、幂等键与返回结构。
回调通知与验签
回调什么时候发、重试几次、怎么保证不重复发货。
错误码
常见错误现象与排查顺序,按可读的类别名组织。
选哪条接入路径
平台与建站
一条贯穿全文的规矩
API KEY 只能放在你自己的服务端。 所有 SDK 示例里的下单调用都由你的后端执行, 前端只负责展示金额、唤起钱包、把交易哈希回传。把 KEY 放进浏览器或 App 包体里, 等于把回调通道的钥匙发出去。