收银页对接与终端能力矩阵

同一个收银 URL 在不同终端上的行为不同：PC 渲染二维码，手机微信外走推荐路径，微信内直接调起微信支付。按矩阵设计，不要自己发明分支。

小豆支付开放平台是面向已有自有系统的商家的支付接入服务：通过服务器对服务器的接口，把支付宝与微信收款接进商家自己的系统，并以签名事件通知回传支付状态；资金由持牌支付公司收付结算。个人也能申请：主体类型选「个人」，身份证 + 本人银行卡即可完成商户进件。央行持牌机构清算，安全可靠的个人和企业支付接口。

本篇回答一个问题：把收款材料交给买家之后，各终端上会发生什么。终端不同、通道不同，买家看到的行为也不同——照着矩阵做，不要自己发明分支。

1. 终端能力矩阵（四端 × 两通道）

通道放行由平台整体控制（不区分应用，也没有自助查询面），粒度是「通道 × 交易形态」。 微信 JSAPI 已开放：买家在微信内打开收银页即可调起微信支付（仅限微信内浏览器）；微信外手机浏览器与商家 App 内没有「直接拉起」形态。上面这张矩阵描述的是能力面（两个通道的终端行为都已按此实现）；其他通道或交易形态尚未放行时，用它下单会得到 422 OPEN_API_CHANNEL_UNAVAILABLE——这是可预期的正常拒绝，不要按故障处理、也不要重试刷量。接入前与对接人确认你要用的通道与交易形态是否已放行，不要靠试探下单去确认。

桌面微信内置浏览器也命中「微信内」分支（平台按 UA 判定，不为桌面微信单独分派形态）：链接若在 PC 微信里被打开，页面同样走微信内的授权/调起链。若买家在 PC 微信里完不成支付，让其用手机微信打开同一条链接即可——不要为此在自有容器里另做一套。

结构性说明（不是实现细节，是这套设计的原因）：平台侧没有「微信正扫」形态——微信收款只有「在微信内打开页面后由页面调起」这一条路，所以微信的「PC 扫码」本质是中转链：二维码里放的是平台收银页地址，扫码后落到手机微信内页面，再由页面调起支付面板。请按这个前提设计你的 UX 文案，不要向买家承诺「扫码直接出付款码」。

商家 App / 宿主内的硬约束（违反即不可用）

• ✅ 用系统浏览器打开收银链（等价「跳转外部浏览器」语义）。
• ❌ 禁止在你自己的 App 的 WebView / 内嵌浏览器里打开收银页——容器 UA 与浏览器特性失真会导致终端判定错误，买家会落到拉不起来的页面。
• ❌ 商家侧没有「App 内直接调起微信支付」的形态；App 内的微信支付同样走推荐路径。

2. 用法一：自渲染官方收款码（商家 PC 页面）

下单响应里的 qrCode 就是官方收款码，可直接在你自己的 PC 页面渲染成二维码，与平台收银页同形。

取响应 qrCode
 ├─ 为空（null） → 该单不下发收款码（渠道不符 / 非官方码 / 无有效尝试）：改用 payUrl 中转链
 └─ 非空 → 渲染前做一次前缀防呆复检（只接受官方收款码前缀）
            └─ 通过 → 渲染二维码 → 买家扫码 → 轮询你自己的服务端拿终态
            └─ 不通过 → 不渲染、不报错、不打印内容，回退 payUrl 中转链

红线：

• 仅支付宝渠道、仅官方前缀才会下发；前端不得拼装、改写、代理转发该地址。
• 不得把 qrCode 写进日志、埋点、门户管理面或事件通知。
• 只在下发响应有效：查询接口恒为 null；需要新码走重拉起端点（新尝试=新码）。过期旧码不可复用。

3. 用法二：payUrl 中转链（两种标准用法）

payUrl 是平台收银页地址，两种用法都标准：

要点：

• 用 payUrl 原值，不要拼接参数、不要加自己的 query。
• 「扫码 → 平台收银页 → 自动拉起」这两步依赖平台收银页的终端分派能力（见矩阵），你的页面不需要判断终端。
• 买家在收银页点「返回商家」才会回跳你冻结的 returnUrl（不是自动跳转）。按钮由收银页本次会话首次观察到支付成功时提供，回跳凭证一次性：刷新过页面，或此前已点击过一次（含浏览器回退后再点）时，不再提供或不再可用。凭证有效期 = 支付窗口（默认 600 秒，平台侧可调）+ 终态展示宽限 600 秒；超时后点击会看到一个中性提示页（不是报错 JSON，也不会泄露订单信息）。扫码支付（PC 出码 → 手机付款）不受此限：只要收银页保持打开并轮询到支付成功，按钮照常提供并可回跳。它只是导航，不是终态——见下一节。
• 微信内（JSAPI）支付完成后：微信会接管完成页（收银页随之关闭），买家不经过收银页的「返回商家」按钮；买家可从微信支付记录中的「商家小票」卡片点「返回商家」回到你冻结的 returnUrl——该通道由平台侧配置、无需商家开通，落点与收银页按钮是同一个 returnUrl；同样是买家点击的导航：不是自动跳转，也不是终态。因此微信内流程请你把 returnUrl 落地页按「展示 + 轮询自己的服务端」设计。

4. 手机微信外：推荐路径（逐字引导文案）

手机浏览器（微信外）打开一笔微信支付单时，平台收银页会给出下面这组引导。商家在自己的页面/文案里若需要复述，请逐字使用（这是一份被两侧共同引用的文本源）：

不要向买家承诺「点一下就到支付面板」：微信不允许第三方应用代发消息，第 ②③ 步必须由买家在微信内完成。平台能做的是把「复制链接 + 唤起微信」合成一步。

4b. 手机微信外：支付宝单的手势引导（逐字引导文案）

手机浏览器（微信外）打开一笔支付宝单时，平台收银页渲染官方收款码，并给一个手势主按钮。同样请逐字使用（同一份文本源）：

为什么不是「进入即自动打开」：浏览器只把用户手势触发的那次打开交给支付宝 App；无手势的自动跳转会被「自动拉起应用/自动跳转」策略吃掉（真机实测：两个主流手机浏览器均连导航都不发生）。另外：平台收银页里的二维码是以 canvas 绘制的，部分浏览器/微信内长按识别可能无效——因此截屏 → 支付宝扫一扫 → 相册才是各端都成立的通用兜底。也别用「复制支付链接到支付宝打开」——支付宝没有「粘贴链接付款」入口，那是死路。

5. 终态从哪来

无论走哪条路径，收银页打开 / 回跳 / 用户点完成都不是终态。商家必须：

1. 接事件通知（webhook 验签）作为主路径；
2. 接查单接口作为补偿与对账路径；
3. returnUrl 落地页只做展示与轮询自己的服务端。

6. 本地验证矩阵

demo/h5-cashier/ 内置终端预览页（可手动切换 PC / 手机微信外 / 手机微信内三种形态）与可运行示例（demo 只在公开仓提供，不在门户的两个下载包内）：

node demo/h5-cashier/server.js

<!-- xd-terminal-matrix-mirror -->

{
  "channels": [
    "ALIPAY_H5",
    "WECHAT_H5"
  ],
  "terminals": [
    "pc",
    "mobileOutsideWechat",
    "mobileInsideWechat",
    "merchantHost"
  ]
}

<!-- /xd-terminal-matrix-mirror -->