weixin-java-tools/weixin-java-pay/REAL_NAME_USAGE.md

微信支付实名验证接口使用说明

概述

微信支付实名验证接口允许商户查询用户的实名认证状态，如果用户未实名认证，接口会返回引导用户进行实名认证的URL。

官方文档

https://pay.wechatpay.cn/doc/v2/merchant/4011987607

接口说明

查询用户实名认证信息

• 接口地址：https://api.mch.weixin.qq.com/userinfo/realnameauth/query

• 请求方式：POST（需要使用商户证书）

• 请求参数：

  • appid：公众账号ID（自动填充）
  • mch_id：商户号（自动填充）
  • openid：用户在商户appid下的唯一标识
  • nonce_str：随机字符串（自动生成）
  • sign：签名（自动生成）

• 返回参数：

  • return_code：返回状态码
  • return_msg：返回信息
  • result_code：业务结果
  • openid：用户标识
  • is_certified：实名认证状态（Y-已实名认证，N-未实名认证）
  • cert_info：实名认证信息（加密，仅已实名时返回）
  • guide_url：引导用户进行实名认证的URL（仅未实名时返回）

使用示例

1. 获取实名验证服务

// 获取WxPayService实例
WxPayService wxPayService = ... // 根据你的配置初始化

// 获取实名验证服务
RealNameService realNameService = wxPayService.getRealNameService();

2. 查询用户实名认证状态（完整方式）

import com.github.binarywang.wxpay.bean.realname.RealNameRequest;
import com.github.binarywang.wxpay.bean.realname.RealNameResult;
import com.github.binarywang.wxpay.exception.WxPayException;

try {
    // 构建请求对象
    RealNameRequest request = RealNameRequest.newBuilder()
        .openid("oUpF8uMuAJO_M2pxb1Q9zNjWeS6o") // 用户的openid
        .build();

    // 调用查询接口
    RealNameResult result = realNameService.queryRealName(request);

    // 处理返回结果
    if ("Y".equals(result.getIsCertified())) {
        System.out.println("用户已实名认证");
        System.out.println("认证信息：" + result.getCertInfo());
    } else {
        System.out.println("用户未实名认证");
        System.out.println("引导链接：" + result.getGuideUrl());
        // 可以将guide_url提供给用户，引导其完成实名认证
    }
} catch (WxPayException e) {
    System.err.println("查询失败：" + e.getMessage());
}

3. 查询用户实名认证状态（简化方式）

import com.github.binarywang.wxpay.bean.realname.RealNameResult;
import com.github.binarywang.wxpay.exception.WxPayException;

try {
    // 直接传入openid进行查询
    RealNameResult result = realNameService.queryRealName("oUpF8uMuAJO_M2pxb1Q9zNjWeS6o");

    // 处理返回结果
    if ("Y".equals(result.getIsCertified())) {
        System.out.println("用户已实名认证");
    } else {
        System.out.println("用户未实名认证，引导链接：" + result.getGuideUrl());
    }
} catch (WxPayException e) {
    System.err.println("查询失败：" + e.getMessage());
}

注意事项

1. 证书要求：本接口需要使用商户证书进行请求，请确保已正确配置商户证书。

2. OPENID获取：openid是用户在商户appid下的唯一标识，需要通过微信公众平台或小程序获取。

3. 认证信息：cert_info字段返回的信息是加密的，需要使用相应的解密方法才能获取明文信息。

4. 引导链接：当用户未实名时，返回的guide_url可以用于引导用户完成实名认证，建议在小程序或H5页面中使用。

5. 频率限制：请注意接口调用频率限制，避免频繁查询同一用户的实名状态。

业务场景

• 转账前校验：在进行企业付款到零钱等操作前，可以先查询用户的实名认证状态
• 风控审核：作为业务风控的一部分，确认用户已完成实名认证
• 用户引导：发现用户未实名时，引导用户完成实名认证以使用相关功能

错误处理

try {
    RealNameResult result = realNameService.queryRealName(openid);
    // 处理结果...
} catch (WxPayException e) {
    // 处理异常
    String errorCode = e.getErrCode();
    String errorMsg = e.getErrCodeDes();
    
    // 根据错误码进行相应处理
    switch (errorCode) {
        case "SYSTEMERROR":
            // 系统错误，建议稍后重试
            break;
        case "PARAM_ERROR":
            // 参数错误，检查openid是否正确
            break;
        default:
            // 其他错误
            break;
    }
}

相关链接

• 微信支付官方文档
• WxJava项目主页