Native（PC 扫码）支付集成指南

在 CloudBase 控制台「集成中心」创建微信支付集成后，平台会自动为你生成一个 HTTP 云函数，封装好下单、查单、退款、回调等全部能力。本指南介绍如何基于该云函数完成 Native 支付——即 PC 网页/桌面应用展示二维码，用户用手机微信扫码完成支付的接入闭环。

关于函数名的约定：集成中心生成的云函数名形如 <集成名>-<随机串>（例如 miniapp-wxpay-rwmx67sc）。为方便讲解，本文统一称其为 pay-common——你在自己的代码中替换为实际函数名即可。

适用场景：PC 收银台、桌面客户端、自助终端、广告屏等所有"非微信内浏览器"的扫码支付需求。

不适用：

微信内 H5 → 用 JSAPI 网页支付
小程序 → 用小程序支付
微信外手机浏览器 → 用 H5 支付

整体调用链路：

正向请求：网页 → CloudBase 云 API 网关（accessToken 鉴权）→ pay-common HTTP 云函数 → 微信支付 API（/v3/pay/transactions/native）
异步回调：微信支付 → 集成中心（验签 + 解密）→ pay-common → 业务侧
状态同步：网页轮询查单接口或前端 WebSocket/SSE 推送，发现支付完成后跳转结果页

架构总览

整体分为正向下单与异步回调两条链路（Native 不需要 openid，下单返回 code_url 由前端生成二维码，支付完成靠轮询/推送感知）：

Native 支付的关键特点：

维度	与 JSAPI/小程序的区别
下单接口	`/v3/pay/transactions/native`（不同接口）
下单返回	`{ code_url: "weixin://wxpay/bizpayurl?pr=..." }`，需要前端生成二维码
是否需要 openid	不需要，无 `payer.openid` 字段
`appid`	公众号 AppID 或小程序 AppID（已与商户号关联即可）
支付完成感知	没有前端调起回调，需要轮询查单或服务端推送
运行环境	任意浏览器/客户端，无微信容器依赖

Native 支付的服务端逻辑与小程序/JSAPI 走的是同一个 pay-common 云函数模板，只是 _action 不同，路由内部走不同的下单 strategy。

前置条件

项	要求
公众号 / 小程序 / 移动应用	至少其一已通过认证；其 AppID 将作为下单 `appid`
微信支付 Native 支付权限	商户平台「产品中心」中开通 Native 支付（一般认证后默认开通）
微信支付商户号	已申请并完成与上述 AppID 的关联
商户超管权限	用于下载 API 证书、设置 APIv3 密钥
前端二维码渲染	任意 QR Code 库（`qrcode` / `qrcode.js` / 后端生成 PNG）

第一步 · 准备商户凭证

#	字段	说明
1	`appId`	公众号 / 小程序 / 移动应用 AppID（已与商户号关联）
2	`merchantId`	10 位数字商户号
3	`apiV3Key`	32 字符 APIv3 密钥
4	`merchantSerialNumber`	40 位十六进制证书序列号
5	`privateKey`	`apiclient_key.pem` 完整内容
6	`wxPayPublicKey`	微信支付公钥 PEM
7	`wxPayPublicKeyId`	公钥 ID（`PUB_KEY_ID_...`）

Native 支付下，appId 可以是公众号或小程序 AppID（甚至开放平台移动应用 AppID），只要在商户平台「Native 支付」产品下与商户号完成关联即可。

第二步 · 在 CloudBase 创建集成

与小程序支付指南完全相同。集成创建后，系统自动生成：

HTTP 云函数 pay-common
回调基础域名 https://<集成标识>.integration-callback.tcloudbase.com
支付回调路径 /wechatpay/order
退款回调路径 /wechatpay/refund

Native 支付与 JSAPI/小程序走的是同一个回调地址，但商户平台里的配置项是分开的，必须分别设置，缺一个都不会收到对应的回调。

在商户平台配置 Native 支付回调链接

完整支付回调 URL = 回调基础域名 + /wechatpay/order，例如：

https://<集成标识>.integration-callback.tcloudbase.com/wechatpay/order

设置路径：微信支付商户平台 → 产品中心 → 我的产品 → Native 支付 → 产品设置 → 开发配置 → 支付配置 → Native 支付 → Native 支付回调链接，点击右侧「修改」填入上述 URL 即可。

💡 与 JSAPI/小程序「支付通知 URL」的区别

Native 支付：本节红框所示的「Native 支付回调链接」——只有配置后，Native 扫码支付成功才会收到回调。

JSAPI / 小程序支付：商户平台「产品中心 → 开发配置 → 支付通知 URL」——只有配置后，公众号内 H5 和微信小程序的支付才会收到回调。

两个配置项互不影响，按需配置即可。如果你只做 Native 支付，就只需要配本节的链接。

第三步 · 了解 pay-common 云函数

完全复用微信小程序支付集成指南所述源码结构与环境变量注入逻辑。Native 下单已在 pay-common 中实现，对应 _action: wxpay_order_native。

第四步 · 接入 PC 收银台

pay-common 部署完成后，PC 端的接入分四步：调用 pay-common 拿 code_url → 前端渲染二维码 → 轮询查单 → 跳转结果页。

4.1 支付相关路由

Native 与其他支付方式共享同一套 pay-common 路由，差异只在下单 _action：

`_action`	类别	说明
`wxpay_order_native`	下单	Native 扫码下单（本指南使用）
`wxpay_query_order_by_out_trade_no`	查询	按商户订单号查单（Native 必备，前端轮询使用）
`wxpay_query_order_by_transaction_id`	查询	按微信订单号查单
`wxpay_close_order`	关单	关闭订单（10 分钟未支付建议主动关闭）
`wxpay_refund`	退款	申请退款
`wxpay_refund_query`	退款	查询退款

与 JSAPI/小程序最大差别：Native 下单走 wxpay_order_native，返回 { code_url } 而非 { timeStamp, paySign, ... }。

所有路由通过 body 中的 _action 字段区分，除回调路由外均需携带 Authorization: Bearer {access_token}。

4.2 回调处理

Native 与 JSAPI / 小程序复用同一套回调处理逻辑，无需为支付方式区分代码。完整实现见微信小程序支付集成指南，本节只列出 4 个核心 handler。

Handler	触发场景	处理原则
`handlerUnified`	同步下单返回	尽早返回、幂等
`handlerUnifiedTrigger`	异步支付结果回调	金额校验、状态原子更新
`handlerRefund`	同步退款返回	尽早返回、幂等
`handlerRefundTrigger`	异步退款结果回调	金额校验、状态原子更新

💡 Native 与 JSAPI / 小程序回调结构 100% 一致——都是 event_type: TRANSACTION.SUCCESS，明文中拿到 out_trade_no / transaction_id / amount 等字段。集成中心已自动验签 + 解密，业务侧拿到的就是明文。

4.3 完整调用示例

适合 PC 网页场景。下面是从下单到展示二维码、轮询查单的端到端示例。

以下约束与 pay-common 源码行为一致，详见 GitHub pay-common。

基础配置

前端调用 pay-common 前需准备的两个变量：

变量	含义
`ENV_ID`	云开发环境 ID
`FN_NAME`	集成创建后自动生成的 HTTP 云函数名（形如 `<集成标识>-<随机串>`）

下单请求体

必填 3 个字段（其他由 pay-common 自动注入）：

字段	类型	规则
`description`	string	商品描述，≤ 127 字符
`amount.total`	number	正整数，单位分（如 0.2 元 → `20`）
`out_trade_no`	string	6–32 位字母/数字/下划线/连字符，全局唯一

Native 支付无需传递的字段（pay-common 已自动处理）：

字段	说明
~~`payer.openid`~~	仅 JSAPI/小程序需要
~~`appid`~~	pay-common 自动注入集成配置的 AppID
~~`notify_url`~~	pay-common 自动使用集成中心的回调地址

鉴权

⚠️ accessToken 必须来自「认证登录」

匿名登录（signInAnonymously）拿到的 token 无权调用云函数，云 API 网关会直接返回 401。

可选登录方式：邮箱、手机号、微信公众号/开放平台、CloudBase 自定义登录等。完整代码与说明请参考 CloudBase Web SDK · 认证登录。

返回结构（三层嵌套）

所有 pay-common 路由都遵循同一份返回结构：

{
  code,           // ① 云 API 网关外层（业务码）
  msg,
  data: {
    status,       // ② wechatpay-node-v3 中间层（HTTP 状态）
    data: { ... } // ③ 微信支付原始业务数据
  }
}

外层 code === 0 即视为成功，业务数据从 data.data 取。下面示例的 unwrap() 函数封装了这层逻辑。

UI 实现要点

二维码内容直接用 code_url 原文（形如 weixin://wxpay/bizpayurl?pr=...），不要做 URL 编码
轮询频率：建议 2–3 秒一次，10 分钟未支付则前端主动调 wxpay_close_order 关闭订单
支付状态以服务端回调为准，前端轮询到 SUCCESS 仅用于跳转 UI

<!-- pc-cashier.html -->
<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>扫码支付</title>
  <style>
    .cashier { text-align: center; padding: 40px; }
    #qrcode  { margin: 24px auto; }
    .status  { color: #888; font-size: 14px; margin-top: 12px; }
  </style>
</head>
<body>
  <div class="cashier">
    <h2>请使用微信扫码支付</h2>
    <h3>金额：<span id="amount">¥ 0.20</span></h3>
    <div id="qrcode"></div>
    <div class="status" id="status">等待扫码……</div>
  </div>

  <script src="https://cdn.bootcdn.net/ajax/libs/qrcodejs/1.0.0/qrcode.min.js"></script>
  <script src="https://static.cloudbase.net/cloudbase-js-sdk/latest/cloudbase.full.js"></script>
  <script>
    const ENV_ID  = 'your-env-id'
    const FN_NAME = 'pay-common'             // 集成创建后生成的实际函数名
    const POLL_INTERVAL = 2000               // 查单间隔 2s
    const POLL_TIMEOUT  = 600000             // 10 分钟后停止轮询并关单

    const app = cloudbase.init({ env: ENV_ID })
    const auth = app.auth({ persistence: 'local' })

    // Web 端拿 accessToken
    // ⚠️ 匿名登录（signInAnonymously）拿到的 accessToken 无法通过云 API 网关调用云函数，
    //    云函数侧会返回 401。必须使用「认证登录」获取 accessToken。
    // 可选登录方式（邮箱、手机号、微信公众号/开放平台、CloudBase 自定义登录等）与完整代码，
    // 参见 CloudBase Web SDK 文档：
    // https://docs.cloudbase.net/api-reference/webv2/authentication#%E8%AE%A4%E8%AF%81%E7%99%BB%E5%BD%95
    async function getAccessToken() {
      // 示例：使用邮箱 + 验证码登录，获取可访问云函数的 accessToken
      // const loginState = await auth.signIn({
      //   username: 'user@example.com',
      //   verification_code: '...',
      //   verification_token: '...',
      // })
      // return loginState.credential.accessToken
      throw new Error('请参考 CloudBase Web SDK 文档实现认证登录后返回 accessToken')
    }

    // 统一封装：调用 pay-common 的任意路由
    async function callPayCommon(token, payload) {
      const res = await fetch(
        `https://${ENV_ID}.api.tcloudbasegateway.com/v1/functions/${FN_NAME}?webfn=true`,
        {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
            Authorization: `Bearer ${token}`,
          },
          body: JSON.stringify(payload),
        }
      )
      return res.json()
    }

    // 从 pay-common 返回结构中解包业务数据
    // pay-common 返回: { code: 0, msg: 'success', data: { status: 200, data: <业务> } }
    function unwrap(body) {
      if (!body || body.code !== 0) return null
      const inner = body.data
      return inner && inner.data ? inner.data : inner
    }

    ;(async () => {
      const token = await getAccessToken()
      const out_trade_no = 'ORDER_' + Date.now()

      // 1. Native 下单（无需 openid / appid / notify_url）
      const orderRes = await callPayCommon(token, {
        _action: 'wxpay_order_native',
        description: '测试商品',
        out_trade_no,
        amount: { total: 20, currency: 'CNY' },   // 0.2 元
      })
      const order = unwrap(orderRes)
      if (!order || !order.code_url) {
        document.getElementById('status').textContent = '下单失败：' + (orderRes.msg || '')
        return
      }
      // order.code_url 形如 'weixin://wxpay/bizpayurl?pr=...'

      // 2. 渲染二维码（code_url 原样作为二维码内容，不要 URL 编码）
      QRCode.toCanvas(document.getElementById('qrcode'), order.code_url, { width: 240 })

      // 3. 轮询查单
      const startedAt = Date.now()
      const timer = setInterval(async () => {
        // 超时关单
        if (Date.now() - startedAt > POLL_TIMEOUT) {
          clearInterval(timer)
          await callPayCommon(token, {
            _action: 'wxpay_close_order',
            out_trade_no,
          })
          document.getElementById('status').textContent = '订单已超时关闭'
          return
        }

        const queryRes = await callPayCommon(token, {
          _action: 'wxpay_query_order_by_out_trade_no',
          out_trade_no,
        })
        const detail = unwrap(queryRes)
        const state  = detail && detail.trade_state

        if (state === 'SUCCESS') {
          clearInterval(timer)
          document.getElementById('status').textContent = '支付成功，正在跳转……'
          location.href = `/order/result?out_trade_no=${out_trade_no}`
        } else if (state === 'CLOSED' || state === 'PAYERROR' || state === 'REVOKED') {
          clearInterval(timer)
          document.getElementById('status').textContent = '订单已 ' + state
        } else if (state === 'USERPAYING') {
          document.getElementById('status').textContent = '用户支付中……'
        }
        // NOTPAY：继续等待
      }, POLL_INTERVAL)
    })()
  </script>
</body>
</html>

实现要点：

code_url 直接用作二维码内容，不要 URL 编码、不要嵌入 HTTPS 链接，扫码后微信会自行跳转支付页。
三层解包：示例中的 unwrap() 函数封装了固定的三层结构——云 API 网关的 { code, msg, data } → wechatpay-node-v3 的 { status, data } → 微信原始业务数据。所有 pay-common 路由的返回都遵循这个结构。
轮询查单是 Native 支付的常规感知方式，建议 2–3 秒一次，10 分钟未支付则前端主动调 wxpay_close_order 关闭订单。
更优体验：服务端在 handlerUnifiedTrigger 收到回调后，通过 WebSocket / SSE 主动推送结果到该用户对应的 PC 会话，可省去轮询；本指南为简化未演示。
最终发货等业务副作用以服务端回调为准，前端轮询到 SUCCESS 仅用于跳转 UI。

多 AppID 场景

pay-common 支持通过 useServiceAccount 参数动态切换 appid（需在云函数环境变量中额外配置 service_app_id）。典型场景：集成里默认是小程序 AppID，但某些 Native 场景希望用服务号 AppID 下单：

// 下单时带上 useServiceAccount: true
await callPayCommon(token, {
  _action: 'wxpay_order_native',
  useServiceAccount: true,         // 用 service_app_id 下单
  description: '测试商品',
  out_trade_no,
  amount: { total: 20, currency: 'CNY' },
})

若未配置 service_app_id 环境变量，pay-common 会直接报错返回 useServiceAccount=true 但未配置 service_app_id 环境变量。

4.4 真机测试

Native 支付测试比 JSAPI/小程序简单：

用任意桌面浏览器（Chrome/Safari）打开 pc-cashier.html，看到二维码即下单成功。
手机微信「扫一扫」二维码，弹出支付页，输入密码完成支付。
PC 端应在 2–4 秒内显示"支付成功"并跳转结果页（取决于轮询间隔）。
同步检查云函数日志：tcb fn log <FN_NAME> 中应能看到 handlerUnifiedTrigger - 支付结果: ... SUCCESS 表示回调链路也成功。

测试金额建议同小程序：使用 0.1–1 元，避免 0.01 元触发风控；同一账号单日扫码支付次数也有限制。

常见问题 FAQ

Q1：返回的 code_url 形如 weixin:// 开头，能直接放到 img src 吗

不能。weixin:// 是私有 schema，不是 HTTPS URL。必须用前端 QR Code 库（qrcode.js / canvas）把字符串绘制成二维码图片。

Q2：扫码后微信提示「该链接无法访问」

通常是把 code_url 做了 URL 编码或包了一层跳转链接。code_url 必须原样作为二维码内容，连去除前后空白都不要做。

Q3：扫码后微信提示「支付链接已失效」

code_url 默认 2 小时后过期；如果用户长时间没扫，需要重新下单生成新链接。前端应同时提供"刷新二维码"按钮。

Q4：手机扫码后没反应，没弹支付页

可能原因：

商户号未开通 Native 支付权限（商户平台「产品中心」→ Native 支付 → 申请开通）
appId 与商户号未完成关联
二维码生成时使用了错误编码（比如 base64）导致内容损坏

Q5：PC 网页轮询查单报 401 / token 过期

CloudBase Web SDK 拿到的 accessToken 默认 2 小时过期。简单做法：每次调用前重新拿 token；更优做法：在 auth.onLoginStateChanged 中监听并刷新。

Q6：能否不轮询，只靠服务端回调通知前端

可以，常见方案：

WebSocket / SSE：业务后端在 handlerUnifiedTrigger 收到回调后，通过 ws/sse 推送给该 out_trade_no 对应的 PC 会话。
CloudBase 实时数据库：服务端把订单状态写到云数据库，PC 前端用实时 SDK db.collection('orders').doc(id).watch() 监听变更。

两种都能省去前端轮询，体验最好。轮询作为兜底依然建议保留。

Q7：Native 支付能否用同一个集成同时支持小程序支付

能。pay-common 模板中 Native 与 JSAPI/小程序下单走同一个 SDK，只是路由（_action）不同。注意：

集成中心填的 appId 决定下单时的 appid。如果该 AppID 在商户平台已开通 Native 与 JSAPI 两种支付，pay-common 就能同时支持。
如果 Native 想用一个 AppID（如开放平台移动应用 AppID）、小程序支付想用另一个 AppID，需要两个独立集成或改 pay-common 代码动态切换。

Q8：Native 支付的回调与小程序支付有什么差别

没有差别。微信支付 V3 的回调对所有支付方式（JSAPI / Native / H5 / APP）都是同一份结构 TRANSACTION.SUCCESS，验签机制、解密方式完全一致。集成中心已代做验签和解密，pay-common 的 handlerUnifiedTrigger 拿到的明文格式与下单方式无关。

附录 · 与其他支付方式的差异速查

维度	小程序	JSAPI 网页	Native（本指南）
`_action`	`wxpay_order`	`wxpay_order`	`wxpay_order_native`
下单接口	`/v3/pay/transactions/jsapi`	`/v3/pay/transactions/jsapi`	`/v3/pay/transactions/native`
是否需 openid	是	是	否
下单返回	`prepay_id` + 5 字段	`prepay_id` + 5 字段	`code_url`
调起方式	`wx.requestPayment`	`WeixinJSBridge.invoke`	二维码 + 用户扫码
支付完成感知	前端 `success` 回调	JSBridge `ok` 回调	轮询查单 / 服务端推送
运行环境	微信小程序	微信内置浏览器	任意浏览器/客户端
回调结构	`TRANSACTION.SUCCESS`	`TRANSACTION.SUCCESS`	`TRANSACTION.SUCCESS`（一致）

延伸阅读

主题	链接
Native 下单	https://pay.weixin.qq.com/doc/v3/merchant/4012791900
查询订单	https://pay.weixin.qq.com/doc/v3/merchant/4012791898
关闭订单	https://pay.weixin.qq.com/doc/v3/merchant/4012791899
支付回调协议	https://pay.weixin.qq.com/docs/merchant/apis/mini-program-payment/payment-notice.html
CloudBase Auth · Web SDK	https://docs.cloudbase.net/api-reference/webv2/authentication

架构总览​

前置条件​

第一步 · 准备商户凭证​

第二步 · 在 CloudBase 创建集成​

在商户平台配置 Native 支付回调链接​

第三步 · 了解 pay-common 云函数​

第四步 · 接入 PC 收银台​

4.1 支付相关路由​

4.2 回调处理​

4.3 完整调用示例​

基础配置​

下单请求体​

鉴权​

返回结构（三层嵌套）​

UI 实现要点​

多 AppID 场景​

4.4 真机测试​

常见问题 FAQ​

Q1：返回的 code_url 形如 weixin:// 开头，能直接放到 img src 吗​

Q2：扫码后微信提示「该链接无法访问」​

Q3：扫码后微信提示「支付链接已失效」​

Q4：手机扫码后没反应，没弹支付页​

Q5：PC 网页轮询查单报 401 / token 过期​

Q6：能否不轮询，只靠服务端回调通知前端​

Q7：Native 支付能否用同一个集成同时支持小程序支付​

Q8：Native 支付的回调与小程序支付有什么差别​

附录 · 与其他支付方式的差异速查​

延伸阅读​