中国道商户接入中心

SDK 接入

适合大部分商户。商户嵌入 SDK 页面/组件，SDK 负责商品展示、下单参数收集和部分体验封装。测试联调请登录商户后台操作。

面向：商户前端 + 商户后台配置

OpenAPI 接入

适合有自研后端能力的商户或系统级合作方。使用 AppId/AppSecret/HMAC 签名调用商品、余额、下单、查单接口。

面向：商户服务端/合作方系统

三层价格

1. 上游成本价：平台向权益供应商采购/结算的底价，仅平台内部可见。
2. 平台基准结算价：平台给商户的默认结算价，必须大于等于上游成本价，是平台毛利底线。
3. 商户零售价：商户展示给用户并向用户收款的价格，必须大于等于商户结算价。

价格安全底线

• 平台基准结算价 >= 上游成本价。
• 商户结算价 >= 平台基准结算价。
• 用户支付价/商户零售价 >= 商户结算价。
• 发现倒挂、空价格、过期报价时，平台会拒单或回退到安全建议价。

商户最短接入

1. 平台开通商户、产品授权、SDK 域名白名单、商户收银台地址与支付回调地址。
2. 商户页面引入 /sdk/commercial-v2/commercial-v2.css 与 /sdk/commercial-v2/commercial-v2-sdk.js。
3. 调用 ChinaDaoCommercialV2.init 渲染商户权益商城。
4. 用户选择权益，SDK 自动完成城市/资源/规格选择，并请求后端 quoteId 锁价。
5. 平台创建待支付订单并返回 cashierUrl，地址仅包含一次性短期 token=cst_xxx，不暴露订单号、金额、签名等敏感参数。
6. 商户前端只负责跳转 cashierUrl，不要解析或自行拼接 merchantId/orderNo/quoteId/amount/timestamp/nonce/sign。
7. 用户在商户收银台付款，商户服务端通过 /sdk/payment/notify 或 /sdk/order-pay-notify 签名回调平台确认收款，平台履约并回调商户。

正式接入代码

<div id="merchant-benefit-sdk"></div>
<link rel="stylesheet" href="/sdk/commercial-v2/commercial-v2.css">
<script src="/sdk/commercial-v2/commercial-v2-sdk.js"></script>
<script>
ChinaDaoCommercialV2.init({
  merchantId: '你的商户ID',
  container: '#merchant-benefit-sdk',
  merchantName: '商户权益商城',
  apiBase: '/prod-api/openapi/v1',
  liveMode: true,
  merchantMemberId: '商户侧会员ID',
  memberOpenId: '微信openId/unionId，可选',
  memberMobile: '会员手机号，可选',
  memberName: '会员昵称，可选',
  memberSource: 'h5'
});
</script>

旧版 /sdk/sdk.js 仅作为历史兼容文件保留，新商户统一接入 SDK v2。

关键入口

产品准入口径

用户端产品展示以 product-admission.json 为准，分为可购买、可查/联调、即将开放、暂不可接入。只有已验证 query/quote/order-create 链路的产品才允许进入购买。

token 化跳转

/sdk/order-create 返回的 cashierUrl 是平台生成的短期跳转地址，格式类似 /sdk/commercial-v2/merchant-cashier.html?token=cst_xxx。浏览器 URL 不再携带 merchantId/orderNo/quoteId/amount/timestamp/nonce/sign。

商户前端只需要跳转该地址；不要解析、保存、转发或自行拼接 token。token 过期后需要重新创建订单或重新发起支付流程。

支付确认边界

token 仅用于收银台展示订单信息，不代表支付成功凭证。

正式支付成功后，必须由商户服务端调用 /sdk/payment/notify 或 /sdk/order-pay-notify，携带 merchantId/orderNo/quoteId/amount/timestamp/nonce/sign 完成验签确认。浏览器前端不能直接确认支付成功。

正式接入

商户后台

商品授权、域名白名单、密钥配置和订单查询请在商户工作台完成。

订单状态

WAIT_PAY 待商户确认收款 → PAID 已确认 → PROCESSING 上游处理中 → SUCCESS 成功 / CLOSED 失败关闭 / REFUNDED 已退款。

回调要求

商户按 orderNo 做幂等。平台可能因网络失败重试通知，同一订单重复通知不得重复发货/重复退款。

SDK 初始化字段

订单归属优先级

1. merchantId + merchantMemberId
2. merchantId + memberOpenId
3. merchantId + memberMobile
4. 浏览器本地订单缓存仅作为老版本兜底，不作为正式归属依据。

后端订单表已新增 merchant_member_id、member_mobile、member_open_id、member_source 字段，均按商户维度索引查询。

SDK端表现

• 订单详情显示售后状态。
• 符合条件的订单展示“申请退款/售后”按钮。
• 提交前有二次确认，提交后自动刷新订单状态。
• 订单列表新增售后筛选，便于会员查看处理中/已退款订单。

接口边界

退款申请仅创建售后请求，不代表资金立即原路退回。实际退款需平台/商户按支付渠道、履约状态和风控规则审核处理。

生产环境禁止用真实订单做退款演示，除非商户明确授权。

正式流程

1. 查询真实门店和菜单 SKU。
2. 调用 POST /openapi/v1/sdk/food/quote?merchantId=3 生成报价快照。
3. 订单创建只提交 quoteId，不要提交前端计算金额。
4. 后端按 Redis 价格快照写入订单金额，保障 quote/order/DB 一致。

星巴克正式服验收样例

商品：双杯美式咖啡

productId：sbk_135533136191685166

价格：43.20

测试订单：TEST202605202018285095

验收：quote = order = DB = 43.20