支付方式前置曝光
更新时间:2026.03.26服务商查询微信分付曝光建议
接口说明
支持商户:【普通服务商】
请求方式:【POST】/v3/pay/partner/transactions/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)
【子商户APPID】 是子商户在微信开放平台(移动应用)或公众平台(公众号/小程序)上申请的一个唯一标识。需确保该sub_appid与sub_mchid有绑定关系,具体请参考服务商模式开发必要参数说明。
payer 选填 object
【支付者信息】 支付者信息
| 属性 | |
sp_openid 选填 string(128) 【用户服务商标识】 用户在服务商sp_appid下的唯一标识,详见 获取OpenID文档。使用此参数时需传入服务商sp_appid。sp_openid、phone_number_hash和sub_openid只需填其中之一。 phone_number_hash 选填 string(64) 【用户手机号的哈希值】 用户手机号(包括国家码前缀)的SM3哈希值并编码为大写十六进制字符串。sp_openid、phone_number_hash和sub_openid只需填其中之一。 sub_openid 选填 string(128) 【用户子商户标识】 用户在子商户sub_appid下的唯一标识,详见 获取OpenID文档。使用此参数时需传入子商户sub_appid。sp_openid、phone_number_hash和sub_openid只需填其中之一。 |
out_trade_no 必填 string(32)
【商户订单号】 服务商系统内部订单号,要求6-32个字符内,只能是数字、大小写字母_-|* 且在同一个服务商商户号下唯一。如需使用微信分付方式付款,商户在调用下单接口时的商户订单号需和此商户订单号一致。
请求示例
POST
1curl -X POST \ 2 https://api.mch.weixin.qq.com/v3/pay/partner/transactions/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" : "example_sp_mchid", 8 "sp_appid" : "wxd678efh567hg6787", 9 "sub_mchid" : "example_sub_mchid", 10 "sub_appid" : "wxd678efh567hg6787", 11 "payer" : { 12 "sp_openid" : "oLTPCuEfSOSZA6X5uR_JxNKjrGLg", 13 "phone_number_hash" : "ABDEF3445546456B", 14 "sub_openid" : "oLTPCuEfSOSZA6X5uR_JxNKjrGLg" 15 }, 16 "out_trade_no" : "example_out_trade_no" 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 PartnerGetExposureRecommendation { 26 private static String HOST = "https://api.mch.weixin.qq.com"; 27 private static String METHOD = "POST"; 28 private static String PATH = "/v3/pay/partner/transactions/exposure"; 29 30 public static void main(String[] args) { 31 // TODO: 请准备商户开发必要参数,参考:https://pay.weixin.qq.com/doc/v3/partner/4013080340 32 PartnerGetExposureRecommendation client = new PartnerGetExposureRecommendation( 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 PartnerAPIv3PartnerGetExposureRecommendationRequest request = new PartnerAPIv3PartnerGetExposureRecommendationRequest(); 41 request.spMchid = "example_sp_mchid"; 42 request.spAppid = "wxd678efh567hg6787"; 43 request.subMchid = "example_sub_mchid"; 44 request.subAppid = "wxd678efh567hg6787"; 45 request.payer = new PartnerExposurePayer(); 46 request.payer.spOpenid = "oLTPCuEfSOSZA6X5uR_JxNKjrGLg"; 47 request.payer.phoneNumberHash = "ABDEF3445546456B"; 48 request.payer.subOpenid = "oLTPCuEfSOSZA6X5uR_JxNKjrGLg"; 49 request.outTradeNo = "example_out_trade_no"; 50 try { 51 PartnerAPIv3PartnerGetExposureRecommendationResponse 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 PartnerAPIv3PartnerGetExposureRecommendationResponse run(PartnerAPIv3PartnerGetExposureRecommendationRequest 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, PartnerAPIv3PartnerGetExposureRecommendationResponse.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 PartnerGetExposureRecommendation(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 PartnerAPIv3PartnerGetExposureRecommendationRequest { 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("payer") 120 public PartnerExposurePayer payer; 121 122 @SerializedName("out_trade_no") 123 public String outTradeNo; 124 } 125 126 public static class PartnerAPIv3PartnerGetExposureRecommendationResponse { 127 @SerializedName("fqf_exposure") 128 public Boolean fqfExposure; 129 130 @SerializedName("market_exposure_token") 131 public String marketExposureToken; 132 } 133 134 public static class PartnerExposurePayer { 135 @SerializedName("sp_openid") 136 public String spOpenid; 137 138 @SerializedName("phone_number_hash") 139 public String phoneNumberHash; 140 141 @SerializedName("sub_openid") 142 public String subOpenid; 143 } 144 145} 146
需配合微信支付工具库 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 := &PartnerApiv3PartnerGetExposureRecommendationRequest{ 27 SpMchid: wxpay_utility.String("example_sp_mchid"), 28 SpAppid: wxpay_utility.String("wxd678efh567hg6787"), 29 SubMchid: wxpay_utility.String("example_sub_mchid"), 30 SubAppid: wxpay_utility.String("wxd678efh567hg6787"), 31 Payer: &PartnerExposurePayer{ 32 SpOpenid: wxpay_utility.String("oLTPCuEfSOSZA6X5uR_JxNKjrGLg"), 33 PhoneNumberHash: wxpay_utility.String("ABDEF3445546456B"), 34 SubOpenid: wxpay_utility.String("oLTPCuEfSOSZA6X5uR_JxNKjrGLg"), 35 }, 36 OutTradeNo: wxpay_utility.String("example_out_trade_no"), 37 } 38 39 response, err := PartnerGetExposureRecommendation(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 PartnerGetExposureRecommendation(config *wxpay_utility.MchConfig, request *PartnerApiv3PartnerGetExposureRecommendationRequest) (response *PartnerApiv3PartnerGetExposureRecommendationResponse, err error) { 51 const ( 52 host = "https://api.mch.weixin.qq.com" 53 method = "POST" 54 path = "/v3/pay/partner/transactions/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 := &PartnerApiv3PartnerGetExposureRecommendationResponse{} 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 PartnerApiv3PartnerGetExposureRecommendationRequest 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 Payer *PartnerExposurePayer `json:"payer,omitempty"` 119 OutTradeNo *string `json:"out_trade_no,omitempty"` 120} 121 122type PartnerApiv3PartnerGetExposureRecommendationResponse struct { 123 FqfExposure *bool `json:"fqf_exposure,omitempty"` 124 MarketExposureToken *string `json:"market_exposure_token,omitempty"` 125} 126 127type PartnerExposurePayer struct { 128 SpOpenid *string `json:"sp_openid,omitempty"` 129 PhoneNumberHash *string `json:"phone_number_hash,omitempty"` 130 SubOpenid *string `json:"sub_openid,omitempty"` 131} 132
应答参数
200 OK
fqf_exposure 必填 boolean
【是否建议曝光微信分付】 是否建议曝光微信分付
market_exposure_token 选填 string(128)
【曝光凭证】 如果建议曝光则返回曝光凭证,商户在调起支付时在package参数中需传入该参数。
应答示例
200 OK
1{ 2 "fqf_exposure" : true, 3 "market_exposure_token" : "Dfkdsf324+-LKFD=" 4} 5
错误码
以下是本接口返回的错误码列表。详细错误码规则,请参考微信支付接口规则-错误码和错误提示

