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