申请二级商户充值

更新时间:2025.07.29

商户系统须通过调用此接口获取充值链接,随后发起充值流程。

使用注意:
1、指定充值渠道后,部分商户仍可能因微信支付暂不支持导致无法使用该支付方式。(比如小微商户暂不支持网银和转账汇款)
2、充值链接有效期为7天。过期未支付,系统将自动关单

接口说明

支持商户:【平台商户】

请求方式:【POST】/v3/platsolution/ecommerce/recharges/apply

请求域名:【主域名】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  包体参数

 sub_mchid  必填   string(32)

【二级商户号】 微信支付分配的商户号,出资商户号


 out_recharge_no  必填   string(64)

【商户充值单号】 商户系统内部的充值单号,只能由数字、大小写字母组成,在平台商户系统内部唯一


 recharge_scene  必填   string

【充值场景】 按照实际情况填写

可选取值

  • ECOMMERCE_DEPOSIT:  二级商户充值保证金

  • ECOMMERCE_PAYMENT:  二级商户充值运营资金


 account_type  必填   string

【充值入账账户】 使用充值场景所支持的入账账户

可选取值

  • DEPOSIT:  保证金账户

  • OPERATION:  运营账户


 recharge_amount  必填   object

【充值金额】 单位为分,仅支持CNY

属性

 notify_url  选填   string(1024)

【商户回调地址】 异步接收充值结果的回调地址


 available_recharge_channels  选填   array[string]

【可用充值渠道列表】 缺省展示全部充值渠道。若传入可用渠道列表,以传入内容为准

可选取值

  • BANK_TRANSFER:  银行转账

  • QR_RECHARGE:  扫码充值

  • ONLINE_BANK:  网银充值


 remark  选填   string(20)

【充值备注】 将在充值页面展示。UTF8编码,最多允许20个字符

请求示例

Java
Go
curl

需配合微信支付工具库 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 PlatSolutionApply {
26  private static String HOST = "https://api.mch.weixin.qq.com";
27  private static String METHOD = "POST";
28  private static String PATH = "/v3/platsolution/ecommerce/recharges/apply";
29
30  public static void main(String[] args) {
31    // TODO: 请准备商户开发必要参数,参考:https://pay.weixin.qq.com/doc/v3/partner/4013080340
32    PlatSolutionApply client = new PlatSolutionApply(
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    RechargeApplyRequest request = new RechargeApplyRequest();
41    request.subMchid = "1900001109";
42    request.outRechargeNo = "cz202407181234";
43    request.rechargeScene = RechargeScene.ECOMMERCE_DEPOSIT;
44    request.accountType = AccountType.DEPOSIT;
45    request.rechargeAmount = new RechargeAmount();
46    request.rechargeAmount.amount = 500000L;
47    request.rechargeAmount.currency = "CNY";
48    request.notifyUrl = "https://www.weixin.qq.com/wxpay/pay.php";
49    request.availableRechargeChannels = new ArrayList<>();
50    {
51      request.availableRechargeChannels.add(RechargeChannel.BANK_TRANSFER);
52    };
53    request.remark = "example_remark";
54    try {
55      RechargeApplyResponse response = client.run(request);
56
57      // TODO: 请求成功,继续业务逻辑
58      System.out.println(response);
59    } catch (WXPayUtility.ApiException e) {
60      // TODO: 请求失败,根据状态码执行不同的逻辑
61      e.printStackTrace();
62    }
63  }
64
65  public RechargeApplyResponse run(RechargeApplyRequest request) {
66    String uri = PATH;
67    String reqBody = WXPayUtility.toJson(request);
68
69    Request.Builder reqBuilder = new Request.Builder().url(HOST + uri);
70    reqBuilder.addHeader("Accept", "application/json");
71    reqBuilder.addHeader("Wechatpay-Serial", wechatPayPublicKeyId);
72    reqBuilder.addHeader("Authorization", WXPayUtility.buildAuthorization(mchid, certificateSerialNo,privateKey, METHOD, uri, reqBody));
73    reqBuilder.addHeader("Content-Type", "application/json");
74    RequestBody requestBody = RequestBody.create(MediaType.parse("application/json; charset=utf-8"), reqBody);
75    reqBuilder.method(METHOD, requestBody);
76    Request httpRequest = reqBuilder.build();
77
78    // 发送HTTP请求
79    OkHttpClient client = new OkHttpClient.Builder().build();
80    try (Response httpResponse = client.newCall(httpRequest).execute()) {
81      String respBody = WXPayUtility.extractBody(httpResponse);
82      if (httpResponse.code() >= 200 && httpResponse.code() < 300) {
83        // 2XX 成功,验证应答签名
84        WXPayUtility.validateResponse(this.wechatPayPublicKeyId, this.wechatPayPublicKey,
85            httpResponse.headers(), respBody);
86
87        // 从HTTP应答报文构建返回数据
88        return WXPayUtility.fromJson(respBody, RechargeApplyResponse.class);
89      } else {
90        throw new WXPayUtility.ApiException(httpResponse.code(), respBody, httpResponse.headers());
91      }
92    } catch (IOException e) {
93      throw new UncheckedIOException("Sending request to " + uri + " failed.", e);
94    }
95  }
96
97  private final String mchid;
98  private final String certificateSerialNo;
99  private final PrivateKey privateKey;
100  private final String wechatPayPublicKeyId;
101  private final PublicKey wechatPayPublicKey;
102
103  public PlatSolutionApply(String mchid, String certificateSerialNo, String privateKeyFilePath, String wechatPayPublicKeyId, String wechatPayPublicKeyFilePath) {
104    this.mchid = mchid;
105    this.certificateSerialNo = certificateSerialNo;
106    this.privateKey = WXPayUtility.loadPrivateKeyFromPath(privateKeyFilePath);
107    this.wechatPayPublicKeyId = wechatPayPublicKeyId;
108    this.wechatPayPublicKey = WXPayUtility.loadPublicKeyFromPath(wechatPayPublicKeyFilePath);
109  }
110
111  public static class RechargeApplyRequest {
112    @SerializedName("sub_mchid")
113    public String subMchid;
114  
115    @SerializedName("out_recharge_no")
116    public String outRechargeNo;
117  
118    @SerializedName("recharge_scene")
119    public RechargeScene rechargeScene;
120  
121    @SerializedName("account_type")
122    public AccountType accountType;
123  
124    @SerializedName("recharge_amount")
125    public RechargeAmount rechargeAmount;
126  
127    @SerializedName("notify_url")
128    public String notifyUrl;
129  
130    @SerializedName("available_recharge_channels")
131    public List<RechargeChannel> availableRechargeChannels;
132  
133    @SerializedName("remark")
134    public String remark;
135  }
136  
137  public static class RechargeApplyResponse {
138    @SerializedName("recharge_id")
139    public String rechargeId;
140  
141    @SerializedName("out_recharge_no")
142    public String outRechargeNo;
143  
144    @SerializedName("recharge_url")
145    public String rechargeUrl;
146  }
147  
148  public enum RechargeScene {
149    @SerializedName("ECOMMERCE_DEPOSIT")
150    ECOMMERCE_DEPOSIT,
151    @SerializedName("ECOMMERCE_PAYMENT")
152    ECOMMERCE_PAYMENT
153  }
154  
155  public enum AccountType {
156    @SerializedName("DEPOSIT")
157    DEPOSIT,
158    @SerializedName("OPERATION")
159    OPERATION
160  }
161  
162  public static class RechargeAmount {
163    @SerializedName("amount")
164    public Long amount;
165  
166    @SerializedName("currency")
167    public String currency;
168  }
169  
170  public enum RechargeChannel {
171    @SerializedName("BANK_TRANSFER")
172    BANK_TRANSFER,
173    @SerializedName("QR_RECHARGE")
174    QR_RECHARGE,
175    @SerializedName("ONLINE_BANK")
176    ONLINE_BANK
177  }
178  
179}
180

应答参数

200 OK

 recharge_id  必填   string(27)

【微信支付充值单号】 微信支付充值单号


 out_recharge_no  必填   string(64)

【商户充值单号】 商户系统内部的充值单号,只能由数字、大小写字母组成,在平台商户系统内部唯一


 recharge_url  必填   string(2048)

【充值链接】 由链接进入充值页面

应答示例

200 OK

1{
2  "recharge_id" : "172207846292553701",
3  "out_recharge_no" : "cz202407181234",
4  "recharge_url" : "https://www.payapp.qq.com/plat/recharge.html"
5}
6

 

错误码

公共错误码

状态码

错误码

描述

解决方案

400

PARAM_ERROR

参数错误

请根据错误提示正确传入参数

400

INVALID_REQUEST

HTTP 请求不符合微信支付 APIv3 接口规则

请参阅 接口规则

401

SIGN_ERROR

验证不通过

请参阅 签名常见问题

500

SYSTEM_ERROR

系统异常,请稍后重试

请稍后重试

业务错误码

状态码

错误码

描述

解决方案

400

INVALID_REQUEST

入账账户不存在

二级子商户开通对应入账账户

400

INVALID_REQUEST

单笔充值金额超过上限

单笔充值金额小于等于2千万元

400

INVALID_REQUEST

该业务充值单号已存在

请核实商户充值单号是否重复

403

NO_AUTH

服务商未开通平台收付通

服务商开通微信支付平台收付通

403

NO_AUTH

平台充值权限被处罚,无法发起充值

服务商登录「合作伙伴平台-账户中心-违约记录」查看详情

403

NO_AUTH

商户号出入金权限被管控

二级子商户前往「微信支付商户平台-账户中心-违约记录」或「商家助手小程序-风险处理」查看详情

429

FREQUENCY_LIMITED

频率超限

请降低请求频率

 

 

反馈
咨询
目录
置顶