微信支付：Native 扫码支付（PC 网页扫码）

本文介绍普通商户如何在 tio-boot 后端接入微信支付 API V3 的 Native 下单接口，把返回的 code_url 渲染成二维码， 让用户在电脑浏览器上扫码付款，并通过通知与查单确认收款结果。适用于网页端充值、购买虚拟内容等场景。

网页扫码与小程序支付用的是同一套商户配置，区别在下单接口与前端展示方式：小程序用 JSAPI 下单后 wx.requestPayment， 网页扫码用 Native 下单后展示二维码。小程序内的支付流程见微信小程序支付：普通支付。

会员、数字内容、解锁功能等虚拟商品应按平台要求接入虚拟支付，不能因为改成"扫码"就绕开类目与商品合规要求。 申请前应如实说明商品和交付方式。

1. 支付流程

浏览器                         tio-boot 后端                    微信平台
  │ 选金额、点下一步               │                              │
  ├─────────────────────────────>│ 后端定价，先写支付订单        │
  │                               │ Native 下单                  │
  │                               ├─────────────────────────────>│
  │ 返回订单号 + code_url          │<──────── code_url ───────────┤
  │<──────────────────────────────┤                              │
  │ 展示二维码并轮询订单状态        │                              │
  ├──────────────────────────────>│ 主动查单（本地仍未支付时）     │
  │                               ├─────────────────────────────>│
  │                               │<────── 支付结果通知 ──────────┤
  │                               │ 验签、解密、核对金额           │
  │                               │ 事务内改状态并发放权益          │
  │ 轮询得到已支付                 │                              │
  │<──────────────────────────────┤                              │

下单成功只表示拿到了二维码，最终是否付款要看验签通过的通知或主动查单结果，不能根据前端回调直接发货。 用户扫码付款后，微信会把结果推给 notify_url；网络抖动、服务重启都可能让通知延迟送达，所以要同时支持主动查单。

2. 开通与准备

2.1 运营侧

1. 申请微信支付商户号：营业执照、法人或经营者资料、结算账户、超级管理员，审核通过后完成签约；
2. 在商户平台「产品中心」确认已开通 Native 支付（扫码支付）；
3. 完成商户号与 AppID 的绑定（商户平台「产品中心 → AppID 账号管理」提交，公众号/小程序/网站应用侧确认）；
4. 准备商品说明、退款规则、客服联系方式等上线资料，按平台要求完成备案与经营类目审核。

Native 扫码支付不需要配置「JSAPI 支付授权目录」，也不需要网页授权域名；需要网页授权域名的是公众号内的 JSAPI 支付。

2.2 参数用途

登录商户平台「账户中心 → API 安全」准备下列参数：

参数	用途	注意事项
AppID	标识本次支付所属应用	必须与商户号绑定，且与下单时使用的一致
商户号	标识收款商户	与上面 AppID 绑定
商户私钥	签名下单与查单请求	常见文件名 apiclient_key.pem，仅存后端
商户证书序列号	标识商户签名使用的证书	不能填微信支付公钥 ID
APIv3 密钥	解密通知中的 resource	商户平台设置的 32 位密钥
微信支付公钥及公钥 ID	验证微信返回内容与通知签名	公钥 ID 通常以 PUB_KEY_ID_ 开头
支付回调地址	接收异步通知	公网可访问的 HTTPS 地址

本文使用微信支付公钥模式。仍使用平台证书模式的商户，应按官方 SDK 的平台证书配置接入并维护证书轮换， 不能把平台证书序列号填成公钥 ID。两种验签配置的差异参见官方 Java SDK。

2.3 环境变量

以下均为占位值，不可直接用于请求。文件路径可以改为服务器绝对路径。

WECHAT_PAY_APP_ID=YOUR_APP_ID
WECHAT_PAY_MCH_ID=YOUR_MERCHANT_ID
WECHAT_PAY_API_V3_KEY=YOUR_32_CHARACTER_API_V3_KEY
WECHAT_PAY_MERCHANT_SERIAL=YOUR_MERCHANT_CERT_SERIAL
WECHAT_PAY_PRIVATE_KEY_PATH=certs/wechatpay/apiclient_key.pem
WECHAT_PAY_PUBLIC_KEY_PATH=certs/wechatpay/wechatpay_pub_key.pem
WECHAT_PAY_PUBLIC_KEY_ID=PUB_KEY_ID_YOUR_PUBLIC_KEY_ID
WECHAT_PAY_NOTIFY_URL=https://api.example.com/api/payments/wechat/notify

下文 Java 示例通过 System.getenv 读取操作系统环境变量。放在项目配置文件里时应改用项目配置加载器读取， Java 不会自动读取 .env 文件。私钥、APIv3 密钥不提交仓库、不返回前端、不写日志。

2.4 域名与网络

• 回调地址允许微信服务器直接访问，不能要求业务登录或重定向到登录页；
• JSAPI 与 Native 都按每次下单请求里的 notify_url 回调，不需要在商户平台另填该接口地址；
• 网关与反向代理必须保留通知签名请求头（wechatpay-serial、wechatpay-nonce、wechatpay-signature、wechatpay-timestamp）与原始请求体；
• 服务器要能访问 https://api.mch.weixin.qq.com，并开启时间同步（NTP），时间偏差过大会导致签名与验签失败。

3. Java 后端客户端

3.1 添加官方 SDK

在依赖管理中锁定团队验证过的 SDK 版本后加入依赖，版本以官方文档为准：

<dependency>
  <groupId>com.github.wechatpay-apiv3</groupId>
  <artifactId>wechatpay-java</artifactId>
  <version>${wechatpay-java.version}</version>
</dependency>

SDK 负责请求签名、应答验签与通知解密，业务代码负责订单、金额与状态校验。

3.2 下单、查单、关单与通知解析

新建 example.payment.WechatPayClient，应用启动时创建并复用。Native 下单调用 POST https://api.mch.weixin.qq.com/v3/pay/transactions/native，请求体字段与 JSAPI 基本一致， 只是不再需要 payer.openid，返回值为二维码内容 code_url：

{
  "appid": "YOUR_APP_ID",
  "mchid": "YOUR_MERCHANT_ID",
  "description": "示例虚拟商品",
  "out_trade_no": "DEMO_ORDER_001",
  "notify_url": "https://api.example.com/api/payments/wechat/notify",
  "time_expire": "2026-01-01T12:30:00+08:00",
  "amount": { "total": 100, "currency": "CNY" }
}

package example.payment;

import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import com.wechat.pay.java.core.RSAPublicKeyConfig;
import com.wechat.pay.java.core.notification.NotificationParser;
import com.wechat.pay.java.core.notification.RequestParam;
import com.wechat.pay.java.service.payments.model.Transaction;
import com.wechat.pay.java.service.payments.nativepay.NativePayService;
import com.wechat.pay.java.service.payments.nativepay.model.Amount;
import com.wechat.pay.java.service.payments.nativepay.model.CloseOrderRequest;
import com.wechat.pay.java.service.payments.nativepay.model.PrepayRequest;
import com.wechat.pay.java.service.payments.nativepay.model.QueryOrderByOutTradeNoRequest;

public final class WechatPayClient {
  private static final DateTimeFormatter RFC3339 = DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ssXXX");

  private final String appId = required("WECHAT_PAY_APP_ID");
  private final String mchId = required("WECHAT_PAY_MCH_ID");
  private final String notifyUrl = required("WECHAT_PAY_NOTIFY_URL");
  private final NativePayService service;
  private final NotificationParser parser;

  public WechatPayClient() {
    RSAPublicKeyConfig config = new RSAPublicKeyConfig.Builder()
        .merchantId(mchId)
        .privateKeyFromPath(required("WECHAT_PAY_PRIVATE_KEY_PATH"))
        .merchantSerialNumber(required("WECHAT_PAY_MERCHANT_SERIAL"))
        .publicKeyFromPath(required("WECHAT_PAY_PUBLIC_KEY_PATH"))
        .publicKeyId(required("WECHAT_PAY_PUBLIC_KEY_ID"))
        .apiV3Key(required("WECHAT_PAY_API_V3_KEY"))
        .build();
    service = new NativePayService.Builder().config(config).build();
    parser = new NotificationParser(config);
  }

  /** 下单，返回二维码内容 */
  public String prepay(String outTradeNo, String description, int totalFen, LocalDateTime expireTime) {
    if (totalFen <= 0) {
      throw new IllegalArgumentException("订单金额超出支持范围");
    }
    Amount amount = new Amount();
    amount.setTotal(totalFen);
    amount.setCurrency("CNY");

    PrepayRequest request = new PrepayRequest();
    request.setAppid(appId);
    request.setMchid(mchId);
    request.setDescription(description);
    request.setOutTradeNo(outTradeNo);
    request.setNotifyUrl(notifyUrl);
    if (expireTime != null) {
      // 二维码有效期由 time_expire 决定，格式为 RFC3339，例如 2026-01-01T12:30:00+08:00
      request.setTimeExpire(RFC3339.format(expireTime.atZone(java.time.ZoneId.of("Asia/Shanghai"))));
    }
    request.setAmount(amount);
    return service.prepay(request).getCodeUrl();
  }

  public Transaction query(String outTradeNo) {
    QueryOrderByOutTradeNoRequest request = new QueryOrderByOutTradeNoRequest();
    request.setMchid(mchId);
    request.setOutTradeNo(outTradeNo);
    return service.queryOrderByOutTradeNo(request);
  }

  /** 关闭订单，避免留下仍然可以付款的二维码 */
  public void close(String outTradeNo) {
    CloseOrderRequest request = new CloseOrderRequest();
    request.setMchid(mchId);
    request.setOutTradeNo(outTradeNo);
    service.closeOrder(request);
  }

  public Transaction parseNotification(String serial, String nonce,
      String signature, String timestamp, String rawBody) {
    RequestParam request = new RequestParam.Builder()
        .serialNumber(serial).nonce(nonce).signature(signature)
        .timestamp(timestamp).body(rawBody).build();
    return parser.parse(request, Transaction.class);
  }

  /** expected 参数必须来自本地保存的支付订单 */
  public boolean matches(Transaction tx, String outTradeNo, int expectedFen) {
    return tx != null
        && appId.equals(tx.getAppid()) && mchId.equals(tx.getMchid())
        && outTradeNo.equals(tx.getOutTradeNo())
        && tx.getTransactionId() != null && !tx.getTransactionId().isBlank()
        && tx.getAmount() != null && tx.getAmount().getTotal() != null
        && tx.getAmount().getTotal() == expectedFen
        && "CNY".equals(tx.getAmount().getCurrency());
  }

  private static String required(String name) {
    String value = System.getenv(name);
    if (value == null || value.isBlank()) {
      throw new IllegalStateException("缺少环境变量：" + name);
    }
    return value;
  }
}

金额单位为分，例如 1 元对应 100 分。扫码支付的付款人 OpenID 由微信在支付成功后返回，下单时不需要传， 因此不需要 code2Session，也就不需要小程序 AppSecret。核对金额使用 amount.total，不要拿优惠后的 payer_total 与订单原金额比较。

4. 展示二维码

后端把 code_url（形如 weixin://wxpay/bizpayurl?pr=xxxx）交给前端渲染成二维码即可，两条常见做法：

做法	说明
前端用二维码库渲染	接口只返回 code_url，前端生成二维码图片，样式与尺寸由前端控制
后端生成图片/data URL	后端用二维码库把 code_url 编成 SVG 或 PNG 返回，前端直接放进 <img src>，手机端还能把 code_url 当链接唤起微信

二维码内容必须原样使用接口返回的 code_url，不要自己拼支付链接。页面同时展示金额、剩余有效时间， 并在用户付款后轮询订单状态；手机浏览器可以额外提供"在微信中打开"按钮，直接跳转 code_url。

5. 业务订单与回调 Handler

5.1 订单数据

下单前先落库，回调到达时才有一致的核验依据。至少保存：

字段	用途
order_id、user_id	业务订单及所属用户
out_trade_no	商户订单号，唯一且不超过 32 个字符
amount_fen、currency	锁定的应付金额和币种
appid、mchid	本次支付所属应用与商户
push_count	权益发放次数或状态机标记，保证只发一次
status	至少区分 PENDING、PAID、CLOSED
transaction_id、paid_at	微信支付订单号和支付成功时间

给商户订单号与微信交易单号设置唯一约束（交易单号允许为空，用部分唯一索引）。同一商户订单号不能在金额变化后继续使用。 用户重复点击时复用未过期、金额相同的待支付订单，避免同时存在多个可付款二维码。

5.2 回调 Handler

package example.payment;

import java.util.Map;
import com.wechat.pay.java.service.payments.model.Transaction;
import nexus.io.tio.boot.http.TioRequestContext;
import nexus.io.tio.http.common.HttpRequest;
import nexus.io.tio.http.common.HttpResponse;

public final class WechatNotifyHandler {
  public interface PaidOrderService {
    // 正常返回表示核验通过且事务已提交；重复通知也必须核验
    void confirm(Transaction transaction);
  }

  private final WechatPayClient client;
  private final PaidOrderService orders;

  public WechatNotifyHandler(WechatPayClient client, PaidOrderService orders) {
    this.client = client;
    this.orders = orders;
  }

  public HttpResponse notify(HttpRequest request) {
    try {
      Transaction transaction = client.parseNotification(
          request.getHeader("wechatpay-serial"),
          request.getHeader("wechatpay-nonce"),
          request.getHeader("wechatpay-signature"),
          request.getHeader("wechatpay-timestamp"),
          request.getBodyString());
      orders.confirm(transaction);
      return TioRequestContext.getResponse().setStatus(200)
          .setJson(Map.of("code", "SUCCESS", "message", "成功"));
    } catch (RuntimeException e) {
      // 生产环境记录脱敏异常与请求编号，不记录密钥或通知全文
      return TioRequestContext.getResponse().setStatus(500)
          .setJson(Map.of("code", "FAIL", "message", "通知处理失败"));
    }
  }
}

在路由配置中注册，paidOrderService 是项目实现的订单服务：

WechatPayClient payClient = new WechatPayClient();
WechatNotifyHandler handler = new WechatNotifyHandler(payClient, paidOrderService);
router.add(HttpMethod.POST, "/api/payments/wechat/notify", handler::notify);

只对通知路径放行业务登录拦截（微信服务器没有业务登录态，身份由签名保证），下单与查单仍然要求登录。 验签必须使用未经修改的 getBodyString()，不能 JSON 解析后再序列化。

通知里除交易信息外还有事件类型：外层 event_type 与解密后的 trade_state 是两个字段， 只有 event_type 为 TRANSACTION.SUCCESS 且 trade_state 为 SUCCESS 才按支付成功处理； 退款等其他事件应确认收到但不改动订单。

5.3 实现 confirm：核验与幂等

开始事务
  根据通知的 out_trade_no 查询并锁定本地支付记录
  记录不存在：失败、告警，不应答成功
  核对 appid、mchid、out_trade_no、transaction_id 与 amount.total、currency
  若已支付：核对 transaction_id 相同，按重复通知处理
  若待支付：
    条件更新订单为 PAID 并写入 transaction_id、paid_at（只有受影响行数大于 0 才继续）
    发放权益（加积分、开通会员、写发货任务等）
  若已关闭却收到成功通知：进入异常核对流程，不静默覆盖
提交事务后返回

权益发放与状态迁移必须在同一事务里，重复通知不能重复发放。不用行锁时应使用条件更新并检查受影响行数， 保证只有一次状态迁移成功。回调需要在 5 秒内应答，耗时任务交给异步处理。

6. 主动查单与关单

• 用户查询订单状态时，先验证订单归属；本地仍是待支付时调用查单接口，结果为 SUCCESS 就复用同一套核验与发放逻辑；
• 其他交易状态按语义区分：NOTPAY、USERPAYING 保持待支付，CLOSED、REVOKED、PAYERROR 关闭本地订单；
• 二维码过期或下单失败时，按微信关单流程关闭微信侧订单（closeOrder），避免留下仍可付款的二维码；
• 限制主动查单频率，避免前端轮询无限放大成微信请求；
• 服务端定时扫描长时间待支付的订单并查单，关闭超时订单前先按微信关单流程处理付款与关单的并发；
• 定期对账，覆盖通知丢失与异常中断。

7. 联调验收

1. 确认下单 AppID、商户绑定 AppID、mchid 三者一致；
2. 检查私钥可读、公钥 ID 与公钥匹配、APIv3 密钥正确，服务器时间同步；
3. 创建后端定价的小额订单，确认支付记录在预下单前已落库；
4. 用真实微信扫码付款，核对页面上的商品金额与收银台一致；
5. 付款后确认收到通知、订单变为 PAID、transaction_id 已保存、权益只发放一次；
6. 受控重放已处理的通知，确认不重复发放；篡改内容应验签失败；
7. 把回调地址临时改错，确认用户查单时能通过主动查单补全状态；
8. 测试取消支付、二维码过期后重新获取、跨用户查询他人订单，确保不会误记成功或越权。

代码编译通过不代表商户已开通，不能替代真机付款、通知与退款测试。

8. 常见问题

现象	排查方向
下单报 AppID 与商户号不匹配	商户号尚未与下单使用的 AppID 绑定，或两者不是同一主体
二维码扫不出来	用返回的 code_url 单独生成二维码验证；确认二维码内容没有被截断或二次编码
扫码后提示订单已过期	time_expire 与本地订单有效期不一致，或二维码展示时间过长，应支持重新获取
重复点击生成多个可付款订单	下单前先查未过期的同金额待支付订单并复用，或加唯一约束防止并发创建
通知验签失败	核对公钥 ID、公钥、签名头与原始请求体；反向代理不能改写 body
通知解密失败	APIv3 密钥不对，它与商户私钥、小程序 AppSecret 是三样不同的东西
付了款但订单未更新	查通知访问日志与事务异常，用主动查单补状态，不要让用户立即再次付款
服务重启后二维码失效消息	本地订单与微信订单状态不一致时以查单结果为准，必要时关单后重新下单

日志记录失败阶段、脱敏订单标识、微信错误码、HTTP 状态与响应头 Request-ID。用户端可展示业务订单号与业务请求编号， 不能展示私钥、APIv3 密钥、OpenID 与通知全文。微信支付常见问题可作为平台侧排查入口。