获取微信分付曝光建议
更新时间:2025.09.29获取微信分付曝光建议
接口说明
支持商户:【普通商户】
请求方式:【POST】/v3/pay/instal/exposure
请求域名:【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点
【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点 ,指引点击查看
请求参数
Header HTTP头参数
Authorization 必填 string
请参考签名认证生成认证信息
Accept 必填 string
请设置为application/json
Content-Type 必填 string
请设置为application/json
body 包体参数
mchid 必填 string(32)
【商户号】 是由微信支付系统生成并分配给每个商户的唯一标识符,商户号获取方式请参考普通商户模式开发必要参数说明。
appid 必填 string(32)
【商户AppID】 由微信生成的应用ID,全局唯一。是商户在微信开放平台(移动应用)或公众平台(公众号/小程序)上申请的一个唯一标识。需确保该appid与mchid有绑定关系,具体请参考普通商户模式开发必要参数说明。请求基础下单接口时请注意AppID的应用属性,例如公众号场景下,需使用应用属性为公众号的AppID。
user_id_type 必填 string
【用户ID的类型】
可选取值
UNKNOWN_USER_ID_TYPE: 未知类型OPENID: 普通商户的OpenIDPHONE_NO: 手机号SP_OPENID: 服务商的OpenIDSUB_OPENID: 子商户的OpenID
openid 选填 string(128)
【用户标识】 用户在商户appid下的唯一标识。详见OpenID获取。若user_id_type为OPENID,则填此字段。
phone_number_hash 选填 string(64)
【用户手机号的十六进制字符串】 用户手机号的SM3哈希值并编码为大写十六进制字符串。若user_id_type为PHONE_NO,则填此字段。
请求示例
POST
1curl -X POST \ 2 https://api.mch.weixin.qq.com/v3/pay/instal/exposure \ 3 -H "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"1900000001\",..." \ 4 -H "Accept: application/json" \ 5 -H "Content-Type: application/json" \ 6 -d '{ 7 "mchid" : "12345", 8 "appid" : "123abc", 9 "user_id_type" : "OPENID", 10 "openid" : "123456789", 11 "phone_number_hash" : "EF879546FFFF" 12 }' 13
需配合微信支付工具库 WXPayUtility 使用,请参考Java
1package com.java.demo; 2 3import com.java.utils.WXPayUtility; // 引用微信支付工具库,参考:https://pay.weixin.qq.com/doc/v3/merchant/4014931831 4 5import com.google.gson.annotations.SerializedName; 6import com.google.gson.annotations.Expose; 7import okhttp3.MediaType; 8import okhttp3.OkHttpClient; 9import okhttp3.Request; 10import okhttp3.RequestBody; 11import okhttp3.Response; 12 13import java.io.IOException; 14import java.io.UncheckedIOException; 15import java.security.PrivateKey; 16import java.security.PublicKey; 17import java.util.ArrayList; 18import java.util.HashMap; 19import java.util.List; 20import java.util.Map; 21 22/** 23 * 获取微信分付曝光建议 24 */ 25public class GetExposureRecommendation { 26 private static String HOST = "https://api.mch.weixin.qq.com"; 27 private static String METHOD = "POST"; 28 private static String PATH = "/v3/pay/instal/exposure"; 29 30 public static void main(String[] args) { 31 // TODO: 请准备商户开发必要参数,参考:https://pay.weixin.qq.com/doc/v3/merchant/4013070756 32 GetExposureRecommendation client = new GetExposureRecommendation( 33 "19xxxxxxxx", // 商户号,是由微信支付系统生成并分配给每个商户的唯一标识符,商户号获取方式参考 https://pay.weixin.qq.com/doc/v3/merchant/4013070756 34 "1DDE55AD98Exxxxxxxxxx", // 商户API证书序列号,如何获取请参考 https://pay.weixin.qq.com/doc/v3/merchant/4013053053 35 "/path/to/apiclient_key.pem", // 商户API证书私钥文件路径,本地文件路径 36 "PUB_KEY_ID_xxxxxxxxxxxxx", // 微信支付公钥ID,如何获取请参考 https://pay.weixin.qq.com/doc/v3/merchant/4013038816 37 "/path/to/wxp_pub.pem" // 微信支付公钥文件路径,本地文件路径 38 ); 39 40 GetExposureRecommendationRequest request = new GetExposureRecommendationRequest(); 41 request.mchid = "12345"; 42 request.appid = "123abc"; 43 request.userIdType = UserIdType.OPENID; 44 request.openid = "123456789"; 45 request.phoneNumberHash = "EF879546FFFF"; 46 try { 47 ExposureRecommendation response = client.run(request); 48 // TODO: 请求成功,继续业务逻辑 49 System.out.println(response); 50 } catch (WXPayUtility.ApiException e) { 51 // TODO: 请求失败,根据状态码执行不同的逻辑 52 e.printStackTrace(); 53 } 54 } 55 56 public ExposureRecommendation run(GetExposureRecommendationRequest request) { 57 String uri = PATH; 58 String reqBody = WXPayUtility.toJson(request); 59 60 Request.Builder reqBuilder = new Request.Builder().url(HOST + uri); 61 reqBuilder.addHeader("Accept", "application/json"); 62 reqBuilder.addHeader("Wechatpay-Serial", wechatPayPublicKeyId); 63 reqBuilder.addHeader("Authorization", WXPayUtility.buildAuthorization(mchid, certificateSerialNo,privateKey, METHOD, uri, reqBody)); 64 reqBuilder.addHeader("Content-Type", "application/json"); 65 RequestBody requestBody = RequestBody.create(MediaType.parse("application/json; charset=utf-8"), reqBody); 66 reqBuilder.method(METHOD, requestBody); 67 Request httpRequest = reqBuilder.build(); 68 69 // 发送HTTP请求 70 OkHttpClient client = new OkHttpClient.Builder().build(); 71 try (Response httpResponse = client.newCall(httpRequest).execute()) { 72 String respBody = WXPayUtility.extractBody(httpResponse); 73 if (httpResponse.code() >= 200 && httpResponse.code() < 300) { 74 // 2XX 成功,验证应答签名 75 WXPayUtility.validateResponse(this.wechatPayPublicKeyId, this.wechatPayPublicKey, 76 httpResponse.headers(), respBody); 77 78 // 从HTTP应答报文构建返回数据 79 return WXPayUtility.fromJson(respBody, ExposureRecommendation.class); 80 } else { 81 throw new WXPayUtility.ApiException(httpResponse.code(), respBody, httpResponse.headers()); 82 } 83 } catch (IOException e) { 84 throw new UncheckedIOException("Sending request to " + uri + " failed.", e); 85 } 86 } 87 88 private final String mchid; 89 private final String certificateSerialNo; 90 private final PrivateKey privateKey; 91 private final String wechatPayPublicKeyId; 92 private final PublicKey wechatPayPublicKey; 93 94 public GetExposureRecommendation(String mchid, String certificateSerialNo, String privateKeyFilePath, String wechatPayPublicKeyId, String wechatPayPublicKeyFilePath) { 95 this.mchid = mchid; 96 this.certificateSerialNo = certificateSerialNo; 97 this.privateKey = WXPayUtility.loadPrivateKeyFromPath(privateKeyFilePath); 98 this.wechatPayPublicKeyId = wechatPayPublicKeyId; 99 this.wechatPayPublicKey = WXPayUtility.loadPublicKeyFromPath(wechatPayPublicKeyFilePath); 100 } 101 102 public static class GetExposureRecommendationRequest { 103 @SerializedName("mchid") 104 public String mchid; 105 106 @SerializedName("appid") 107 public String appid; 108 109 @SerializedName("user_id_type") 110 public UserIdType userIdType; 111 112 @SerializedName("openid") 113 public String openid; 114 115 @SerializedName("phone_number_hash") 116 public String phoneNumberHash; 117 } 118 119 public static class ExposureRecommendation { 120 @SerializedName("recommend_exposure") 121 public Boolean recommendExposure; 122 } 123 124 public enum UserIdType { 125 @SerializedName("UNKNOWN_USER_ID_TYPE") 126 UNKNOWN_USER_ID_TYPE, 127 @SerializedName("OPENID") 128 OPENID, 129 @SerializedName("PHONE_NO") 130 PHONE_NO, 131 @SerializedName("SP_OPENID") 132 SP_OPENID, 133 @SerializedName("SUB_OPENID") 134 SUB_OPENID 135 } 136 137} 138
需配合微信支付工具库 wxpay_utility 使用,请参考Go
1package main 2 3import ( 4 "bytes" 5 "demo/wxpay_utility" // 引用微信支付工具库,参考 https://pay.weixin.qq.com/doc/v3/merchant/4015119334 6 "encoding/json" 7 "fmt" 8 "net/http" 9 "net/url" 10) 11 12func main() { 13 // TODO: 请准备商户开发必要参数,参考:https://pay.weixin.qq.com/doc/v3/merchant/4013070756 14 config, err := wxpay_utility.CreateMchConfig( 15 "19xxxxxxxx", // 商户号,是由微信支付系统生成并分配给每个商户的唯一标识符,商户号获取方式参考 https://pay.weixin.qq.com/doc/v3/merchant/4013070756 16 "1DDE55AD98Exxxxxxxxxx", // 商户API证书序列号,如何获取请参考 https://pay.weixin.qq.com/doc/v3/merchant/4013053053 17 "/path/to/apiclient_key.pem", // 商户API证书私钥文件路径,本地文件路径 18 "PUB_KEY_ID_xxxxxxxxxxxxx", // 微信支付公钥ID,如何获取请参考 https://pay.weixin.qq.com/doc/v3/merchant/4013038816 19 "/path/to/wxp_pub.pem", // 微信支付公钥文件路径,本地文件路径 20 ) 21 if err != nil { 22 fmt.Println(err) 23 return 24 } 25 26 request := &GetExposureRecommendationRequest{ 27 Mchid: wxpay_utility.String("12345"), 28 Appid: wxpay_utility.String("123abc"), 29 UserIdType: USERIDTYPE_OPENID.Ptr(), 30 Openid: wxpay_utility.String("123456789"), 31 PhoneNumberHash: wxpay_utility.String("EF879546FFFF"), 32 } 33 34 response, err := GetExposureRecommendation(config, request) 35 if err != nil { 36 fmt.Printf("请求失败: %+v\n", err) 37 // TODO: 请求失败,根据状态码执行不同的处理 38 return 39 } 40 41 // TODO: 请求成功,继续业务逻辑 42 fmt.Printf("请求成功: %+v\n", response) 43} 44 45func GetExposureRecommendation(config *wxpay_utility.MchConfig, request *GetExposureRecommendationRequest) (response *ExposureRecommendation, err error) { 46 const ( 47 host = "https://api.mch.weixin.qq.com" 48 method = "POST" 49 path = "/v3/pay/instal/exposure" 50 ) 51 52 reqUrl, err := url.Parse(fmt.Sprintf("%s%s", host, path)) 53 if err != nil { 54 return nil, err 55 } 56 reqBody, err := json.Marshal(request) 57 if err != nil { 58 return nil, err 59 } 60 httpRequest, err := http.NewRequest(method, reqUrl.String(), bytes.NewReader(reqBody)) 61 if err != nil { 62 return nil, err 63 } 64 httpRequest.Header.Set("Accept", "application/json") 65 httpRequest.Header.Set("Wechatpay-Serial", config.WechatPayPublicKeyId()) 66 httpRequest.Header.Set("Content-Type", "application/json") 67 authorization, err := wxpay_utility.BuildAuthorization(config.MchId(), config.CertificateSerialNo(), config.PrivateKey(), method, reqUrl.RequestURI(), reqBody) 68 if err != nil { 69 return nil, err 70 } 71 httpRequest.Header.Set("Authorization", authorization) 72 73 client := &http.Client{} 74 httpResponse, err := client.Do(httpRequest) 75 if err != nil { 76 return nil, err 77 } 78 respBody, err := wxpay_utility.ExtractResponseBody(httpResponse) 79 if err != nil { 80 return nil, err 81 } 82 if httpResponse.StatusCode >= 200 && httpResponse.StatusCode < 300 { 83 // 2XX 成功,验证应答签名 84 err = wxpay_utility.ValidateResponse( 85 config.WechatPayPublicKeyId(), 86 config.WechatPayPublicKey(), 87 &httpResponse.Header, 88 respBody, 89 ) 90 if err != nil { 91 return nil, err 92 } 93 response := &ExposureRecommendation{} 94 if err := json.Unmarshal(respBody, response); err != nil { 95 return nil, err 96 } 97 98 return response, nil 99 } else { 100 return nil, wxpay_utility.NewApiException( 101 httpResponse.StatusCode, 102 httpResponse.Header, 103 respBody, 104 ) 105 } 106} 107 108type GetExposureRecommendationRequest struct { 109 Mchid *string `json:"mchid,omitempty"` 110 Appid *string `json:"appid,omitempty"` 111 UserIdType *UserIdType `json:"user_id_type,omitempty"` 112 Openid *string `json:"openid,omitempty"` 113 PhoneNumberHash *string `json:"phone_number_hash,omitempty"` 114} 115 116type ExposureRecommendation struct { 117 RecommendExposure *bool `json:"recommend_exposure,omitempty"` 118} 119 120type UserIdType string 121 122func (e UserIdType) Ptr() *UserIdType { 123 return &e 124} 125 126const ( 127 USERIDTYPE_UNKNOWN_USER_ID_TYPE UserIdType = "UNKNOWN_USER_ID_TYPE" 128 USERIDTYPE_OPENID UserIdType = "OPENID" 129 USERIDTYPE_PHONE_NO UserIdType = "PHONE_NO" 130 USERIDTYPE_SP_OPENID UserIdType = "SP_OPENID" 131 USERIDTYPE_SUB_OPENID UserIdType = "SUB_OPENID" 132) 133
应答参数
200 OK
recommend_exposure 必填 boolean
【是否建议曝光微信分付】 是否建议曝光微信分付
应答示例
200 OK
1{ 2 "recommend_exposure" : true 3} 4
错误码
以下是本接口返回的错误码列表。详细错误码规则,请参考微信支付接口规则-错误码和错误提示
