添加实名验证接口使用文档

Co-authored-by: binarywang <1343140+binarywang@users.noreply.github.com>
2025-12-22 18:08:12 +08:00 · 2025-12-19 17:31:27 +00:00
parent 5f9627296d
commit 4ff3f1e34f
1 changed files with 143 additions and 0 deletions
--- a/weixin-java-pay/REAL_NAME_USAGE.md
+++ b/weixin-java-pay/REAL_NAME_USAGE.md
@@ -0,0 +1,143 @@
+# 微信支付实名验证接口使用说明
+
+## 概述
+
+微信支付实名验证接口允许商户查询用户的实名认证状态，如果用户未实名认证，接口会返回引导用户进行实名认证的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. 获取实名验证服务
+
+```java
+// 获取WxPayService实例
+WxPayService wxPayService = ... // 根据你的配置初始化
+
+// 获取实名验证服务
+RealNameService realNameService = wxPayService.getRealNameService();
+```
+
+### 2. 查询用户实名认证状态（完整方式）
+
+```java
+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. 查询用户实名认证状态（简化方式）
+
+```java
+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. **频率限制**：请注意接口调用频率限制，避免频繁查询同一用户的实名状态。
+
+## 业务场景
+
+- **转账前校验**：在进行企业付款到零钱等操作前，可以先查询用户的实名认证状态
+- **风控审核**：作为业务风控的一部分，确认用户已完成实名认证
+- **用户引导**：发现用户未实名时，引导用户完成实名认证以使用相关功能
+
+## 错误处理
+
+```java
+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;
+    }
+}
+```
+
+## 相关链接
+
+- [微信支付官方文档](https://pay.wechatpay.cn/doc/v2/merchant/4011987607)
+- [WxJava项目主页](https://github.com/binarywang/WxJava)