用WorkBuddy制作流程图解，微信小程序虚拟支付对接全流程实战

{
  "offerId": "你的 OfferID",
  "buyQuantity": 1,
  "env": 0,
  "currencyType": "CNY",
  "productId": "vip_monthly",
  "goodsPrice": 2500,
  "outTradeNo": "ORD2026070612345",
  "attach": "{\"uid\":10086,\"pid\":\"vip\"}"
}

package com.example.vpay.util;
​
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
​
/**
 * 虚拟支付签名工具类
 */
public class VpSignUtil {
​
    private static final String HMAC_SHA256 = "HmacSHA256";
​
    /**
     * 计算支付签名 paySig
     *
     * @param uri         固定值 "requestVirtualPayment"
     * @param signDataStr signData 的 JSON 字符串
     * @param appKey      对应环境的 AppKey（现网 / 沙箱）
     * @return HMAC-SHA256 十六进制签名
     */
    public static String calcPaySig(String uri, String signDataStr, String appKey) {
        // 拼接规则：uri + "&" + signDataStr
        String signStr = uri + "&" + signDataStr;
        return hmacSHA256(appKey, signStr);
    }
​
    /**
     * 计算用户态签名 signature
     *
     * @param signDataStr signData 的 JSON 字符串
     * @param sessionKey  用户 session_key
     * @return HMAC-SHA256 十六进制签名
     */
    public static String calcSignature(String signDataStr, String sessionKey) {
        return hmacSHA256(sessionKey, signDataStr);
    }
​
    /**
     * HMAC-SHA256 计算
     *
     * @param key     密钥
     * @param message 待签名内容
     * @return 十六进制字符串
     */
    private static String hmacSHA256(String key, String message) {
        try {
            Mac mac = Mac.getInstance(HMAC_SHA256);
            SecretKeySpec secretKeySpec = new SecretKeySpec(
                    key.getBytes(StandardCharsets.UTF_8), HMAC_SHA256);
            mac.init(secretKeySpec);
            byte[] hash = mac.doFinal(message.getBytes(StandardCharsets.UTF_8));
            return bytesToHex(hash);
        } catch (Exception e) {
            throw new RuntimeException("HMAC-SHA256 计算失败", e);
        }
    }
​
    /**
     * 字节数组转十六进制字符串
     */
    private static String bytesToHex(byte[] bytes) {
        StringBuilder sb = new StringBuilder();
        for (byte b : bytes) {
            sb.append(String.format("%02x", b));
        }
        return sb.toString();
    }
}

package com.example.vpay.config;
​
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Configuration;
​
/**
 * 虚拟支付配置
 * 对应 application.yml 中的 vpay.* 配置项
 */
@Configuration
public class VpConfig {
​
    @Value("${vpay.app-id}")
    private String appId;
​
    @Value("${vpay.offer-id}")
    private String offerId;
​
    @Value("${vpay.app-key}")           // 现网密钥
    private String appKey;
​
    @Value("${vpay.sandbox-key}")       // 沙箱密钥
    private String sandboxKey;
​
    @Value("${vpay.sandbox:false}")     // 是否沙箱环境
    private boolean sandbox;
​
    public String getAppId() { return appId; }
    public String getOfferId() { return offerId; }
​
    /** 根据环境返回对应的 AppKey */
    public String getCurrentAppKey() {
        return sandbox ? sandboxKey : appKey;
    }
​
    /** env 参数：0 = 现网，1 = 沙箱 */
    public int getEnv() {
        return sandbox ? 1 : 0;
    }
}

vpay:
  app-id: wx_your_appid
  offer-id: "1234567890"
  app-key: ${VP_APP_KEY}          # 从环境变量读取
  sandbox-key: ${VP_SANDBOX_KEY}  # 从环境变量读取
  sandbox: false                   # 上线时改为 false

package com.example.vpay.controller;
​
import com.example.vpay.config.VpConfig;
import com.example.vpay.entity.Product;
import com.example.vpay.entity.Order;
import com.example.vpay.service.ProductService;
import com.example.vpay.service.OrderService;
import com.example.vpay.service.UserService;
import com.example.vpay.util.VpSignUtil;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
​
import java.util.*;
​
@RestController
@RequestMapping("/api/vp")
public class VpPaymentController {
​
    @Autowired
    private VpConfig vpConfig;
​
    @Autowired
    private ProductService productService;
​
    @Autowired
    private OrderService orderService;
​
    @Autowired
    private UserService userService;
​
    @Autowired
    private ObjectMapper objectMapper;  // Jackson JSON 序列化
​
    /**
     * 构建支付参数接口
     * POST /api/vp/create
     *
     * 请求体：{ "productId": "vip_monthly", "uid": 10086 }
     * 响应体：{ "code": 0, "data": { "mode", "signData", "paySig", "signature" } }
     */
    @PostMapping("/create")
    public Map<String, Object> createPayment(@RequestBody Map<String, Object> body) {
        String productId = (String) body.get("productId");
        Long uid = Long.valueOf(body.get("uid").toString());
​
        Map<String, Object> resp = new HashMap<>();
​
        // 1. 查商品信息（你的业务逻辑）
        Product product = productService.getProduct(productId);
        if (product == null) {
            resp.put("code", -1);
            resp.put("msg", "商品不存在");
            return resp;
        }
​
        // 2. 生成订单号（8-32 位，字母数字 + _-*@）
        String outTradeNo = "ORD" + System.currentTimeMillis()
                + new Random().nextInt(10000);
​
        // 3. 构建 signData（用 LinkedHashMap 保证字段顺序）
        Map<String, Object> signData = new LinkedHashMap<>();
        signData.put("offerId", vpConfig.getOfferId());
        signData.put("buyQuantity", 1);
        signData.put("env", vpConfig.getEnv());         // 0=现网, 1=沙箱
        signData.put("currencyType", "CNY");
        signData.put("productId", product.getCode());
        signData.put("goodsPrice", product.getPrice()); // 单位：分
        signData.put("outTradeNo", outTradeNo);
​
        // attach 是透传数据，回调时原样返回
        Map<String, Object> attachData = new HashMap<>();
        attachData.put("uid", uid);
        attachData.put("productId", productId);
        signData.put("attach", objectMapper.writeValueAsString(attachData));
​
        // 4. 序列化为字符串（关键步骤！）
        //    使用 Jackson 序列化，确保格式统一
        String signDataStr;
        try {
            signDataStr = objectMapper.writeValueAsString(signData);
        } catch (Exception e) {
            throw new RuntimeException("signData 序列化失败", e);
        }
​
        // 5. 获取用户 session_key
        String sessionKey = userService.getSessionKey(uid);
        if (sessionKey == null || sessionKey.isEmpty()) {
            resp.put("code", -2);
            resp.put("msg", "登录态已过期，请重新登录");
            return resp;
        }
​
        // 6. 计算双签名
        String appKey = vpConfig.getCurrentAppKey();
        String paySig = VpSignUtil.calcPaySig(
                "requestVirtualPayment", signDataStr, appKey);
        String signature = VpSignUtil.calcSignature(signDataStr, sessionKey);
​
        // 7. 创建本地订单
        Order order = new Order();
        order.setOutTradeNo(outTradeNo);
        order.setUid(uid);
        order.setProductId(productId);
        order.setAmount(product.getPrice());
        order.setStatus("pending");
        order.setCreatedAt(new Date());
        orderService.createOrder(order);
​
        // 8. 返回给客户端
        Map<String, Object> data = new HashMap<>();
        data.put("mode", "short_series_goods");
        data.put("signData", signDataStr);   // 必须是字符串！
        data.put("paySig", paySig);
        data.put("signature", signature);
​
        resp.put("code", 0);
        resp.put("data", data);
        return resp;
    }
}

package com.example.vpay.util;
​
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.*;
​
class VpSignUtilTest {
​
    @Test
    void testCalcPaySig() {
        String uri = "requestVirtualPayment";
        String signDataStr = "{\"offerId\":\"1234567890\",\"buyQuantity\":1}";
        String appKey = "test_app_key_123456";
​
        String paySig = VpSignUtil.calcPaySig(uri, signDataStr, appKey);
​
        // 签名应该是 64 位十六进制字符串
        assertNotNull(paySig);
        assertEquals(64, paySig.length());
        assertTrue(paySig.matches("[0-9a-f]{64}"));
    }
​
    @Test
    void testCalcSignature() {
        String signDataStr = "{\"offerId\":\"1234567890\",\"buyQuantity\":1}";
        String sessionKey = "test_session_key";
​
        String signature = VpSignUtil.calcSignature(signDataStr, sessionKey);
​
        assertNotNull(signature);
        assertEquals(64, signature.length());
    }
​
    @Test
    void testSameInputSameResult() {
        // 相同输入应产生相同签名
        String key = "same_key";
        String msg = "same_message";
​
        String sig1 = VpSignUtil.calcSignature(msg, key);
        String sig2 = VpSignUtil.calcSignature(msg, key);
​
        assertEquals(sig1, sig2);
    }
}

// 版本号比较工具函数
function compareVersion(v1, v2) {
  const parts1 = v1.split('.');
  const parts2 = v2.split('.');
  const len = Math.max(parts1.length, parts2.length);
  while (parts1.length < len) parts1.push('0');
  while (parts2.length < len) parts2.push('0');
  for (let i = 0; i < len; i++) {
    const n1 = parseInt(parts1[i], 10);
    const n2 = parseInt(parts2[i], 10);
    if (n1 > n2) return 1;
    if (n1 < n2) return -1;
  }
  return 0;
}
​
// 检查是否支持虚拟支付
function isVPSupported() {
  const { SDKVersion } = wx.getSystemInfoSync();
  return compareVersion(SDKVersion, '2.19.2') >= 0
    || wx.canIUse('requestVirtualPayment');
}

// pages/payment/payment.js
​
/**
 * 发起虚拟支付
 * @param {string} productId - 商品 ID
 */
async function handlePay(productId) {
  // 1. 检查版本支持
  if (!isVPSupported()) {
    wx.showModal({
      title: '提示',
      content: '当前微信版本过低，请更新到最新版本后再试',
      showCancel: false,
    });
    return;
  }
​
  wx.showLoading({ title: '准备中...' });
​
  try {
    // 2. 请求服务端获取支付参数
    const res = await request({
      url: '/api/vp/create',
      method: 'POST',
      data: { productId },
    });
​
    wx.hideLoading();
​
    if (res.code !== 0) {
      wx.showToast({ title: res.msg || '支付准备失败', icon: 'none' });
      return;
    }
​
    const { mode, signData, paySig, signature } = res.data;
​
    // 3. 调用虚拟支付 API
    wx.requestVirtualPayment({
      mode,           // 'short_series_goods' 道具直购
      signData,       // 字符串！不是对象！
      paySig,
      signature,
      success(res) {
        console.log('支付成功', res);
        wx.showToast({ title: '购买成功' });
        // 刷新用户权益状态
        refreshUserVip();
      },
      fail({ errMsg, errCode }) {
        console.error('支付失败', errMsg, errCode);
        if (errCode === -2) {
          // 用户取消，不用提示
          return;
        }
        const msg = ERROR_MAP[errCode] || errMsg || '支付失败';
        wx.showToast({ title: msg, icon: 'none' });
      },
    });
  } catch (err) {
    wx.hideLoading();
    wx.showToast({ title: '网络错误', icon: 'none' });
  }
}
​
// 常见错误码映射
const ERROR_MAP = {
  -15001: '参数错误',
  -15002: '订单号重复，请重试',
  -15003: '系统繁忙，请稍后重试',
  -15005: '用户签名错误，请重新登录',
  -15006: '支付签名错误',
  -15007: '登录态已过期，请重新登录',
  -15010: '商品未发布，请联系客服',
  -15013: '商品价格异常',
  -15014: '商品配置未生效，请稍后再试',
  -15020: '操作过快，请稍后再试',
};

package com.example.vpay.controller;
​
import com.example.vpay.service.OrderService;
import com.example.vpay.service.GoodsService;
import com.example.vpay.service.ComplaintService;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
​
import java.util.*;
​
/**
 * 虚拟支付回调处理
 * 路由：POST /api/vp/callback
 * 需要在 MP 后台配置此地址为消息推送 URL
 */
@RestController
@RequestMapping("/api/vp")
public class VpCallbackController {
​
    private static final Logger log = LoggerFactory.getLogger(VpCallbackController.class);
​
    @Autowired
    private OrderService orderService;
​
    @Autowired
    private GoodsService goodsService;
​
    @Autowired
    private ComplaintService complaintService;
​
    @Autowired
    private ObjectMapper objectMapper;
​
    /**
     * 回调统一入口
     * 微信推送的 body 是 JSON 格式，包含 Event 字段区分回调类型
     */
    @PostMapping("/callback")
    public Map<String, Object> handleCallback(@RequestBody Map<String, Object> body) {
        String event = (String) body.get("Event");
        String outTradeNo = (String) body.get("OutTradeNo");
​
        log.info("收到虚拟支付回调: event={}, outTradeNo={}", event, outTradeNo);
​
        // ---- 道具直购发货推送 ----
        if ("xpay_goods_deliver_notify".equals(event)) {
            return handleGoodsDeliver(body);
        }
​
        // ---- 代币支付推送 ----
        if ("xpay_coin_pay_notify".equals(event)) {
            return handleCoinPay(body);
        }
​
        // ---- 退款推送 ----
        if ("xpay_refund_notify".equals(event)) {
            return handleRefund(body);
        }
​
        // ---- 投诉推送 ----
        if ("xpay_complaint_notify".equals(event)) {
            return handleComplaint(body);
        }
​
        // ---- 首次验证回调地址 ----
        // 配置回调 URL 时微信会发验证请求，直接返回传入的 echostr
        if (event == null || "weapp_audit".equals(event)) {
            Map<String, Object> resp = new HashMap<>();
            resp.put("echostr", body.getOrDefault("echostr", "success"));
            return resp;
        }
​
        // 未知事件，返回成功避免重试
        return successResp();
    }
​
    /**
     * 道具直购发货
     */
    private Map<String, Object> handleGoodsDeliver(Map<String, Object> body) {
        Map<String, Object> goodsInfo = (Map<String, Object>) body.get("GoodsInfo");
        Map<String, Object> weChatPayInfo = (Map<String, Object>) body.get("WeChatPayInfo");
​
        String outTradeNo = (String) body.get("OutTradeNo");
        String productId = (String) goodsInfo.get("ProductId");
        int quantity = (int) goodsInfo.get("Quantity");
        int actualPrice = (int) goodsInfo.get("ActualPrice");
        String attach = (String) goodsInfo.get("Attach");
​
        String transactionId = (String) weChatPayInfo.get("TransactionId");
        long paidTime = (long) weChatPayInfo.get("PaidTime");  // 秒级时间戳
​
        try {
            // 1. 解析透传数据
            Map<String, Object> attachData = objectMapper.readValue(
                    attach, Map.class);
            Long uid = Long.valueOf(attachData.get("uid").toString());
​
            // 2. 查询本地订单
            Order order = orderService.getByOutTradeNo(outTradeNo);
            if (order == null) {
                log.error("订单不存在: {}", outTradeNo);
                return errorResp("order not found");
            }
​
            // 3. 幂等检查：已处理过的订单直接返回成功
            if ("success".equals(order.getStatus())) {
                log.info("订单已处理，幂等返回: {}", outTradeNo);
                return successResp();
            }
​
            // 4. 更新订单状态
            order.setStatus("success");
            order.setTransactionId(transactionId);
            order.setPaidTime(new Date(paidTime * 1000));  // 秒 → 毫秒
            order.setPaidAmount(actualPrice);
            orderService.updateOrder(order);
​
            // 5. 发放商品 / 权益（你的业务逻辑）
            goodsService.deliverGoods(uid, productId, quantity, outTradeNo);
​
            // 6. 返回成功，告诉微信「我收到了」
            log.info("发货成功: outTradeNo={}, productId={}", outTradeNo, productId);
            return successResp();
​
        } catch (Exception e) {
            log.error("回调处理异常: outTradeNo={}", outTradeNo, e);
            // 返回失败，微信会重试（最多 15 次）
            return errorResp("internal error");
        }
    }
​
    /**
     * 代币支付
     */
    private Map<String, Object> handleCoinPay(Map<String, Object> body) {
        Map<String, Object> coinInfo = (Map<String, Object>) body.get("CoinInfo");
        // 处理代币扣减逻辑...
        log.info("代币支付回调: {}", coinInfo);
        return successResp();
    }
​
    /**
     * 退款
     */
    private Map<String, Object> handleRefund(Map<String, Object> body) {
        String mchRefundId = (String) body.get("MchRefundId");
        int refundFee = (int) body.get("RefundFee");
        int retCode = (int) body.get("RetCode");
​
        if (retCode == 0) {
            // 退款成功，回收用户权益
            goodsService.revokeGoods(mchRefundId);
            log.info("退款成功，已回收权益: {}", mchRefundId);
        }
        return successResp();
    }
​
    /**
     * 投诉
     */
    private Map<String, Object> handleComplaint(Map<String, Object> body) {
        String complaintId = (String) body.get("ComplaintId");
        String complaintDetail = (String) body.get("ComplaintDetail");
​
        // 存入投诉表，通知运营处理
        complaintService.createRecord(complaintId, complaintDetail);
        log.info("收到投诉: id={}", complaintId);
        return successResp();
    }
​
    // ---- 响应工具方法 ----
​
    private Map<String, Object> successResp() {
        Map<String, Object> resp = new HashMap<>();
        resp.put("ErrCode", 0);
        resp.put("ErrMsg", "success");
        return resp;
    }
​
    private Map<String, Object> errorResp(String errMsg) {
        Map<String, Object> resp = new HashMap<>();
        resp.put("ErrCode", -1);
        resp.put("ErrMsg", errMsg);
        return resp;
    }
}

package com.example.vpay.task;
​
import com.example.vpay.entity.Order;
import com.example.vpay.service.OrderService;
import com.example.vpay.service.WxQueryService;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.scheduling.annotation.Scheduled;
import org.springframework.stereotype.Component;
​
import java.util.List;
​
/**
 * 订单状态轮询兜底任务
 * 每 5 分钟查询近 30 分钟内 pending 状态的订单
 */
@Component
public class OrderPollingTask {
​
    private static final Logger log = LoggerFactory.getLogger(OrderPollingTask.class);
​
    @Autowired
    private OrderService orderService;
​
    @Autowired
    private WxQueryService wxQueryService;
​
    /**
     * 每 5 分钟执行一次
     */
    @Scheduled(fixedRate = 300_000)
    public void pollPendingOrders() {
        List<Order> pendingOrders = orderService.getRecentPendingOrders(30);
​
        for (Order order : pendingOrders) {
            try {
                // 调用微信 /xpay/query_order 接口查询订单状态
                WxQueryService.QueryResult result =
                        wxQueryService.queryOrder(order.getOutTradeNo());
​
                if (result.isPaid()) {
                    // 已支付但未发货 → 补发商品
                    log.info("轮询发现已支付未发货订单: {}", order.getOutTradeNo());
                    orderService.markAsSuccess(order, result.getTransactionId());
                    goodsService.deliverGoods(
                            order.getUid(),
                            order.getProductId(),
                            1,
                            order.getOutTradeNo()
                    );
                }
            } catch (Exception e) {
                log.warn("轮询订单失败: {}", order.getOutTradeNo(), e);
            }
        }
    }
}

const { platform } = wx.getSystemInfoSync();
if (platform === 'android' || platform === 'windows') {
  // 可以发起虚拟支付
}