企业商户作废员工企业支付额度卡

更新时间:2025.05.09

企业商户作废员工企业支付额度卡。该接口允许服务商作废已下发给员工的企业支付额度卡,作废后该额度卡将无法继续使用,可指定作废原因。当额度卡使用错误、发放错误或需要提前回收额度时,企业可通过此接口作废额度卡。

接口说明

支持商户:【普通服务商】

请求方式:【POST】/v3/webizpay/employees/{employee_id}/quota-cards/{card_no}/cancel

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


path  路径参数

 employee_id  必填   string(64)

【微信授权关系 ID】 微信授权关系ID,微信支付平台生成的唯一标识授权关系的ID,用户注册时会回调商户获取微信授权关系ID或者商户通过企业下唯一的员工ID查询企业支付员工接口获得。
示例:WeBizPay_a968402a-73bb-43e2-9e1a-8371b0ca3d7c


 card_no  必填   string(64)

【企业支付额度卡卡号】 企业支付额度卡卡号,由请求微信支付发放额度卡时返回
示例:1068019671702503425


body  包体参数

 sp_mchid  必填   string(32)

【服务商商户号】 是由微信支付系统生成并分配给每个服务商的唯一标识符,具体请参考服务商模式开发必要参数说明


 sub_mchid  必填   string(32)

【出资子商户号】 出资由服务商为子商户进件后获取,具体请参考服务商模式开发必要参数说明。子商户号


 reason  必填   string(50)

【作废原因】 作废原因,长度不可超过50个字符

请求示例

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 CancelQuotaCard {
26  private static String HOST = "https://api.mch.weixin.qq.com";
27  private static String METHOD = "POST";
28  private static String PATH = "/v3/webizpay/employees/{employee_id}/quota-cards/{card_no}/cancel";
29
30  public static void main(String[] args) {
31    // TODO: 请准备商户开发必要参数,参考:https://pay.weixin.qq.com/doc/v3/partner/4013080340
32    CancelQuotaCard client = new CancelQuotaCard(
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    CancelQuotaCardRequest request = new CancelQuotaCardRequest();
41    request.employeeId = "WeBizPay_a968402a-73bb-43e2-9e1a-8371b0ca3d7c";
42    request.cardNo = "1068019671702503425";
43    request.spMchid = "12341234";
44    request.subMchid = "43214321";
45    request.reason = "商户主动作废";
46    try {
47      CardsCancelQuotaCardResponse response = client.run(request);
48
49      // TODO: 请求成功,继续业务逻辑
50      System.out.println(response);
51    } catch (WXPayUtility.ApiException e) {
52      // TODO: 请求失败,根据状态码执行不同的逻辑
53      e.printStackTrace();
54    }
55  }
56
57  public CardsCancelQuotaCardResponse run(CancelQuotaCardRequest request) {
58    String uri = PATH;
59    uri = uri.replace("{employee_id}", WXPayUtility.urlEncode(request.employeeId));
60    uri = uri.replace("{card_no}", WXPayUtility.urlEncode(request.cardNo));
61    String reqBody = WXPayUtility.toJson(request);
62
63    Request.Builder reqBuilder = new Request.Builder().url(HOST + uri);
64    reqBuilder.addHeader("Accept", "application/json");
65    reqBuilder.addHeader("Wechatpay-Serial", wechatPayPublicKeyId);
66    reqBuilder.addHeader("Authorization", WXPayUtility.buildAuthorization(mchid, certificateSerialNo,privateKey, METHOD, uri, reqBody));
67    reqBuilder.addHeader("Content-Type", "application/json");
68    RequestBody requestBody = RequestBody.create(MediaType.parse("application/json; charset=utf-8"), reqBody);
69    reqBuilder.method(METHOD, requestBody);
70    Request httpRequest = reqBuilder.build();
71
72    // 发送HTTP请求
73    OkHttpClient client = new OkHttpClient.Builder().build();
74    try (Response httpResponse = client.newCall(httpRequest).execute()) {
75      String respBody = WXPayUtility.extractBody(httpResponse);
76      if (httpResponse.code() >= 200 && httpResponse.code() < 300) {
77        // 2XX 成功,验证应答签名
78        WXPayUtility.validateResponse(this.wechatPayPublicKeyId, this.wechatPayPublicKey,
79            httpResponse.headers(), respBody);
80
81        // 从HTTP应答报文构建返回数据
82        return WXPayUtility.fromJson(respBody, CardsCancelQuotaCardResponse.class);
83      } else {
84        throw new WXPayUtility.ApiException(httpResponse.code(), respBody, httpResponse.headers());
85      }
86    } catch (IOException e) {
87      throw new UncheckedIOException("Sending request to " + uri + " failed.", e);
88    }
89  }
90
91  private final String mchid;
92  private final String certificateSerialNo;
93  private final PrivateKey privateKey;
94  private final String wechatPayPublicKeyId;
95  private final PublicKey wechatPayPublicKey;
96
97  public CancelQuotaCard(String mchid, String certificateSerialNo, String privateKeyFilePath, String wechatPayPublicKeyId, String wechatPayPublicKeyFilePath) {
98    this.mchid = mchid;
99    this.certificateSerialNo = certificateSerialNo;
100    this.privateKey = WXPayUtility.loadPrivateKeyFromPath(privateKeyFilePath);
101    this.wechatPayPublicKeyId = wechatPayPublicKeyId;
102    this.wechatPayPublicKey = WXPayUtility.loadPublicKeyFromPath(wechatPayPublicKeyFilePath);
103  }
104
105  public static class CancelQuotaCardRequest {
106    @SerializedName("sp_mchid")
107    public String spMchid;
108  
109    @SerializedName("sub_mchid")
110    public String subMchid;
111  
112    @SerializedName("employee_id")
113    @Expose(serialize = false)
114    public String employeeId;
115  
116    @SerializedName("card_no")
117    @Expose(serialize = false)
118    public String cardNo;
119  
120    @SerializedName("reason")
121    public String reason;
122  }
123  
124  public static class CardsCancelQuotaCardResponse {
125    @SerializedName("sp_mchid")
126    public String spMchid;
127  
128    @SerializedName("sub_mchid")
129    public String subMchid;
130  
131    @SerializedName("employee_id")
132    public String employeeId;
133  
134    @SerializedName("card_no")
135    public String cardNo;
136  
137    @SerializedName("card_state")
138    public CardState cardState;
139  
140    @SerializedName("card_disabled_time")
141    public String cardDisabledTime;
142  }
143  
144  public enum CardState {
145    @SerializedName("ACTIVE")
146    ACTIVE,
147    @SerializedName("DISABLED")
148    DISABLED
149  }
150  
151}
152

应答参数

200 OK

 sp_mchid  必填   string(32)

【服务商商户号】 服务商商户号


 sub_mchid  必填   string(32)

【出资子商户号】 出资子商户号


 employee_id  必填   string(64)

【微信授权关系 ID】 微信授权关系ID,指定接收额度卡的员工授权关系,该员工必须已完成企业支付授权
示例:WeBizPay_a968402a-73bb-43e2-9e1a-8371b0ca3d7c


 card_no  必填   string(64)

【企业支付额度卡卡号】 企业支付额度卡卡号,微信支付平台生成的唯一标识额度卡的编号。通过创建卡和查询卡返回。由商户作废卡时传入
示例:1068019671702503425


 card_state  必填   string

【卡片状态】 卡片状态

可选取值

  • ACTIVE:  生效

  • DISABLED:  失效


 card_disabled_time  选填   string

【卡片失效时间】 卡片失效时间,当卡片不可用时存在此字段

格式要求:支付结束时间需遵循rfc3339标准格式:yyyy-MM-DDTHH:mm:ss+TIMEZONEyyyy-MM-DD 表示年月日;T 字符用于分隔日期和时间部分;HH:mm:ss 表示具体的时分秒;TIMEZONE 表示时区(例如,+08:00 对应东八区时间,即北京时间)。
示例:2015-05-20T13:29:35+08:00 表示北京时间2015年5月20日13点29分35秒。

应答示例

200 OK

1{
2  "sp_mchid" : "12341234",
3  "sub_mchid" : "43214321",
4  "employee_id" : "WeBizPay_a968402a-73bb-43e2-9e1a-8371b0ca3d7c",
5  "card_no" : "1068019671702503425",
6  "card_state" : "DISABLED",
7  "card_disabled_time" : "2023-12-31T23:59:59+08:00"
8}
9

 

错误码

公共错误码

状态码

错误码

描述

解决方案

400

PARAM_ERROR

参数错误

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

400

INVALID_REQUEST

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

请参阅 接口规则

401

SIGN_ERROR

验证不通过

请参阅 签名常见问题

500

SYSTEM_ERROR

系统异常,请稍后重试

请稍后重试

 

 

更多技术问题
技术咨询
反馈
咨询
目录
置顶