失效用户商品券组
更新时间:2025.11.20服务商可以通过本接口将用户商品券组内的所有商品券同步失效
前置条件:已经给用户发券成功,且商品券的 usage_mode 为 PROGRESSIVE_BUNDLE
接口说明
支持商户:【普通服务商】
请求方式:【POST】/v3/marketing/partner/product-coupon/users/{openid}/coupon-bundles/{user_coupon_bundle_id}/deactivate
请求域名:【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点
【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点 ,指引点击查看
接口限频:500/秒(商户号维度)
请求参数
Header HTTP头参数
Authorization 必填 string
请参考签名认证生成认证信息
Accept 必填 string
请设置为application/json
Content-Type 必填 string
请设置为application/json
path 路径参数
user_coupon_bundle_id 必填 string(40)
【用户券组ID】 用户券组的唯一标识,【向用户发放商品券批次组】时由微信支付生成,本接口会同步失效用户商品券组内所有用户商品券
openid 必填 string
【用户OpenID】 OpenID信息,用户在AppID下的唯一标识,获取方式参考OpenID
body 包体参数
product_coupon_id 必填 string
【商品券ID】 商品券的唯一标识,创建商品券时由微信支付生成
stock_bundle_id 必填 string
【批次组ID】 商品券批次组的唯一标识,【创建商品券(多次优惠)】或【添加商品券批次组】时由微信支付生成,请确保该批次组属于 product_coupon_id 对应的商品券
appid 必填 string
【公众账号ID】 公众账号ID也称AppID,是(微信开放平台、微信公众平台)为开发者提供的一个唯一标识,用于识别开发者的应用程序(APP、小程序、公众号)。 开发者需要先在微信开放平台或微信公众平台中申请ID,然后在服务商平台中绑定,详见服务商商户号与AppID账号关联管理。
out_request_no 必填 string(40)
【失效请求单号】 品牌失效用户商品券的请求流水号,品牌侧需保持唯一性,可使用 数字、大小写字母、下划线_、短横线- 组成,长度在6-40个字符之间
deactivate_reason 必填 string(150)
【失效原因】 记录用户商品券的失效原因,长度不超过150个UTF-8字符
brand_id 必填 string
【品牌ID】 微信支付为品牌方分配的唯一标识,该品牌应与服务商存在授权关系
请求示例
POST
1curl -X POST \ 2 https://api.mch.weixin.qq.com/v3/marketing/partner/product-coupon/users/oh-394z-6CGkNoJrsDLTTUKiAnp4/coupon-bundles/123446565767/deactivate \ 3 -H "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"1900000001\",..." \ 4 -H "Accept: application/json" \ 5 -H "Content-Type: application/json" \ 6 -d '{ 7 "product_coupon_id" : "1002323", 8 "stock_bundle_id" : "100232301", 9 "appid" : "wx233544546545989", 10 "out_request_no" : "1002600620019090123144054436", 11 "deactivate_reason" : "商品已下线,使用户商品券失效", 12 "brand_id" : "120344" 13 }' 14
需配合微信支付工具库 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 DeactivateUserProductCouponBundle { 26 private static String HOST = "https://api.mch.weixin.qq.com"; 27 private static String METHOD = "POST"; 28 private static String PATH = "/v3/marketing/partner/product-coupon/users/{openid}/coupon-bundles/{user_coupon_bundle_id}/deactivate"; 29 30 public static void main(String[] args) { 31 // TODO: 请准备商户开发必要参数,参考:https://pay.weixin.qq.com/doc/v3/partner/4013080340 32 DeactivateUserProductCouponBundle client = new DeactivateUserProductCouponBundle( 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 DeactivateUserProductCouponBundleRequest request = new DeactivateUserProductCouponBundleRequest(); 41 request.userCouponBundleId = "123446565767"; 42 request.openid = "oh-394z-6CGkNoJrsDLTTUKiAnp4"; 43 request.productCouponId = "1002323"; 44 request.stockBundleId = "100232301"; 45 request.appid = "wx233544546545989"; 46 request.outRequestNo = "1002600620019090123144054436"; 47 request.deactivateReason = "商品已下线,使用户商品券失效"; 48 request.brandId = "120344"; 49 try { 50 DeactivateUserProductCouponBundleResponse response = client.run(request); 51 // TODO: 请求成功,继续业务逻辑 52 System.out.println(response); 53 } catch (WXPayUtility.ApiException e) { 54 // TODO: 请求失败,根据状态码执行不同的逻辑 55 e.printStackTrace(); 56 } 57 } 58 59 public DeactivateUserProductCouponBundleResponse run(DeactivateUserProductCouponBundleRequest request) { 60 String uri = PATH; 61 uri = uri.replace("{user_coupon_bundle_id}", WXPayUtility.urlEncode(request.userCouponBundleId)); 62 uri = uri.replace("{openid}", WXPayUtility.urlEncode(request.openid)); 63 String reqBody = WXPayUtility.toJson(request); 64 65 Request.Builder reqBuilder = new Request.Builder().url(HOST + uri); 66 reqBuilder.addHeader("Accept", "application/json"); 67 reqBuilder.addHeader("Wechatpay-Serial", wechatPayPublicKeyId); 68 reqBuilder.addHeader("Authorization", WXPayUtility.buildAuthorization(mchid, certificateSerialNo,privateKey, METHOD, uri, reqBody)); 69 reqBuilder.addHeader("Content-Type", "application/json"); 70 RequestBody requestBody = RequestBody.create(MediaType.parse("application/json; charset=utf-8"), reqBody); 71 reqBuilder.method(METHOD, requestBody); 72 Request httpRequest = reqBuilder.build(); 73 74 // 发送HTTP请求 75 OkHttpClient client = new OkHttpClient.Builder().build(); 76 try (Response httpResponse = client.newCall(httpRequest).execute()) { 77 String respBody = WXPayUtility.extractBody(httpResponse); 78 if (httpResponse.code() >= 200 && httpResponse.code() < 300) { 79 // 2XX 成功,验证应答签名 80 WXPayUtility.validateResponse(this.wechatPayPublicKeyId, this.wechatPayPublicKey, 81 httpResponse.headers(), respBody); 82 83 // 从HTTP应答报文构建返回数据 84 return WXPayUtility.fromJson(respBody, DeactivateUserProductCouponBundleResponse.class); 85 } else { 86 throw new WXPayUtility.ApiException(httpResponse.code(), respBody, httpResponse.headers()); 87 } 88 } catch (IOException e) { 89 throw new UncheckedIOException("Sending request to " + uri + " failed.", e); 90 } 91 } 92 93 private final String mchid; 94 private final String certificateSerialNo; 95 private final PrivateKey privateKey; 96 private final String wechatPayPublicKeyId; 97 private final PublicKey wechatPayPublicKey; 98 99 public DeactivateUserProductCouponBundle(String mchid, String certificateSerialNo, String privateKeyFilePath, String wechatPayPublicKeyId, String wechatPayPublicKeyFilePath) { 100 this.mchid = mchid; 101 this.certificateSerialNo = certificateSerialNo; 102 this.privateKey = WXPayUtility.loadPrivateKeyFromPath(privateKeyFilePath); 103 this.wechatPayPublicKeyId = wechatPayPublicKeyId; 104 this.wechatPayPublicKey = WXPayUtility.loadPublicKeyFromPath(wechatPayPublicKeyFilePath); 105 } 106 107 public static class DeactivateUserProductCouponBundleRequest { 108 @SerializedName("product_coupon_id") 109 public String productCouponId; 110 111 @SerializedName("stock_bundle_id") 112 public String stockBundleId; 113 114 @SerializedName("user_coupon_bundle_id") 115 @Expose(serialize = false) 116 public String userCouponBundleId; 117 118 @SerializedName("appid") 119 public String appid; 120 121 @SerializedName("openid") 122 @Expose(serialize = false) 123 public String openid; 124 125 @SerializedName("out_request_no") 126 public String outRequestNo; 127 128 @SerializedName("deactivate_reason") 129 public String deactivateReason; 130 131 @SerializedName("brand_id") 132 public String brandId; 133 } 134 135 public static class DeactivateUserProductCouponBundleResponse { 136 @SerializedName("user_coupon_bundle_id") 137 public String userCouponBundleId; 138 139 @SerializedName("user_product_coupon_list") 140 public List<UserProductCouponEntity> userProductCouponList = new ArrayList<UserProductCouponEntity>(); 141 } 142 143 public static class UserProductCouponEntity { 144 @SerializedName("coupon_code") 145 public String couponCode; 146 147 @SerializedName("coupon_state") 148 public UserProductCouponState couponState; 149 150 @SerializedName("valid_begin_time") 151 public String validBeginTime; 152 153 @SerializedName("valid_end_time") 154 public String validEndTime; 155 156 @SerializedName("receive_time") 157 public String receiveTime; 158 159 @SerializedName("send_request_no") 160 public String sendRequestNo; 161 162 @SerializedName("send_channel") 163 public UserProductCouponSendChannel sendChannel; 164 165 @SerializedName("confirm_request_no") 166 public String confirmRequestNo; 167 168 @SerializedName("confirm_time") 169 public String confirmTime; 170 171 @SerializedName("deactivate_request_no") 172 public String deactivateRequestNo; 173 174 @SerializedName("deactivate_time") 175 public String deactivateTime; 176 177 @SerializedName("deactivate_reason") 178 public String deactivateReason; 179 180 @SerializedName("progressive_bundle_usage_detail") 181 public CouponUsageDetail progressiveBundleUsageDetail; 182 183 @SerializedName("user_product_coupon_bundle_info") 184 public UserProductCouponBundleInfo userProductCouponBundleInfo; 185 186 @SerializedName("product_coupon") 187 public ProductCouponEntity productCoupon; 188 189 @SerializedName("stock") 190 public StockEntity stock; 191 192 @SerializedName("attach") 193 public String attach; 194 195 @SerializedName("channel_custom_info") 196 public String channelCustomInfo; 197 198 @SerializedName("coupon_tag_info") 199 public CouponTagInfo couponTagInfo; 200 201 @SerializedName("brand_id") 202 public String brandId; 203 } 204 205 public enum UserProductCouponState { 206 @SerializedName("CONFIRMING") 207 CONFIRMING, 208 @SerializedName("PENDING") 209 PENDING, 210 @SerializedName("EFFECTIVE") 211 EFFECTIVE, 212 @SerializedName("USED") 213 USED, 214 @SerializedName("EXPIRED") 215 EXPIRED, 216 @SerializedName("DELETED") 217 DELETED, 218 @SerializedName("DEACTIVATED") 219 DEACTIVATED 220 } 221 222 public enum UserProductCouponSendChannel { 223 @SerializedName("BRAND_MANAGE") 224 BRAND_MANAGE, 225 @SerializedName("API") 226 API, 227 @SerializedName("RECEIVE_COMPONENT") 228 RECEIVE_COMPONENT 229 } 230 231 public static class CouponUsageDetail { 232 @SerializedName("use_request_no") 233 public String useRequestNo; 234 235 @SerializedName("use_time") 236 public String useTime; 237 238 @SerializedName("return_request_no") 239 public String returnRequestNo; 240 241 @SerializedName("return_time") 242 public String returnTime; 243 244 @SerializedName("associated_order_info") 245 public UserProductCouponAssociatedOrderInfo associatedOrderInfo; 246 247 @SerializedName("associated_pay_score_order_info") 248 public UserProductCouponAssociatedPayScoreOrderInfo associatedPayScoreOrderInfo; 249 250 @SerializedName("saved_amount") 251 public Long savedAmount; 252 } 253 254 public static class UserProductCouponBundleInfo { 255 @SerializedName("user_coupon_bundle_id") 256 public String userCouponBundleId; 257 258 @SerializedName("user_coupon_bundle_index") 259 public Long userCouponBundleIndex; 260 261 @SerializedName("total_count") 262 public Long totalCount; 263 264 @SerializedName("used_count") 265 public Long usedCount; 266 } 267 268 public static class ProductCouponEntity { 269 @SerializedName("product_coupon_id") 270 public String productCouponId; 271 272 @SerializedName("scope") 273 public ProductCouponScope scope; 274 275 @SerializedName("type") 276 public ProductCouponType type; 277 278 @SerializedName("usage_mode") 279 public UsageMode usageMode; 280 281 @SerializedName("single_usage_info") 282 public SingleUsageInfo singleUsageInfo; 283 284 @SerializedName("progressive_bundle_usage_info") 285 public ProgressiveBundleUsageInfo progressiveBundleUsageInfo; 286 287 @SerializedName("display_info") 288 public ProductCouponDisplayInfo displayInfo; 289 290 @SerializedName("out_product_no") 291 public String outProductNo; 292 293 @SerializedName("state") 294 public ProductCouponState state; 295 296 @SerializedName("deactivate_request_no") 297 public String deactivateRequestNo; 298 299 @SerializedName("deactivate_time") 300 public String deactivateTime; 301 302 @SerializedName("deactivate_reason") 303 public String deactivateReason; 304 305 @SerializedName("brand_id") 306 public String brandId; 307 } 308 309 public static class StockEntity { 310 @SerializedName("product_coupon_id") 311 public String productCouponId; 312 313 @SerializedName("stock_id") 314 public String stockId; 315 316 @SerializedName("remark") 317 public String remark; 318 319 @SerializedName("coupon_code_mode") 320 public CouponCodeMode couponCodeMode; 321 322 @SerializedName("coupon_code_count_info") 323 public CouponCodeCountInfo couponCodeCountInfo; 324 325 @SerializedName("stock_send_rule") 326 public StockSendRule stockSendRule; 327 328 @SerializedName("progressive_bundle_usage_rule") 329 public StockUsageRule progressiveBundleUsageRule; 330 331 @SerializedName("stock_bundle_info") 332 public StockBundleInfo stockBundleInfo; 333 334 @SerializedName("usage_rule_display_info") 335 public UsageRuleDisplayInfo usageRuleDisplayInfo; 336 337 @SerializedName("coupon_display_info") 338 public CouponDisplayInfo couponDisplayInfo; 339 340 @SerializedName("notify_config") 341 public NotifyConfig notifyConfig; 342 343 @SerializedName("store_scope") 344 public StockStoreScope storeScope; 345 346 @SerializedName("sent_count_info") 347 public StockSentCountInfo sentCountInfo; 348 349 @SerializedName("state") 350 public StockState state; 351 352 @SerializedName("deactivate_request_no") 353 public String deactivateRequestNo; 354 355 @SerializedName("deactivate_time") 356 public String deactivateTime; 357 358 @SerializedName("deactivate_reason") 359 public String deactivateReason; 360 361 @SerializedName("brand_id") 362 public String brandId; 363 } 364 365 public static class CouponTagInfo { 366 @SerializedName("coupon_tag_list") 367 public List<UserProductCouponTag> couponTagList; 368 369 @SerializedName("member_tag_info") 370 public MemberTagInfo memberTagInfo; 371 } 372 373 public static class UserProductCouponAssociatedOrderInfo { 374 @SerializedName("transaction_id") 375 public String transactionId; 376 377 @SerializedName("out_trade_no") 378 public String outTradeNo; 379 380 @SerializedName("mchid") 381 public String mchid; 382 383 @SerializedName("sub_mchid") 384 public String subMchid; 385 } 386 387 public static class UserProductCouponAssociatedPayScoreOrderInfo { 388 @SerializedName("order_id") 389 public String orderId; 390 391 @SerializedName("out_order_no") 392 public String outOrderNo; 393 394 @SerializedName("mchid") 395 public String mchid; 396 397 @SerializedName("sub_mchid") 398 public String subMchid; 399 } 400 401 public enum ProductCouponScope { 402 @SerializedName("ALL") 403 ALL, 404 @SerializedName("SINGLE") 405 SINGLE 406 } 407 408 public enum ProductCouponType { 409 @SerializedName("NORMAL") 410 NORMAL, 411 @SerializedName("DISCOUNT") 412 DISCOUNT, 413 @SerializedName("EXCHANGE") 414 EXCHANGE 415 } 416 417 public enum UsageMode { 418 @SerializedName("SINGLE") 419 SINGLE, 420 @SerializedName("PROGRESSIVE_BUNDLE") 421 PROGRESSIVE_BUNDLE 422 } 423 424 public static class SingleUsageInfo { 425 @SerializedName("normal_coupon") 426 public NormalCouponUsageRule normalCoupon; 427 428 @SerializedName("discount_coupon") 429 public DiscountCouponUsageRule discountCoupon; 430 } 431 432 public static class ProgressiveBundleUsageInfo { 433 @SerializedName("count") 434 public Long count; 435 436 @SerializedName("interval_days") 437 public Long intervalDays; 438 } 439 440 public static class ProductCouponDisplayInfo { 441 @SerializedName("name") 442 public String name; 443 444 @SerializedName("image_url") 445 public String imageUrl; 446 447 @SerializedName("background_url") 448 public String backgroundUrl; 449 450 @SerializedName("detail_image_url_list") 451 public List<String> detailImageUrlList; 452 453 @SerializedName("original_price") 454 public Long originalPrice; 455 456 @SerializedName("combo_package_list") 457 public List<ComboPackage> comboPackageList; 458 } 459 460 public enum ProductCouponState { 461 @SerializedName("AUDITING") 462 AUDITING, 463 @SerializedName("EFFECTIVE") 464 EFFECTIVE, 465 @SerializedName("DEACTIVATED") 466 DEACTIVATED 467 } 468 469 public enum CouponCodeMode { 470 @SerializedName("WECHATPAY") 471 WECHATPAY, 472 @SerializedName("UPLOAD") 473 UPLOAD 474 } 475 476 public static class CouponCodeCountInfo { 477 @SerializedName("total_count") 478 public Long totalCount; 479 480 @SerializedName("available_count") 481 public Long availableCount; 482 } 483 484 public static class StockSendRule { 485 @SerializedName("max_count") 486 public Long maxCount; 487 488 @SerializedName("max_count_per_day") 489 public Long maxCountPerDay; 490 491 @SerializedName("max_count_per_user") 492 public Long maxCountPerUser; 493 } 494 495 public static class StockUsageRule { 496 @SerializedName("coupon_available_period") 497 public CouponAvailablePeriod couponAvailablePeriod; 498 499 @SerializedName("normal_coupon") 500 public NormalCouponUsageRule normalCoupon; 501 502 @SerializedName("discount_coupon") 503 public DiscountCouponUsageRule discountCoupon; 504 505 @SerializedName("exchange_coupon") 506 public ExchangeCouponUsageRule exchangeCoupon; 507 } 508 509 public static class StockBundleInfo { 510 @SerializedName("stock_bundle_id") 511 public String stockBundleId; 512 513 @SerializedName("stock_bundle_index") 514 public Long stockBundleIndex; 515 } 516 517 public static class UsageRuleDisplayInfo { 518 @SerializedName("coupon_usage_method_list") 519 public List<CouponUsageMethod> couponUsageMethodList = new ArrayList<CouponUsageMethod>(); 520 521 @SerializedName("mini_program_appid") 522 public String miniProgramAppid; 523 524 @SerializedName("mini_program_path") 525 public String miniProgramPath; 526 527 @SerializedName("app_path") 528 public String appPath; 529 530 @SerializedName("usage_description") 531 public String usageDescription; 532 533 @SerializedName("coupon_available_store_info") 534 public CouponAvailableStoreInfo couponAvailableStoreInfo; 535 } 536 537 public static class CouponDisplayInfo { 538 @SerializedName("code_display_mode") 539 public CouponCodeDisplayMode codeDisplayMode; 540 541 @SerializedName("background_color") 542 public String backgroundColor; 543 544 @SerializedName("entrance_mini_program") 545 public EntranceMiniProgram entranceMiniProgram; 546 547 @SerializedName("entrance_official_account") 548 public EntranceOfficialAccount entranceOfficialAccount; 549 550 @SerializedName("entrance_finder") 551 public EntranceFinder entranceFinder; 552 } 553 554 public static class NotifyConfig { 555 @SerializedName("notify_appid") 556 public String notifyAppid; 557 } 558 559 public enum StockStoreScope { 560 @SerializedName("NONE") 561 NONE, 562 @SerializedName("ALL") 563 ALL, 564 @SerializedName("SPECIFIC") 565 SPECIFIC 566 } 567 568 public static class StockSentCountInfo { 569 @SerializedName("total_count") 570 public Long totalCount; 571 572 @SerializedName("today_count") 573 public Long todayCount; 574 } 575 576 public enum StockState { 577 @SerializedName("AUDITING") 578 AUDITING, 579 @SerializedName("SENDING") 580 SENDING, 581 @SerializedName("PAUSED") 582 PAUSED, 583 @SerializedName("STOPPED") 584 STOPPED, 585 @SerializedName("DEACTIVATED") 586 DEACTIVATED 587 } 588 589 public enum UserProductCouponTag { 590 @SerializedName("MEMBER") 591 MEMBER 592 } 593 594 public static class MemberTagInfo { 595 @SerializedName("member_card_id") 596 public String memberCardId; 597 } 598 599 public static class NormalCouponUsageRule { 600 @SerializedName("threshold") 601 public Long threshold; 602 603 @SerializedName("discount_amount") 604 public Long discountAmount; 605 } 606 607 public static class DiscountCouponUsageRule { 608 @SerializedName("threshold") 609 public Long threshold; 610 611 @SerializedName("percent_off") 612 public Long percentOff; 613 } 614 615 public static class ComboPackage { 616 @SerializedName("name") 617 public String name; 618 619 @SerializedName("pick_count") 620 public Long pickCount; 621 622 @SerializedName("choice_list") 623 public List<ComboPackageChoice> choiceList = new ArrayList<ComboPackageChoice>(); 624 } 625 626 public static class CouponAvailablePeriod { 627 @SerializedName("available_begin_time") 628 public String availableBeginTime; 629 630 @SerializedName("available_end_time") 631 public String availableEndTime; 632 633 @SerializedName("available_days") 634 public Long availableDays; 635 636 @SerializedName("wait_days_after_receive") 637 public Long waitDaysAfterReceive; 638 639 @SerializedName("weekly_available_period") 640 public FixedWeekPeriod weeklyAvailablePeriod; 641 642 @SerializedName("irregular_available_period_list") 643 public List<TimePeriod> irregularAvailablePeriodList; 644 } 645 646 public static class ExchangeCouponUsageRule { 647 @SerializedName("threshold") 648 public Long threshold; 649 650 @SerializedName("exchange_price") 651 public Long exchangePrice; 652 } 653 654 public enum CouponUsageMethod { 655 @SerializedName("OFFLINE") 656 OFFLINE, 657 @SerializedName("MINI_PROGRAM") 658 MINI_PROGRAM, 659 @SerializedName("APP") 660 APP, 661 @SerializedName("PAYMENT_CODE") 662 PAYMENT_CODE 663 } 664 665 public static class CouponAvailableStoreInfo { 666 @SerializedName("description") 667 public String description; 668 669 @SerializedName("mini_program_appid") 670 public String miniProgramAppid; 671 672 @SerializedName("mini_program_path") 673 public String miniProgramPath; 674 } 675 676 public enum CouponCodeDisplayMode { 677 @SerializedName("INVISIBLE") 678 INVISIBLE, 679 @SerializedName("BARCODE") 680 BARCODE, 681 @SerializedName("QRCODE") 682 QRCODE 683 } 684 685 public static class EntranceMiniProgram { 686 @SerializedName("appid") 687 public String appid; 688 689 @SerializedName("path") 690 public String path; 691 692 @SerializedName("entrance_wording") 693 public String entranceWording; 694 695 @SerializedName("guidance_wording") 696 public String guidanceWording; 697 } 698 699 public static class EntranceOfficialAccount { 700 @SerializedName("appid") 701 public String appid; 702 } 703 704 public static class EntranceFinder { 705 @SerializedName("finder_id") 706 public String finderId; 707 708 @SerializedName("finder_video_id") 709 public String finderVideoId; 710 711 @SerializedName("finder_video_cover_image_url") 712 public String finderVideoCoverImageUrl; 713 } 714 715 public static class ComboPackageChoice { 716 @SerializedName("name") 717 public String name; 718 719 @SerializedName("price") 720 public Long price; 721 722 @SerializedName("count") 723 public Long count; 724 725 @SerializedName("image_url") 726 public String imageUrl; 727 728 @SerializedName("mini_program_appid") 729 public String miniProgramAppid; 730 731 @SerializedName("mini_program_path") 732 public String miniProgramPath; 733 } 734 735 public static class FixedWeekPeriod { 736 @SerializedName("day_list") 737 public List<WeekEnum> dayList = new ArrayList<WeekEnum>(); 738 739 @SerializedName("day_period_list") 740 public List<PeriodOfTheDay> dayPeriodList; 741 } 742 743 public static class TimePeriod { 744 @SerializedName("begin_time") 745 public String beginTime; 746 747 @SerializedName("end_time") 748 public String endTime; 749 } 750 751 public enum WeekEnum { 752 @SerializedName("MONDAY") 753 MONDAY, 754 @SerializedName("TUESDAY") 755 TUESDAY, 756 @SerializedName("WEDNESDAY") 757 WEDNESDAY, 758 @SerializedName("THURSDAY") 759 THURSDAY, 760 @SerializedName("FRIDAY") 761 FRIDAY, 762 @SerializedName("SATURDAY") 763 SATURDAY, 764 @SerializedName("SUNDAY") 765 SUNDAY 766 } 767 768 public static class PeriodOfTheDay { 769 @SerializedName("begin_time") 770 public Long beginTime; 771 772 @SerializedName("end_time") 773 public Long endTime; 774 } 775 776} 777
需配合微信支付工具库 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 "strings" 11 "time" 12) 13 14func main() { 15 // TODO: 请准备商户开发必要参数,参考:https://pay.weixin.qq.com/doc/v3/partner/4013080340 16 config, err := wxpay_utility.CreateMchConfig( 17 "19xxxxxxxx", // 商户号,是由微信支付系统生成并分配给每个商户的唯一标识符,商户号获取方式参考 https://pay.weixin.qq.com/doc/v3/partner/4013080340 18 "1DDE55AD98Exxxxxxxxxx", // 商户API证书序列号,如何获取请参考 https://pay.weixin.qq.com/doc/v3/partner/4013058924 19 "/path/to/apiclient_key.pem", // 商户API证书私钥文件路径,本地文件路径 20 "PUB_KEY_ID_xxxxxxxxxxxxx", // 微信支付公钥ID,如何获取请参考 https://pay.weixin.qq.com/doc/v3/partner/4013038589 21 "/path/to/wxp_pub.pem", // 微信支付公钥文件路径,本地文件路径 22 ) 23 if err != nil { 24 fmt.Println(err) 25 return 26 } 27 28 request := &DeactivateUserProductCouponBundleRequest{ 29 UserCouponBundleId: wxpay_utility.String("123446565767"), 30 Openid: wxpay_utility.String("oh-394z-6CGkNoJrsDLTTUKiAnp4"), 31 ProductCouponId: wxpay_utility.String("1002323"), 32 StockBundleId: wxpay_utility.String("100232301"), 33 Appid: wxpay_utility.String("wx233544546545989"), 34 OutRequestNo: wxpay_utility.String("1002600620019090123144054436"), 35 DeactivateReason: wxpay_utility.String("商品已下线,使用户商品券失效"), 36 BrandId: wxpay_utility.String("120344"), 37 } 38 39 response, err := DeactivateUserProductCouponBundle(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 DeactivateUserProductCouponBundle(config *wxpay_utility.MchConfig, request *DeactivateUserProductCouponBundleRequest) (response *DeactivateUserProductCouponBundleResponse, err error) { 51 const ( 52 host = "https://api.mch.weixin.qq.com" 53 method = "POST" 54 path = "/v3/marketing/partner/product-coupon/users/{openid}/coupon-bundles/{user_coupon_bundle_id}/deactivate" 55 ) 56 57 reqUrl, err := url.Parse(fmt.Sprintf("%s%s", host, path)) 58 if err != nil { 59 return nil, err 60 } 61 reqUrl.Path = strings.Replace(reqUrl.Path, "{user_coupon_bundle_id}", url.PathEscape(*request.UserCouponBundleId), -1) 62 reqUrl.Path = strings.Replace(reqUrl.Path, "{openid}", url.PathEscape(*request.Openid), -1) 63 reqBody, err := json.Marshal(request) 64 if err != nil { 65 return nil, err 66 } 67 httpRequest, err := http.NewRequest(method, reqUrl.String(), bytes.NewReader(reqBody)) 68 if err != nil { 69 return nil, err 70 } 71 httpRequest.Header.Set("Accept", "application/json") 72 httpRequest.Header.Set("Wechatpay-Serial", config.WechatPayPublicKeyId()) 73 httpRequest.Header.Set("Content-Type", "application/json") 74 authorization, err := wxpay_utility.BuildAuthorization(config.MchId(), config.CertificateSerialNo(), config.PrivateKey(), method, reqUrl.RequestURI(), reqBody) 75 if err != nil { 76 return nil, err 77 } 78 httpRequest.Header.Set("Authorization", authorization) 79 80 client := &http.Client{} 81 httpResponse, err := client.Do(httpRequest) 82 if err != nil { 83 return nil, err 84 } 85 respBody, err := wxpay_utility.ExtractResponseBody(httpResponse) 86 if err != nil { 87 return nil, err 88 } 89 if httpResponse.StatusCode >= 200 && httpResponse.StatusCode < 300 { 90 // 2XX 成功,验证应答签名 91 err = wxpay_utility.ValidateResponse( 92 config.WechatPayPublicKeyId(), 93 config.WechatPayPublicKey(), 94 &httpResponse.Header, 95 respBody, 96 ) 97 if err != nil { 98 return nil, err 99 } 100 response := &DeactivateUserProductCouponBundleResponse{} 101 if err := json.Unmarshal(respBody, response); err != nil { 102 return nil, err 103 } 104 105 return response, nil 106 } else { 107 return nil, wxpay_utility.NewApiException( 108 httpResponse.StatusCode, 109 httpResponse.Header, 110 respBody, 111 ) 112 } 113} 114 115type DeactivateUserProductCouponBundleRequest struct { 116 ProductCouponId *string `json:"product_coupon_id,omitempty"` 117 StockBundleId *string `json:"stock_bundle_id,omitempty"` 118 UserCouponBundleId *string `json:"user_coupon_bundle_id,omitempty"` 119 Appid *string `json:"appid,omitempty"` 120 Openid *string `json:"openid,omitempty"` 121 OutRequestNo *string `json:"out_request_no,omitempty"` 122 DeactivateReason *string `json:"deactivate_reason,omitempty"` 123 BrandId *string `json:"brand_id,omitempty"` 124} 125 126func (o *DeactivateUserProductCouponBundleRequest) MarshalJSON() ([]byte, error) { 127 type Alias DeactivateUserProductCouponBundleRequest 128 a := &struct { 129 UserCouponBundleId *string `json:"user_coupon_bundle_id,omitempty"` 130 Openid *string `json:"openid,omitempty"` 131 *Alias 132 }{ 133 // 序列化时移除非 Body 字段 134 UserCouponBundleId: nil, 135 Openid: nil, 136 Alias: (*Alias)(o), 137 } 138 return json.Marshal(a) 139} 140 141type DeactivateUserProductCouponBundleResponse struct { 142 UserCouponBundleId *string `json:"user_coupon_bundle_id,omitempty"` 143 UserProductCouponList []UserProductCouponEntity `json:"user_product_coupon_list,omitempty"` 144} 145 146type UserProductCouponEntity struct { 147 CouponCode *string `json:"coupon_code,omitempty"` 148 CouponState *UserProductCouponState `json:"coupon_state,omitempty"` 149 ValidBeginTime *time.Time `json:"valid_begin_time,omitempty"` 150 ValidEndTime *time.Time `json:"valid_end_time,omitempty"` 151 ReceiveTime *string `json:"receive_time,omitempty"` 152 SendRequestNo *string `json:"send_request_no,omitempty"` 153 SendChannel *UserProductCouponSendChannel `json:"send_channel,omitempty"` 154 ConfirmRequestNo *string `json:"confirm_request_no,omitempty"` 155 ConfirmTime *time.Time `json:"confirm_time,omitempty"` 156 DeactivateRequestNo *string `json:"deactivate_request_no,omitempty"` 157 DeactivateTime *string `json:"deactivate_time,omitempty"` 158 DeactivateReason *string `json:"deactivate_reason,omitempty"` 159 ProgressiveBundleUsageDetail *CouponUsageDetail `json:"progressive_bundle_usage_detail,omitempty"` 160 UserProductCouponBundleInfo *UserProductCouponBundleInfo `json:"user_product_coupon_bundle_info,omitempty"` 161 ProductCoupon *ProductCouponEntity `json:"product_coupon,omitempty"` 162 Stock *StockEntity `json:"stock,omitempty"` 163 Attach *string `json:"attach,omitempty"` 164 ChannelCustomInfo *string `json:"channel_custom_info,omitempty"` 165 CouponTagInfo *CouponTagInfo `json:"coupon_tag_info,omitempty"` 166 BrandId *string `json:"brand_id,omitempty"` 167} 168 169type UserProductCouponState string 170 171func (e UserProductCouponState) Ptr() *UserProductCouponState { 172 return &e 173} 174 175const ( 176 USERPRODUCTCOUPONSTATE_CONFIRMING UserProductCouponState = "CONFIRMING" 177 USERPRODUCTCOUPONSTATE_PENDING UserProductCouponState = "PENDING" 178 USERPRODUCTCOUPONSTATE_EFFECTIVE UserProductCouponState = "EFFECTIVE" 179 USERPRODUCTCOUPONSTATE_USED UserProductCouponState = "USED" 180 USERPRODUCTCOUPONSTATE_EXPIRED UserProductCouponState = "EXPIRED" 181 USERPRODUCTCOUPONSTATE_DELETED UserProductCouponState = "DELETED" 182 USERPRODUCTCOUPONSTATE_DEACTIVATED UserProductCouponState = "DEACTIVATED" 183) 184 185type UserProductCouponSendChannel string 186 187func (e UserProductCouponSendChannel) Ptr() *UserProductCouponSendChannel { 188 return &e 189} 190 191const ( 192 USERPRODUCTCOUPONSENDCHANNEL_BRAND_MANAGE UserProductCouponSendChannel = "BRAND_MANAGE" 193 USERPRODUCTCOUPONSENDCHANNEL_API UserProductCouponSendChannel = "API" 194 USERPRODUCTCOUPONSENDCHANNEL_RECEIVE_COMPONENT UserProductCouponSendChannel = "RECEIVE_COMPONENT" 195) 196 197type CouponUsageDetail struct { 198 UseRequestNo *string `json:"use_request_no,omitempty"` 199 UseTime *time.Time `json:"use_time,omitempty"` 200 ReturnRequestNo *string `json:"return_request_no,omitempty"` 201 ReturnTime *time.Time `json:"return_time,omitempty"` 202 AssociatedOrderInfo *UserProductCouponAssociatedOrderInfo `json:"associated_order_info,omitempty"` 203 AssociatedPayScoreOrderInfo *UserProductCouponAssociatedPayScoreOrderInfo `json:"associated_pay_score_order_info,omitempty"` 204 SavedAmount *int64 `json:"saved_amount,omitempty"` 205} 206 207type UserProductCouponBundleInfo struct { 208 UserCouponBundleId *string `json:"user_coupon_bundle_id,omitempty"` 209 UserCouponBundleIndex *int64 `json:"user_coupon_bundle_index,omitempty"` 210 TotalCount *int64 `json:"total_count,omitempty"` 211 UsedCount *int64 `json:"used_count,omitempty"` 212} 213 214type ProductCouponEntity struct { 215 ProductCouponId *string `json:"product_coupon_id,omitempty"` 216 Scope *ProductCouponScope `json:"scope,omitempty"` 217 Type *ProductCouponType `json:"type,omitempty"` 218 UsageMode *UsageMode `json:"usage_mode,omitempty"` 219 SingleUsageInfo *SingleUsageInfo `json:"single_usage_info,omitempty"` 220 ProgressiveBundleUsageInfo *ProgressiveBundleUsageInfo `json:"progressive_bundle_usage_info,omitempty"` 221 DisplayInfo *ProductCouponDisplayInfo `json:"display_info,omitempty"` 222 OutProductNo *string `json:"out_product_no,omitempty"` 223 State *ProductCouponState `json:"state,omitempty"` 224 DeactivateRequestNo *string `json:"deactivate_request_no,omitempty"` 225 DeactivateTime *string `json:"deactivate_time,omitempty"` 226 DeactivateReason *string `json:"deactivate_reason,omitempty"` 227 BrandId *string `json:"brand_id,omitempty"` 228} 229 230type StockEntity struct { 231 ProductCouponId *string `json:"product_coupon_id,omitempty"` 232 StockId *string `json:"stock_id,omitempty"` 233 Remark *string `json:"remark,omitempty"` 234 CouponCodeMode *CouponCodeMode `json:"coupon_code_mode,omitempty"` 235 CouponCodeCountInfo *CouponCodeCountInfo `json:"coupon_code_count_info,omitempty"` 236 StockSendRule *StockSendRule `json:"stock_send_rule,omitempty"` 237 ProgressiveBundleUsageRule *StockUsageRule `json:"progressive_bundle_usage_rule,omitempty"` 238 StockBundleInfo *StockBundleInfo `json:"stock_bundle_info,omitempty"` 239 UsageRuleDisplayInfo *UsageRuleDisplayInfo `json:"usage_rule_display_info,omitempty"` 240 CouponDisplayInfo *CouponDisplayInfo `json:"coupon_display_info,omitempty"` 241 NotifyConfig *NotifyConfig `json:"notify_config,omitempty"` 242 StoreScope *StockStoreScope `json:"store_scope,omitempty"` 243 SentCountInfo *StockSentCountInfo `json:"sent_count_info,omitempty"` 244 State *StockState `json:"state,omitempty"` 245 DeactivateRequestNo *string `json:"deactivate_request_no,omitempty"` 246 DeactivateTime *time.Time `json:"deactivate_time,omitempty"` 247 DeactivateReason *string `json:"deactivate_reason,omitempty"` 248 BrandId *string `json:"brand_id,omitempty"` 249} 250 251type CouponTagInfo struct { 252 CouponTagList []UserProductCouponTag `json:"coupon_tag_list,omitempty"` 253 MemberTagInfo *MemberTagInfo `json:"member_tag_info,omitempty"` 254} 255 256type UserProductCouponAssociatedOrderInfo struct { 257 TransactionId *string `json:"transaction_id,omitempty"` 258 OutTradeNo *string `json:"out_trade_no,omitempty"` 259 Mchid *string `json:"mchid,omitempty"` 260 SubMchid *string `json:"sub_mchid,omitempty"` 261} 262 263type UserProductCouponAssociatedPayScoreOrderInfo struct { 264 OrderId *string `json:"order_id,omitempty"` 265 OutOrderNo *string `json:"out_order_no,omitempty"` 266 Mchid *string `json:"mchid,omitempty"` 267 SubMchid *string `json:"sub_mchid,omitempty"` 268} 269 270type ProductCouponScope string 271 272func (e ProductCouponScope) Ptr() *ProductCouponScope { 273 return &e 274} 275 276const ( 277 PRODUCTCOUPONSCOPE_ALL ProductCouponScope = "ALL" 278 PRODUCTCOUPONSCOPE_SINGLE ProductCouponScope = "SINGLE" 279) 280 281type ProductCouponType string 282 283func (e ProductCouponType) Ptr() *ProductCouponType { 284 return &e 285} 286 287const ( 288 PRODUCTCOUPONTYPE_NORMAL ProductCouponType = "NORMAL" 289 PRODUCTCOUPONTYPE_DISCOUNT ProductCouponType = "DISCOUNT" 290 PRODUCTCOUPONTYPE_EXCHANGE ProductCouponType = "EXCHANGE" 291) 292 293type UsageMode string 294 295func (e UsageMode) Ptr() *UsageMode { 296 return &e 297} 298 299const ( 300 USAGEMODE_SINGLE UsageMode = "SINGLE" 301 USAGEMODE_PROGRESSIVE_BUNDLE UsageMode = "PROGRESSIVE_BUNDLE" 302) 303 304type SingleUsageInfo struct { 305 NormalCoupon *NormalCouponUsageRule `json:"normal_coupon,omitempty"` 306 DiscountCoupon *DiscountCouponUsageRule `json:"discount_coupon,omitempty"` 307} 308 309type ProgressiveBundleUsageInfo struct { 310 Count *int64 `json:"count,omitempty"` 311 IntervalDays *int64 `json:"interval_days,omitempty"` 312} 313 314type ProductCouponDisplayInfo struct { 315 Name *string `json:"name,omitempty"` 316 ImageUrl *string `json:"image_url,omitempty"` 317 BackgroundUrl *string `json:"background_url,omitempty"` 318 DetailImageUrlList []string `json:"detail_image_url_list,omitempty"` 319 OriginalPrice *int64 `json:"original_price,omitempty"` 320 ComboPackageList []ComboPackage `json:"combo_package_list,omitempty"` 321} 322 323type ProductCouponState string 324 325func (e ProductCouponState) Ptr() *ProductCouponState { 326 return &e 327} 328 329const ( 330 PRODUCTCOUPONSTATE_AUDITING ProductCouponState = "AUDITING" 331 PRODUCTCOUPONSTATE_EFFECTIVE ProductCouponState = "EFFECTIVE" 332 PRODUCTCOUPONSTATE_DEACTIVATED ProductCouponState = "DEACTIVATED" 333) 334 335type CouponCodeMode string 336 337func (e CouponCodeMode) Ptr() *CouponCodeMode { 338 return &e 339} 340 341const ( 342 COUPONCODEMODE_WECHATPAY CouponCodeMode = "WECHATPAY" 343 COUPONCODEMODE_UPLOAD CouponCodeMode = "UPLOAD" 344) 345 346type CouponCodeCountInfo struct { 347 TotalCount *int64 `json:"total_count,omitempty"` 348 AvailableCount *int64 `json:"available_count,omitempty"` 349} 350 351type StockSendRule struct { 352 MaxCount *int64 `json:"max_count,omitempty"` 353 MaxCountPerDay *int64 `json:"max_count_per_day,omitempty"` 354 MaxCountPerUser *int64 `json:"max_count_per_user,omitempty"` 355} 356 357type StockUsageRule struct { 358 CouponAvailablePeriod *CouponAvailablePeriod `json:"coupon_available_period,omitempty"` 359 NormalCoupon *NormalCouponUsageRule `json:"normal_coupon,omitempty"` 360 DiscountCoupon *DiscountCouponUsageRule `json:"discount_coupon,omitempty"` 361 ExchangeCoupon *ExchangeCouponUsageRule `json:"exchange_coupon,omitempty"` 362} 363 364type StockBundleInfo struct { 365 StockBundleId *string `json:"stock_bundle_id,omitempty"` 366 StockBundleIndex *int64 `json:"stock_bundle_index,omitempty"` 367} 368 369type UsageRuleDisplayInfo struct { 370 CouponUsageMethodList []CouponUsageMethod `json:"coupon_usage_method_list,omitempty"` 371 MiniProgramAppid *string `json:"mini_program_appid,omitempty"` 372 MiniProgramPath *string `json:"mini_program_path,omitempty"` 373 AppPath *string `json:"app_path,omitempty"` 374 UsageDescription *string `json:"usage_description,omitempty"` 375 CouponAvailableStoreInfo *CouponAvailableStoreInfo `json:"coupon_available_store_info,omitempty"` 376} 377 378type CouponDisplayInfo struct { 379 CodeDisplayMode *CouponCodeDisplayMode `json:"code_display_mode,omitempty"` 380 BackgroundColor *string `json:"background_color,omitempty"` 381 EntranceMiniProgram *EntranceMiniProgram `json:"entrance_mini_program,omitempty"` 382 EntranceOfficialAccount *EntranceOfficialAccount `json:"entrance_official_account,omitempty"` 383 EntranceFinder *EntranceFinder `json:"entrance_finder,omitempty"` 384} 385 386type NotifyConfig struct { 387 NotifyAppid *string `json:"notify_appid,omitempty"` 388} 389 390type StockStoreScope string 391 392func (e StockStoreScope) Ptr() *StockStoreScope { 393 return &e 394} 395 396const ( 397 STOCKSTORESCOPE_NONE StockStoreScope = "NONE" 398 STOCKSTORESCOPE_ALL StockStoreScope = "ALL" 399 STOCKSTORESCOPE_SPECIFIC StockStoreScope = "SPECIFIC" 400) 401 402type StockSentCountInfo struct { 403 TotalCount *int64 `json:"total_count,omitempty"` 404 TodayCount *int64 `json:"today_count,omitempty"` 405} 406 407type StockState string 408 409func (e StockState) Ptr() *StockState { 410 return &e 411} 412 413const ( 414 STOCKSTATE_AUDITING StockState = "AUDITING" 415 STOCKSTATE_SENDING StockState = "SENDING" 416 STOCKSTATE_PAUSED StockState = "PAUSED" 417 STOCKSTATE_STOPPED StockState = "STOPPED" 418 STOCKSTATE_DEACTIVATED StockState = "DEACTIVATED" 419) 420 421type UserProductCouponTag string 422 423func (e UserProductCouponTag) Ptr() *UserProductCouponTag { 424 return &e 425} 426 427const ( 428 USERPRODUCTCOUPONTAG_MEMBER UserProductCouponTag = "MEMBER" 429) 430 431type MemberTagInfo struct { 432 MemberCardId *string `json:"member_card_id,omitempty"` 433} 434 435type NormalCouponUsageRule struct { 436 Threshold *int64 `json:"threshold,omitempty"` 437 DiscountAmount *int64 `json:"discount_amount,omitempty"` 438} 439 440type DiscountCouponUsageRule struct { 441 Threshold *int64 `json:"threshold,omitempty"` 442 PercentOff *int64 `json:"percent_off,omitempty"` 443} 444 445type ComboPackage struct { 446 Name *string `json:"name,omitempty"` 447 PickCount *int64 `json:"pick_count,omitempty"` 448 ChoiceList []ComboPackageChoice `json:"choice_list,omitempty"` 449} 450 451type CouponAvailablePeriod struct { 452 AvailableBeginTime *string `json:"available_begin_time,omitempty"` 453 AvailableEndTime *string `json:"available_end_time,omitempty"` 454 AvailableDays *int64 `json:"available_days,omitempty"` 455 WaitDaysAfterReceive *int64 `json:"wait_days_after_receive,omitempty"` 456 WeeklyAvailablePeriod *FixedWeekPeriod `json:"weekly_available_period,omitempty"` 457 IrregularAvailablePeriodList []TimePeriod `json:"irregular_available_period_list,omitempty"` 458} 459 460type ExchangeCouponUsageRule struct { 461 Threshold *int64 `json:"threshold,omitempty"` 462 ExchangePrice *int64 `json:"exchange_price,omitempty"` 463} 464 465type CouponUsageMethod string 466 467func (e CouponUsageMethod) Ptr() *CouponUsageMethod { 468 return &e 469} 470 471const ( 472 COUPONUSAGEMETHOD_OFFLINE CouponUsageMethod = "OFFLINE" 473 COUPONUSAGEMETHOD_MINI_PROGRAM CouponUsageMethod = "MINI_PROGRAM" 474 COUPONUSAGEMETHOD_APP CouponUsageMethod = "APP" 475 COUPONUSAGEMETHOD_PAYMENT_CODE CouponUsageMethod = "PAYMENT_CODE" 476) 477 478type CouponAvailableStoreInfo struct { 479 Description *string `json:"description,omitempty"` 480 MiniProgramAppid *string `json:"mini_program_appid,omitempty"` 481 MiniProgramPath *string `json:"mini_program_path,omitempty"` 482} 483 484type CouponCodeDisplayMode string 485 486func (e CouponCodeDisplayMode) Ptr() *CouponCodeDisplayMode { 487 return &e 488} 489 490const ( 491 COUPONCODEDISPLAYMODE_INVISIBLE CouponCodeDisplayMode = "INVISIBLE" 492 COUPONCODEDISPLAYMODE_BARCODE CouponCodeDisplayMode = "BARCODE" 493 COUPONCODEDISPLAYMODE_QRCODE CouponCodeDisplayMode = "QRCODE" 494) 495 496type EntranceMiniProgram struct { 497 Appid *string `json:"appid,omitempty"` 498 Path *string `json:"path,omitempty"` 499 EntranceWording *string `json:"entrance_wording,omitempty"` 500 GuidanceWording *string `json:"guidance_wording,omitempty"` 501} 502 503type EntranceOfficialAccount struct { 504 Appid *string `json:"appid,omitempty"` 505} 506 507type EntranceFinder struct { 508 FinderId *string `json:"finder_id,omitempty"` 509 FinderVideoId *string `json:"finder_video_id,omitempty"` 510 FinderVideoCoverImageUrl *string `json:"finder_video_cover_image_url,omitempty"` 511} 512 513type ComboPackageChoice struct { 514 Name *string `json:"name,omitempty"` 515 Price *int64 `json:"price,omitempty"` 516 Count *int64 `json:"count,omitempty"` 517 ImageUrl *string `json:"image_url,omitempty"` 518 MiniProgramAppid *string `json:"mini_program_appid,omitempty"` 519 MiniProgramPath *string `json:"mini_program_path,omitempty"` 520} 521 522type FixedWeekPeriod struct { 523 DayList []WeekEnum `json:"day_list,omitempty"` 524 DayPeriodList []PeriodOfTheDay `json:"day_period_list,omitempty"` 525} 526 527type TimePeriod struct { 528 BeginTime *string `json:"begin_time,omitempty"` 529 EndTime *string `json:"end_time,omitempty"` 530} 531 532type WeekEnum string 533 534func (e WeekEnum) Ptr() *WeekEnum { 535 return &e 536} 537 538const ( 539 WEEKENUM_MONDAY WeekEnum = "MONDAY" 540 WEEKENUM_TUESDAY WeekEnum = "TUESDAY" 541 WEEKENUM_WEDNESDAY WeekEnum = "WEDNESDAY" 542 WEEKENUM_THURSDAY WeekEnum = "THURSDAY" 543 WEEKENUM_FRIDAY WeekEnum = "FRIDAY" 544 WEEKENUM_SATURDAY WeekEnum = "SATURDAY" 545 WEEKENUM_SUNDAY WeekEnum = "SUNDAY" 546) 547 548type PeriodOfTheDay struct { 549 BeginTime *int64 `json:"begin_time,omitempty"` 550 EndTime *int64 `json:"end_time,omitempty"` 551} 552
应答参数
200 OK
user_coupon_bundle_id 必填 string(40)
【用户券组ID】 用户券组的唯一标识,【向用户发放商品券批次组】时由微信支付生成
user_product_coupon_list 必填 array[object]
【用户商品券列表】 用户商品券列表
| 属性 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
coupon_code 必填 string(40) 【用户商品券Code】 用户商品券的唯一标识 coupon_state 必填 string 【用户商品券状态】 可选取值
valid_begin_time 必填 string 【有效期开始时间】 用户商品券可用开始时间,遵循rfc3339标准格式,格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE,yyyy-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间) valid_end_time 必填 string 【有效期结束时间】 用户商品券可用结束时间。遵循rfc3339标准格式,格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE,yyyy-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间) receive_time 必填 string 【领券时间】 用户领券时间。遵循rfc3339标准格式,格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE,yyyy-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间) send_request_no 必填 string(128) 【发券请求单号】 发券时传入的请求流水号 send_channel 必填 string 【发券渠道】 描述用户商品券是经由什么渠道发送的 可选取值
confirm_request_no 选填 string 【确认请求单号】 品牌方确认发券请求时传入的的请求流水号。当且仅当 品牌方调用【确认发放用户商品券API】后提供。 confirm_time 选填 string 【确认发放时间】 品牌方确认发券时间,当且仅当 品牌方调用【确认发放用户商品券API】后提供。遵循rfc3339标准格式,格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE,yyyy-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间) deactivate_request_no 选填 string(128) 【失效请求单号】 品牌方失效券请求时传入的的请求流水号。当且仅当 deactivate_time 选填 string 【失效时间】 失效时间,当且仅当 deactivate_reason 选填 string(150) 【失效原因】 失效券的原因,当且仅当 progressive_bundle_usage_detail 选填 object 【多次优惠使用详情】 当且仅当
user_product_coupon_bundle_info 必填 object 【用户券组信息】 当前用户券所属用户券组的信息
product_coupon 必填 object 【商品券信息】 该用户商品券对应的商品券详情
stock 必填 object 【批次信息】 该用户商品券发券时使用的批次详情
attach 选填 string 【自定义附加信息】 调用发券接口时品牌方使用 注: 发券渠道多样,只有品牌方通过发券接口发放的券才会在查询和回调中携带此字段,其他渠道发放的券 channel_custom_info 选填 string(1000) 【渠道自定义信息】 使用微信支付提供的其他渠道(比如「摇一摇有优惠」)发放商品券时,渠道可能会设置该渠道特定的自定义信息,请根据 coupon_tag_info 选填 object 【用户商品券标签信息】 用户商品券标签信息
brand_id 必填 string 【品牌ID】 微信支付为品牌方分配的唯一标识,该品牌应与服务商存在授权关系 |
应答示例
200 OK
1{ 2 "user_coupon_bundle_id" : "123446565767", 3 "user_product_coupon_list" : [ 4 { 5 "coupon_code" : "123446565767", 6 "coupon_state" : "USED", 7 "valid_begin_time" : "2025-01-01T00:00+08:00", 8 "valid_end_time" : "2025-01-30T23:59:59+08:00", 9 "receive_time" : "2025-01-01T09:10:00+08:00", 10 "send_request_no" : "MCHSEND202003101234", 11 "send_channel" : "BRAND_MANAGE", 12 "confirm_request_no" : "MCHCONFIRM202003101234", 13 "confirm_time" : "2025-01-20T13:29:35+08:00", 14 "deactivate_request_no" : "1002600620019090123143254436", 15 "deactivate_time" : "2025-01-20T13:29:35+08:00", 16 "deactivate_reason" : "商品已下线", 17 "progressive_bundle_usage_detail" : { 18 "use_request_no" : "MCHUSE202003101234", 19 "use_time" : "2025-07-20T13:29:35+08:00", 20 "return_request_no" : "MCHRETURN202003101234", 21 "return_time" : "2025-07-20T14:29:35+08:00", 22 "associated_order_info" : { 23 "transaction_id" : "4200000000123456789123456789", 24 "out_trade_no" : "trade_no_20250724123456", 25 "mchid" : "1234567890", 26 "sub_mchid" : "1234567890" 27 }, 28 "associated_pay_score_order_info" : { 29 "order_id" : "1000000000201908301055157220022", 30 "out_order_no" : "order_no_20250724123456", 31 "mchid" : "1234567890", 32 "sub_mchid" : "1234567890" 33 }, 34 "saved_amount" : 1000 35 }, 36 "user_product_coupon_bundle_info" : { 37 "user_coupon_bundle_id" : "7014123823561283749832", 38 "user_coupon_bundle_index" : 0, 39 "total_count" : 10, 40 "used_count" : 3 41 }, 42 "product_coupon" : { 43 "product_coupon_id" : "1002323", 44 "scope" : "ALL", 45 "type" : "NORMAL", 46 "usage_mode" : "SINGLE", 47 "single_usage_info" : { 48 "normal_coupon" : { 49 "threshold" : 10000, 50 "discount_amount" : 100 51 }, 52 "discount_coupon" : { 53 "threshold" : 10000, 54 "percent_off" : 30 55 } 56 }, 57 "progressive_bundle_usage_info" : { 58 "count" : 10, 59 "interval_days" : 1 60 }, 61 "display_info" : { 62 "name" : "全场满100可减10元", 63 "image_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx", 64 "background_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx", 65 "detail_image_url_list" : [ 66 "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx" 67 ], 68 "original_price" : 10000, 69 "combo_package_list" : [ 70 { 71 "name" : "咖啡2选1", 72 "pick_count" : 3, 73 "choice_list" : [ 74 { 75 "name" : "美式", 76 "price" : 10000, 77 "count" : 2, 78 "image_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx", 79 "mini_program_appid" : "wx4fd12345678", 80 "mini_program_path" : "/pages/index/index" 81 } 82 ] 83 } 84 ] 85 }, 86 "out_product_no" : "Product_1234567890", 87 "state" : "AUDITING", 88 "deactivate_request_no" : "1002600620019090123143254436", 89 "deactivate_time" : "2025-06-20T13:29:35+08:00", 90 "deactivate_reason" : "商品已下架", 91 "brand_id" : "120344" 92 }, 93 "stock" : { 94 "product_coupon_id" : "200000001", 95 "stock_id" : "123456789", 96 "remark" : "满减券", 97 "coupon_code_mode" : "UPLOAD", 98 "coupon_code_count_info" : { 99 "total_count" : 10000, 100 "available_count" : 999 101 }, 102 "stock_send_rule" : { 103 "max_count" : 10000000, 104 "max_count_per_day" : 10000, 105 "max_count_per_user" : 1 106 }, 107 "progressive_bundle_usage_rule" : { 108 "coupon_available_period" : { 109 "available_begin_time" : "2025-01-01T00:00:00+08:00", 110 "available_end_time" : "2025-10-01T00:00:00+08:00", 111 "available_days" : 10, 112 "wait_days_after_receive" : 1, 113 "weekly_available_period" : { 114 "day_list" : [ 115 "MONDAY" 116 ], 117 "day_period_list" : [ 118 { 119 "begin_time" : 60, 120 "end_time" : 86399 121 } 122 ] 123 }, 124 "irregular_available_period_list" : [ 125 { 126 "begin_time" : "2025-01-01T00:00:00+08:00", 127 "end_time" : "2025-10-01T00:00:00+08:00" 128 } 129 ] 130 }, 131 "normal_coupon" : { 132 "threshold" : 10000, 133 "discount_amount" : 100 134 }, 135 "discount_coupon" : { 136 "threshold" : 10000, 137 "percent_off" : 30 138 }, 139 "exchange_coupon" : { 140 "threshold" : 10000, 141 "exchange_price" : 100 142 } 143 }, 144 "stock_bundle_info" : { 145 "stock_bundle_id" : "123456789", 146 "stock_bundle_index" : 0 147 }, 148 "usage_rule_display_info" : { 149 "coupon_usage_method_list" : [ 150 "MINI_PROGRAM" 151 ], 152 "mini_program_appid" : "wx1234567890", 153 "mini_program_path" : "/pages/index/product", 154 "app_path" : "https://www.example.com/jump-to-app", 155 "usage_description" : "全场可用", 156 "coupon_available_store_info" : { 157 "description" : "可在上海市区的所有门店使用,详细列表参考小程序内信息为准", 158 "mini_program_appid" : "wx1234567890", 159 "mini_program_path" : "/pages/index/store-list" 160 } 161 }, 162 "coupon_display_info" : { 163 "code_display_mode" : "QRCODE", 164 "background_color" : "Color010", 165 "entrance_mini_program" : { 166 "appid" : "wx1234567890", 167 "path" : "/pages/index/product", 168 "entrance_wording" : "欢迎选购", 169 "guidance_wording" : "获取更多优惠" 170 }, 171 "entrance_official_account" : { 172 "appid" : "wx1234567890" 173 }, 174 "entrance_finder" : { 175 "finder_id" : "gh_12345678", 176 "finder_video_id" : "UDFsdf24df34dD456Hdf34", 177 "finder_video_cover_image_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx" 178 } 179 }, 180 "notify_config" : { 181 "notify_appid" : "wx4fd12345678" 182 }, 183 "store_scope" : "SPECIFIC", 184 "sent_count_info" : { 185 "total_count" : 100, 186 "today_count" : 10 187 }, 188 "state" : "SENDING", 189 "deactivate_request_no" : "1002600620019090123143254436", 190 "deactivate_time" : "2025-01-01T00:00+08:00", 191 "deactivate_reason" : "批次信息有误,重新创建", 192 "brand_id" : "120344" 193 }, 194 "attach" : "example_attach", 195 "channel_custom_info" : "example_channel_custom_info", 196 "coupon_tag_info" : { 197 "coupon_tag_list" : [ 198 "MEMBER" 199 ], 200 "member_tag_info" : { 201 "member_card_id" : "MemberCardId_1234567890" 202 } 203 }, 204 "brand_id" : "120344" 205 } 206 ] 207} 208
错误码
以下是本接口返回的错误码列表。详细错误码规则,请参考微信支付接口规则-错误码和错误提示
状态码 | 错误码 | 描述 | 解决方案 |
|---|---|---|---|
400 | PARAM_ERROR | 参数错误 | 请根据错误提示正确传入参数 |
400 | INVALID_REQUEST | HTTP 请求不符合微信支付 APIv3 接口规则 | 请参阅 接口规则 |
401 | SIGN_ERROR | 验证不通过 | 请参阅 签名常见问题 |
500 | SYSTEM_ERROR | 系统异常,请稍后重试 | 请稍后重试 |
400 | INVALID_REQUEST | 传入参数不符合业务规则 | 请参考文档中对每个字段的要求以及组合要求,确认请求参数是否满足 |
404 | NOT_FOUND | 未找到 product_coupon_id 对应的商品券 | 请确认 product_coupon_id 存在且属于当前品牌 |
404 | NOT_FOUND | 未找到 stock_id 对应的商品券批次 | 请确认 stock_id 存在且属于当前商品券 |
404 | NOT_FOUND | 未找到 coupon_code 对应的用户商品券 | 请确认 coupon_code 存在且属于当前商品券批次,且已发放给用户 |
429 | RATELIMIT_EXCEEDED | 请求超过接口频率限制 | 请稍后使用原参数重试 |


