失效用户商品券
更新时间:2025.10.21服务商可以通过本接口将用户的商品券失效
前置条件:已经给用户发券成功,且商品券的 usage_mode 不为 PROGRESSIVE_BUNDLE
接口说明
支持商户:【普通服务商】
请求方式:【POST】/v3/marketing/partner/product-coupon/users/{openid}/coupons/{coupon_code}/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 路径参数
coupon_code 必填 string(40)
【用户商品券Code】 用户商品券的唯一标识
openid 必填 string
【用户OpenID】 OpenID信息,用户在AppID下的唯一标识,获取方式参考OpenID
body 包体参数
product_coupon_id 必填 string
【商品券ID】 商品券的唯一标识,创建商品券时由微信支付生成
stock_id 必填 string
【批次ID】 商品券批次的唯一标识,商品券批次创建时由微信支付生成(可使用【创建商品券API】或【添加商品券批次API】创建),请确保该批次属于 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/coupons/Code_123456/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" : "1000000013", 8 "appid" : "wx233544546545989", 9 "deactivate_reason" : "商品已下线,使用户商品券失效", 10 "stock_id" : "1000000013001", 11 "out_request_no" : "MCHDEACTIVATE202003101234", 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 DeactivateUserProductCoupon { 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}/coupons/{coupon_code}/deactivate"; 29 30 public static void main(String[] args) { 31 // TODO: 请准备商户开发必要参数,参考:https://pay.weixin.qq.com/doc/v3/partner/4013080340 32 DeactivateUserProductCoupon client = new DeactivateUserProductCoupon( 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 DeactivateUserProductCouponRequest request = new DeactivateUserProductCouponRequest(); 41 request.productCouponId = "1000000013"; 42 request.stockId = "1000000013001"; 43 request.couponCode = "Code_123456"; 44 request.appid = "wx233544546545989"; 45 request.openid = "oh-394z-6CGkNoJrsDLTTUKiAnp4"; 46 request.outRequestNo = "MCHDEACTIVATE202003101234"; 47 request.deactivateReason = "商品已下线,使用户商品券失效"; 48 request.brandId = "120344"; 49 try { 50 UserProductCouponEntity 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 UserProductCouponEntity run(DeactivateUserProductCouponRequest request) { 60 String uri = PATH; 61 uri = uri.replace("{coupon_code}", WXPayUtility.urlEncode(request.couponCode)); 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, UserProductCouponEntity.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 DeactivateUserProductCoupon(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 DeactivateUserProductCouponRequest { 108 @SerializedName("product_coupon_id") 109 public String productCouponId; 110 111 @SerializedName("stock_id") 112 public String stockId; 113 114 @SerializedName("coupon_code") 115 @Expose(serialize = false) 116 public String couponCode; 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 UserProductCouponEntity { 136 @SerializedName("coupon_code") 137 public String couponCode; 138 139 @SerializedName("coupon_state") 140 public UserProductCouponState couponState; 141 142 @SerializedName("valid_begin_time") 143 public String validBeginTime; 144 145 @SerializedName("valid_end_time") 146 public String validEndTime; 147 148 @SerializedName("receive_time") 149 public String receiveTime; 150 151 @SerializedName("send_request_no") 152 public String sendRequestNo; 153 154 @SerializedName("send_channel") 155 public UserProductCouponSendChannel sendChannel; 156 157 @SerializedName("confirm_request_no") 158 public String confirmRequestNo; 159 160 @SerializedName("confirm_time") 161 public String confirmTime; 162 163 @SerializedName("deactivate_request_no") 164 public String deactivateRequestNo; 165 166 @SerializedName("deactivate_time") 167 public String deactivateTime; 168 169 @SerializedName("deactivate_reason") 170 public String deactivateReason; 171 172 @SerializedName("single_usage_detail") 173 public CouponUsageDetail singleUsageDetail; 174 175 @SerializedName("product_coupon") 176 public ProductCouponEntity productCoupon; 177 178 @SerializedName("stock") 179 public StockEntity stock; 180 181 @SerializedName("attach") 182 public String attach; 183 184 @SerializedName("channel_custom_info") 185 public String channelCustomInfo; 186 187 @SerializedName("coupon_tag_info") 188 public CouponTagInfo couponTagInfo; 189 190 @SerializedName("brand_id") 191 public String brandId; 192 } 193 194 public enum UserProductCouponState { 195 @SerializedName("CONFIRMING") 196 CONFIRMING, 197 @SerializedName("PENDING") 198 PENDING, 199 @SerializedName("EFFECTIVE") 200 EFFECTIVE, 201 @SerializedName("USED") 202 USED, 203 @SerializedName("EXPIRED") 204 EXPIRED, 205 @SerializedName("DELETED") 206 DELETED, 207 @SerializedName("DEACTIVATED") 208 DEACTIVATED 209 } 210 211 public enum UserProductCouponSendChannel { 212 @SerializedName("BRAND_MANAGE") 213 BRAND_MANAGE, 214 @SerializedName("API") 215 API, 216 @SerializedName("RECEIVE_COMPONENT") 217 RECEIVE_COMPONENT, 218 @SerializedName("MEMBER") 219 MEMBER, 220 @SerializedName("STICKER_GIFT") 221 STICKER_GIFT 222 } 223 224 public static class CouponUsageDetail { 225 @SerializedName("use_request_no") 226 public String useRequestNo; 227 228 @SerializedName("use_time") 229 public String useTime; 230 231 @SerializedName("return_request_no") 232 public String returnRequestNo; 233 234 @SerializedName("return_time") 235 public String returnTime; 236 237 @SerializedName("associated_order_info") 238 public UserProductCouponAssociatedOrderInfo associatedOrderInfo; 239 240 @SerializedName("associated_pay_score_order_info") 241 public UserProductCouponAssociatedPayScoreOrderInfo associatedPayScoreOrderInfo; 242 243 @SerializedName("saved_amount") 244 public Long savedAmount; 245 246 @SerializedName("use_product_no_list") 247 public List<String> useProductNoList; 248 } 249 250 public static class ProductCouponEntity { 251 @SerializedName("product_coupon_id") 252 public String productCouponId; 253 254 @SerializedName("scope") 255 public ProductCouponScope scope; 256 257 @SerializedName("type") 258 public ProductCouponType type; 259 260 @SerializedName("usage_mode") 261 public UsageMode usageMode; 262 263 @SerializedName("single_usage_info") 264 public SingleUsageInfo singleUsageInfo; 265 266 @SerializedName("progressive_bundle_usage_info") 267 public ProgressiveBundleUsageInfo progressiveBundleUsageInfo; 268 269 @SerializedName("display_info") 270 public ProductCouponDisplayInfo displayInfo; 271 272 @SerializedName("out_product_no") 273 public String outProductNo; 274 275 @SerializedName("state") 276 public ProductCouponState state; 277 278 @SerializedName("deactivate_request_no") 279 public String deactivateRequestNo; 280 281 @SerializedName("deactivate_time") 282 public String deactivateTime; 283 284 @SerializedName("deactivate_reason") 285 public String deactivateReason; 286 287 @SerializedName("brand_id") 288 public String brandId; 289 290 @SerializedName("available_product_no_list") 291 public List<String> availableProductNoList; 292 293 @SerializedName("business_mode") 294 public ProductCouponBusinessMode businessMode; 295 } 296 297 public static class StockEntity { 298 @SerializedName("product_coupon_id") 299 public String productCouponId; 300 301 @SerializedName("stock_id") 302 public String stockId; 303 304 @SerializedName("remark") 305 public String remark; 306 307 @SerializedName("coupon_code_mode") 308 public CouponCodeMode couponCodeMode; 309 310 @SerializedName("coupon_code_count_info") 311 public CouponCodeCountInfo couponCodeCountInfo; 312 313 @SerializedName("stock_send_rule") 314 public StockSendRule stockSendRule; 315 316 @SerializedName("single_usage_rule") 317 public SingleUsageRule singleUsageRule; 318 319 @SerializedName("usage_rule_display_info") 320 public UsageRuleDisplayInfo usageRuleDisplayInfo; 321 322 @SerializedName("coupon_display_info") 323 public CouponDisplayInfo couponDisplayInfo; 324 325 @SerializedName("notify_config") 326 public NotifyConfig notifyConfig; 327 328 @SerializedName("store_scope") 329 public StockStoreScope storeScope; 330 331 @SerializedName("sent_count_info") 332 public StockSentCountInfo sentCountInfo; 333 334 @SerializedName("state") 335 public StockState state; 336 337 @SerializedName("deactivate_request_no") 338 public String deactivateRequestNo; 339 340 @SerializedName("deactivate_time") 341 public String deactivateTime; 342 343 @SerializedName("deactivate_reason") 344 public String deactivateReason; 345 346 @SerializedName("brand_id") 347 public String brandId; 348 } 349 350 public static class CouponTagInfo { 351 @SerializedName("coupon_tag_list") 352 public List<UserProductCouponTag> couponTagList; 353 354 @SerializedName("member_tag_info") 355 public MemberTagInfo memberTagInfo; 356 } 357 358 public static class UserProductCouponAssociatedOrderInfo { 359 @SerializedName("transaction_id") 360 public String transactionId; 361 362 @SerializedName("out_trade_no") 363 public String outTradeNo; 364 365 @SerializedName("mchid") 366 public String mchid; 367 368 @SerializedName("sub_mchid") 369 public String subMchid; 370 } 371 372 public static class UserProductCouponAssociatedPayScoreOrderInfo { 373 @SerializedName("order_id") 374 public String orderId; 375 376 @SerializedName("out_order_no") 377 public String outOrderNo; 378 379 @SerializedName("mchid") 380 public String mchid; 381 382 @SerializedName("sub_mchid") 383 public String subMchid; 384 } 385 386 public enum ProductCouponScope { 387 @SerializedName("ALL") 388 ALL, 389 @SerializedName("SINGLE") 390 SINGLE, 391 @SerializedName("CATEGORY") 392 CATEGORY 393 } 394 395 public enum ProductCouponType { 396 @SerializedName("NORMAL") 397 NORMAL, 398 @SerializedName("DISCOUNT") 399 DISCOUNT, 400 @SerializedName("EXCHANGE") 401 EXCHANGE 402 } 403 404 public enum UsageMode { 405 @SerializedName("SINGLE") 406 SINGLE, 407 @SerializedName("PROGRESSIVE_BUNDLE") 408 PROGRESSIVE_BUNDLE 409 } 410 411 public static class SingleUsageInfo { 412 @SerializedName("normal_coupon") 413 public NormalCouponUsageRule normalCoupon; 414 415 @SerializedName("discount_coupon") 416 public DiscountCouponUsageRule discountCoupon; 417 } 418 419 public static class ProgressiveBundleUsageInfo { 420 @SerializedName("count") 421 public Long count; 422 423 @SerializedName("interval_days") 424 public Long intervalDays; 425 } 426 427 public static class ProductCouponDisplayInfo { 428 @SerializedName("name") 429 public String name; 430 431 @SerializedName("image_url") 432 public String imageUrl; 433 434 @SerializedName("background_url") 435 public String backgroundUrl; 436 437 @SerializedName("detail_image_url_list") 438 public List<String> detailImageUrlList; 439 440 @SerializedName("original_price") 441 public Long originalPrice; 442 443 @SerializedName("combo_package_list") 444 public List<ComboPackage> comboPackageList; 445 } 446 447 public enum ProductCouponState { 448 @SerializedName("AUDITING") 449 AUDITING, 450 @SerializedName("EFFECTIVE") 451 EFFECTIVE, 452 @SerializedName("DEACTIVATED") 453 DEACTIVATED 454 } 455 456 public enum ProductCouponBusinessMode { 457 @SerializedName("FREE") 458 FREE 459 } 460 461 public enum CouponCodeMode { 462 @SerializedName("WECHATPAY") 463 WECHATPAY, 464 @SerializedName("UPLOAD") 465 UPLOAD, 466 @SerializedName("API_ASSIGN") 467 API_ASSIGN 468 } 469 470 public static class CouponCodeCountInfo { 471 @SerializedName("total_count") 472 public Long totalCount; 473 474 @SerializedName("available_count") 475 public Long availableCount; 476 } 477 478 public static class StockSendRule { 479 @SerializedName("max_count") 480 public Long maxCount; 481 482 @SerializedName("max_count_per_day") 483 public Long maxCountPerDay; 484 485 @SerializedName("max_count_per_user") 486 public Long maxCountPerUser; 487 } 488 489 public static class SingleUsageRule { 490 @SerializedName("coupon_available_period") 491 public CouponAvailablePeriod couponAvailablePeriod; 492 493 @SerializedName("normal_coupon") 494 public NormalCouponUsageRule normalCoupon; 495 496 @SerializedName("discount_coupon") 497 public DiscountCouponUsageRule discountCoupon; 498 499 @SerializedName("exchange_coupon") 500 public ExchangeCouponUsageRule exchangeCoupon; 501 } 502 503 public static class UsageRuleDisplayInfo { 504 @SerializedName("coupon_usage_method_list") 505 public List<CouponUsageMethod> couponUsageMethodList = new ArrayList<CouponUsageMethod>(); 506 507 @SerializedName("mini_program_appid") 508 public String miniProgramAppid; 509 510 @SerializedName("mini_program_path") 511 public String miniProgramPath; 512 513 @SerializedName("app_path") 514 public String appPath; 515 516 @SerializedName("usage_description") 517 public String usageDescription; 518 519 @SerializedName("coupon_available_store_info") 520 public CouponAvailableStoreInfo couponAvailableStoreInfo; 521 522 @SerializedName("app_jump_type") 523 public AppJumpType appJumpType; 524 525 @SerializedName("passcode_link") 526 public String passcodeLink; 527 } 528 529 public static class CouponDisplayInfo { 530 @SerializedName("code_display_mode") 531 public CouponCodeDisplayMode codeDisplayMode; 532 533 @SerializedName("background_color") 534 public String backgroundColor; 535 536 @SerializedName("entrance_mini_program") 537 public EntranceMiniProgram entranceMiniProgram; 538 539 @SerializedName("entrance_official_account") 540 public EntranceOfficialAccount entranceOfficialAccount; 541 } 542 543 public static class NotifyConfig { 544 @SerializedName("notify_appid") 545 public String notifyAppid; 546 } 547 548 public enum StockStoreScope { 549 @SerializedName("NONE") 550 NONE, 551 @SerializedName("ALL") 552 ALL, 553 @SerializedName("SPECIFIC") 554 SPECIFIC 555 } 556 557 public static class StockSentCountInfo { 558 @SerializedName("total_count") 559 public Long totalCount; 560 561 @SerializedName("today_count") 562 public Long todayCount; 563 } 564 565 public enum StockState { 566 @SerializedName("AUDITING") 567 AUDITING, 568 @SerializedName("SENDING") 569 SENDING, 570 @SerializedName("PAUSED") 571 PAUSED, 572 @SerializedName("STOPPED") 573 STOPPED, 574 @SerializedName("DEACTIVATED") 575 DEACTIVATED 576 } 577 578 public enum UserProductCouponTag { 579 @SerializedName("MEMBER") 580 MEMBER, 581 @SerializedName("MEMBER_ACTIVITY") 582 MEMBER_ACTIVITY 583 } 584 585 public static class MemberTagInfo { 586 @SerializedName("member_card_id") 587 public String memberCardId; 588 } 589 590 public static class NormalCouponUsageRule { 591 @SerializedName("threshold") 592 public Long threshold; 593 594 @SerializedName("discount_amount") 595 public Long discountAmount; 596 } 597 598 public static class DiscountCouponUsageRule { 599 @SerializedName("threshold") 600 public Long threshold; 601 602 @SerializedName("percent_off") 603 public Long percentOff; 604 } 605 606 public static class ComboPackage { 607 @SerializedName("name") 608 public String name; 609 610 @SerializedName("pick_count") 611 public Long pickCount; 612 613 @SerializedName("choice_list") 614 public List<ComboPackageChoice> choiceList = new ArrayList<ComboPackageChoice>(); 615 } 616 617 public static class CouponAvailablePeriod { 618 @SerializedName("available_begin_time") 619 public String availableBeginTime; 620 621 @SerializedName("available_end_time") 622 public String availableEndTime; 623 624 @SerializedName("available_days") 625 public Long availableDays; 626 627 @SerializedName("wait_days_after_receive") 628 public Long waitDaysAfterReceive; 629 630 @SerializedName("weekly_available_period") 631 public FixedWeekPeriod weeklyAvailablePeriod; 632 633 @SerializedName("irregular_available_period_list") 634 public List<TimePeriod> irregularAvailablePeriodList; 635 636 @SerializedName("available_seconds") 637 public Long availableSeconds; 638 } 639 640 public static class ExchangeCouponUsageRule { 641 @SerializedName("threshold") 642 public Long threshold; 643 644 @SerializedName("exchange_price") 645 public Long exchangePrice; 646 } 647 648 public enum CouponUsageMethod { 649 @SerializedName("OFFLINE") 650 OFFLINE, 651 @SerializedName("MINI_PROGRAM") 652 MINI_PROGRAM, 653 @SerializedName("APP") 654 APP, 655 @SerializedName("PAYMENT_CODE") 656 PAYMENT_CODE 657 } 658 659 public static class CouponAvailableStoreInfo { 660 @SerializedName("description") 661 public String description; 662 663 @SerializedName("mini_program_appid") 664 public String miniProgramAppid; 665 666 @SerializedName("mini_program_path") 667 public String miniProgramPath; 668 } 669 670 public enum AppJumpType { 671 @SerializedName("H5") 672 H5, 673 @SerializedName("PASSCODE_LINK") 674 PASSCODE_LINK, 675 @SerializedName("USAGE_GUIDE") 676 USAGE_GUIDE 677 } 678 679 public enum CouponCodeDisplayMode { 680 @SerializedName("INVISIBLE") 681 INVISIBLE, 682 @SerializedName("BARCODE") 683 BARCODE, 684 @SerializedName("QRCODE") 685 QRCODE 686 } 687 688 public static class EntranceMiniProgram { 689 @SerializedName("appid") 690 public String appid; 691 692 @SerializedName("path") 693 public String path; 694 695 @SerializedName("entrance_wording") 696 public String entranceWording; 697 698 @SerializedName("guidance_wording") 699 public String guidanceWording; 700 } 701 702 public static class EntranceOfficialAccount { 703 @SerializedName("appid") 704 public String appid; 705 } 706 707 public static class ComboPackageChoice { 708 @SerializedName("name") 709 public String name; 710 711 @SerializedName("price") 712 public Long price; 713 714 @SerializedName("count") 715 public Long count; 716 717 @SerializedName("image_url") 718 public String imageUrl; 719 720 @SerializedName("mini_program_appid") 721 public String miniProgramAppid; 722 723 @SerializedName("mini_program_path") 724 public String miniProgramPath; 725 } 726 727 public static class FixedWeekPeriod { 728 @SerializedName("day_list") 729 public List<WeekEnum> dayList = new ArrayList<WeekEnum>(); 730 731 @SerializedName("day_period_list") 732 public List<PeriodOfTheDay> dayPeriodList; 733 } 734 735 public static class TimePeriod { 736 @SerializedName("begin_time") 737 public String beginTime; 738 739 @SerializedName("end_time") 740 public String endTime; 741 } 742 743 public enum WeekEnum { 744 @SerializedName("MONDAY") 745 MONDAY, 746 @SerializedName("TUESDAY") 747 TUESDAY, 748 @SerializedName("WEDNESDAY") 749 WEDNESDAY, 750 @SerializedName("THURSDAY") 751 THURSDAY, 752 @SerializedName("FRIDAY") 753 FRIDAY, 754 @SerializedName("SATURDAY") 755 SATURDAY, 756 @SerializedName("SUNDAY") 757 SUNDAY 758 } 759 760 public static class PeriodOfTheDay { 761 @SerializedName("begin_time") 762 public Long beginTime; 763 764 @SerializedName("end_time") 765 public Long endTime; 766 } 767 768} 769
需配合微信支付工具库 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 := &DeactivateUserProductCouponRequest{ 29 ProductCouponId: wxpay_utility.String("1000000013"), 30 StockId: wxpay_utility.String("1000000013001"), 31 CouponCode: wxpay_utility.String("Code_123456"), 32 Appid: wxpay_utility.String("wx233544546545989"), 33 Openid: wxpay_utility.String("oh-394z-6CGkNoJrsDLTTUKiAnp4"), 34 OutRequestNo: wxpay_utility.String("MCHDEACTIVATE202003101234"), 35 DeactivateReason: wxpay_utility.String("商品已下线,使用户商品券失效"), 36 BrandId: wxpay_utility.String("120344"), 37 } 38 39 response, err := DeactivateUserProductCoupon(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 DeactivateUserProductCoupon(config *wxpay_utility.MchConfig, request *DeactivateUserProductCouponRequest) (response *UserProductCouponEntity, err error) { 51 const ( 52 host = "https://api.mch.weixin.qq.com" 53 method = "POST" 54 path = "/v3/marketing/partner/product-coupon/users/{openid}/coupons/{coupon_code}/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, "{coupon_code}", url.PathEscape(*request.CouponCode), -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 := &UserProductCouponEntity{} 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 DeactivateUserProductCouponRequest struct { 116 ProductCouponId *string `json:"product_coupon_id,omitempty"` 117 StockId *string `json:"stock_id,omitempty"` 118 CouponCode *string `json:"coupon_code,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 *DeactivateUserProductCouponRequest) MarshalJSON() ([]byte, error) { 127 type Alias DeactivateUserProductCouponRequest 128 a := &struct { 129 CouponCode *string `json:"coupon_code,omitempty"` 130 Openid *string `json:"openid,omitempty"` 131 *Alias 132 }{ 133 // 序列化时移除非 Body 字段 134 CouponCode: nil, 135 Openid: nil, 136 Alias: (*Alias)(o), 137 } 138 return json.Marshal(a) 139} 140 141type UserProductCouponEntity struct { 142 CouponCode *string `json:"coupon_code,omitempty"` 143 CouponState *UserProductCouponState `json:"coupon_state,omitempty"` 144 ValidBeginTime *time.Time `json:"valid_begin_time,omitempty"` 145 ValidEndTime *time.Time `json:"valid_end_time,omitempty"` 146 ReceiveTime *string `json:"receive_time,omitempty"` 147 SendRequestNo *string `json:"send_request_no,omitempty"` 148 SendChannel *UserProductCouponSendChannel `json:"send_channel,omitempty"` 149 ConfirmRequestNo *string `json:"confirm_request_no,omitempty"` 150 ConfirmTime *time.Time `json:"confirm_time,omitempty"` 151 DeactivateRequestNo *string `json:"deactivate_request_no,omitempty"` 152 DeactivateTime *string `json:"deactivate_time,omitempty"` 153 DeactivateReason *string `json:"deactivate_reason,omitempty"` 154 SingleUsageDetail *CouponUsageDetail `json:"single_usage_detail,omitempty"` 155 ProductCoupon *ProductCouponEntity `json:"product_coupon,omitempty"` 156 Stock *StockEntity `json:"stock,omitempty"` 157 Attach *string `json:"attach,omitempty"` 158 ChannelCustomInfo *string `json:"channel_custom_info,omitempty"` 159 CouponTagInfo *CouponTagInfo `json:"coupon_tag_info,omitempty"` 160 BrandId *string `json:"brand_id,omitempty"` 161} 162 163type UserProductCouponState string 164 165func (e UserProductCouponState) Ptr() *UserProductCouponState { 166 return &e 167} 168 169const ( 170 USERPRODUCTCOUPONSTATE_CONFIRMING UserProductCouponState = "CONFIRMING" 171 USERPRODUCTCOUPONSTATE_PENDING UserProductCouponState = "PENDING" 172 USERPRODUCTCOUPONSTATE_EFFECTIVE UserProductCouponState = "EFFECTIVE" 173 USERPRODUCTCOUPONSTATE_USED UserProductCouponState = "USED" 174 USERPRODUCTCOUPONSTATE_EXPIRED UserProductCouponState = "EXPIRED" 175 USERPRODUCTCOUPONSTATE_DELETED UserProductCouponState = "DELETED" 176 USERPRODUCTCOUPONSTATE_DEACTIVATED UserProductCouponState = "DEACTIVATED" 177) 178 179type UserProductCouponSendChannel string 180 181func (e UserProductCouponSendChannel) Ptr() *UserProductCouponSendChannel { 182 return &e 183} 184 185const ( 186 USERPRODUCTCOUPONSENDCHANNEL_BRAND_MANAGE UserProductCouponSendChannel = "BRAND_MANAGE" 187 USERPRODUCTCOUPONSENDCHANNEL_API UserProductCouponSendChannel = "API" 188 USERPRODUCTCOUPONSENDCHANNEL_RECEIVE_COMPONENT UserProductCouponSendChannel = "RECEIVE_COMPONENT" 189 USERPRODUCTCOUPONSENDCHANNEL_MEMBER UserProductCouponSendChannel = "MEMBER" 190 USERPRODUCTCOUPONSENDCHANNEL_STICKER_GIFT UserProductCouponSendChannel = "STICKER_GIFT" 191) 192 193type CouponUsageDetail struct { 194 UseRequestNo *string `json:"use_request_no,omitempty"` 195 UseTime *time.Time `json:"use_time,omitempty"` 196 ReturnRequestNo *string `json:"return_request_no,omitempty"` 197 ReturnTime *time.Time `json:"return_time,omitempty"` 198 AssociatedOrderInfo *UserProductCouponAssociatedOrderInfo `json:"associated_order_info,omitempty"` 199 AssociatedPayScoreOrderInfo *UserProductCouponAssociatedPayScoreOrderInfo `json:"associated_pay_score_order_info,omitempty"` 200 SavedAmount *int64 `json:"saved_amount,omitempty"` 201 UseProductNoList []string `json:"use_product_no_list,omitempty"` 202} 203 204type ProductCouponEntity struct { 205 ProductCouponId *string `json:"product_coupon_id,omitempty"` 206 Scope *ProductCouponScope `json:"scope,omitempty"` 207 Type *ProductCouponType `json:"type,omitempty"` 208 UsageMode *UsageMode `json:"usage_mode,omitempty"` 209 SingleUsageInfo *SingleUsageInfo `json:"single_usage_info,omitempty"` 210 ProgressiveBundleUsageInfo *ProgressiveBundleUsageInfo `json:"progressive_bundle_usage_info,omitempty"` 211 DisplayInfo *ProductCouponDisplayInfo `json:"display_info,omitempty"` 212 OutProductNo *string `json:"out_product_no,omitempty"` 213 State *ProductCouponState `json:"state,omitempty"` 214 DeactivateRequestNo *string `json:"deactivate_request_no,omitempty"` 215 DeactivateTime *string `json:"deactivate_time,omitempty"` 216 DeactivateReason *string `json:"deactivate_reason,omitempty"` 217 BrandId *string `json:"brand_id,omitempty"` 218 AvailableProductNoList []string `json:"available_product_no_list,omitempty"` 219 BusinessMode *ProductCouponBusinessMode `json:"business_mode,omitempty"` 220} 221 222type StockEntity struct { 223 ProductCouponId *string `json:"product_coupon_id,omitempty"` 224 StockId *string `json:"stock_id,omitempty"` 225 Remark *string `json:"remark,omitempty"` 226 CouponCodeMode *CouponCodeMode `json:"coupon_code_mode,omitempty"` 227 CouponCodeCountInfo *CouponCodeCountInfo `json:"coupon_code_count_info,omitempty"` 228 StockSendRule *StockSendRule `json:"stock_send_rule,omitempty"` 229 SingleUsageRule *SingleUsageRule `json:"single_usage_rule,omitempty"` 230 UsageRuleDisplayInfo *UsageRuleDisplayInfo `json:"usage_rule_display_info,omitempty"` 231 CouponDisplayInfo *CouponDisplayInfo `json:"coupon_display_info,omitempty"` 232 NotifyConfig *NotifyConfig `json:"notify_config,omitempty"` 233 StoreScope *StockStoreScope `json:"store_scope,omitempty"` 234 SentCountInfo *StockSentCountInfo `json:"sent_count_info,omitempty"` 235 State *StockState `json:"state,omitempty"` 236 DeactivateRequestNo *string `json:"deactivate_request_no,omitempty"` 237 DeactivateTime *time.Time `json:"deactivate_time,omitempty"` 238 DeactivateReason *string `json:"deactivate_reason,omitempty"` 239 BrandId *string `json:"brand_id,omitempty"` 240} 241 242type CouponTagInfo struct { 243 CouponTagList []UserProductCouponTag `json:"coupon_tag_list,omitempty"` 244 MemberTagInfo *MemberTagInfo `json:"member_tag_info,omitempty"` 245} 246 247type UserProductCouponAssociatedOrderInfo struct { 248 TransactionId *string `json:"transaction_id,omitempty"` 249 OutTradeNo *string `json:"out_trade_no,omitempty"` 250 Mchid *string `json:"mchid,omitempty"` 251 SubMchid *string `json:"sub_mchid,omitempty"` 252} 253 254type UserProductCouponAssociatedPayScoreOrderInfo struct { 255 OrderId *string `json:"order_id,omitempty"` 256 OutOrderNo *string `json:"out_order_no,omitempty"` 257 Mchid *string `json:"mchid,omitempty"` 258 SubMchid *string `json:"sub_mchid,omitempty"` 259} 260 261type ProductCouponScope string 262 263func (e ProductCouponScope) Ptr() *ProductCouponScope { 264 return &e 265} 266 267const ( 268 PRODUCTCOUPONSCOPE_ALL ProductCouponScope = "ALL" 269 PRODUCTCOUPONSCOPE_SINGLE ProductCouponScope = "SINGLE" 270 PRODUCTCOUPONSCOPE_CATEGORY ProductCouponScope = "CATEGORY" 271) 272 273type ProductCouponType string 274 275func (e ProductCouponType) Ptr() *ProductCouponType { 276 return &e 277} 278 279const ( 280 PRODUCTCOUPONTYPE_NORMAL ProductCouponType = "NORMAL" 281 PRODUCTCOUPONTYPE_DISCOUNT ProductCouponType = "DISCOUNT" 282 PRODUCTCOUPONTYPE_EXCHANGE ProductCouponType = "EXCHANGE" 283) 284 285type UsageMode string 286 287func (e UsageMode) Ptr() *UsageMode { 288 return &e 289} 290 291const ( 292 USAGEMODE_SINGLE UsageMode = "SINGLE" 293 USAGEMODE_PROGRESSIVE_BUNDLE UsageMode = "PROGRESSIVE_BUNDLE" 294) 295 296type SingleUsageInfo struct { 297 NormalCoupon *NormalCouponUsageRule `json:"normal_coupon,omitempty"` 298 DiscountCoupon *DiscountCouponUsageRule `json:"discount_coupon,omitempty"` 299} 300 301type ProgressiveBundleUsageInfo struct { 302 Count *int64 `json:"count,omitempty"` 303 IntervalDays *int64 `json:"interval_days,omitempty"` 304} 305 306type ProductCouponDisplayInfo struct { 307 Name *string `json:"name,omitempty"` 308 ImageUrl *string `json:"image_url,omitempty"` 309 BackgroundUrl *string `json:"background_url,omitempty"` 310 DetailImageUrlList []string `json:"detail_image_url_list,omitempty"` 311 OriginalPrice *int64 `json:"original_price,omitempty"` 312 ComboPackageList []ComboPackage `json:"combo_package_list,omitempty"` 313} 314 315type ProductCouponState string 316 317func (e ProductCouponState) Ptr() *ProductCouponState { 318 return &e 319} 320 321const ( 322 PRODUCTCOUPONSTATE_AUDITING ProductCouponState = "AUDITING" 323 PRODUCTCOUPONSTATE_EFFECTIVE ProductCouponState = "EFFECTIVE" 324 PRODUCTCOUPONSTATE_DEACTIVATED ProductCouponState = "DEACTIVATED" 325) 326 327type ProductCouponBusinessMode string 328 329func (e ProductCouponBusinessMode) Ptr() *ProductCouponBusinessMode { 330 return &e 331} 332 333const ( 334 PRODUCTCOUPONBUSINESSMODE_FREE ProductCouponBusinessMode = "FREE" 335) 336 337type CouponCodeMode string 338 339func (e CouponCodeMode) Ptr() *CouponCodeMode { 340 return &e 341} 342 343const ( 344 COUPONCODEMODE_WECHATPAY CouponCodeMode = "WECHATPAY" 345 COUPONCODEMODE_UPLOAD CouponCodeMode = "UPLOAD" 346 COUPONCODEMODE_API_ASSIGN CouponCodeMode = "API_ASSIGN" 347) 348 349type CouponCodeCountInfo struct { 350 TotalCount *int64 `json:"total_count,omitempty"` 351 AvailableCount *int64 `json:"available_count,omitempty"` 352} 353 354type StockSendRule struct { 355 MaxCount *int64 `json:"max_count,omitempty"` 356 MaxCountPerDay *int64 `json:"max_count_per_day,omitempty"` 357 MaxCountPerUser *int64 `json:"max_count_per_user,omitempty"` 358} 359 360type SingleUsageRule struct { 361 CouponAvailablePeriod *CouponAvailablePeriod `json:"coupon_available_period,omitempty"` 362 NormalCoupon *NormalCouponUsageRule `json:"normal_coupon,omitempty"` 363 DiscountCoupon *DiscountCouponUsageRule `json:"discount_coupon,omitempty"` 364 ExchangeCoupon *ExchangeCouponUsageRule `json:"exchange_coupon,omitempty"` 365} 366 367type UsageRuleDisplayInfo struct { 368 CouponUsageMethodList []CouponUsageMethod `json:"coupon_usage_method_list,omitempty"` 369 MiniProgramAppid *string `json:"mini_program_appid,omitempty"` 370 MiniProgramPath *string `json:"mini_program_path,omitempty"` 371 AppPath *string `json:"app_path,omitempty"` 372 UsageDescription *string `json:"usage_description,omitempty"` 373 CouponAvailableStoreInfo *CouponAvailableStoreInfo `json:"coupon_available_store_info,omitempty"` 374 AppJumpType *AppJumpType `json:"app_jump_type,omitempty"` 375 PasscodeLink *string `json:"passcode_link,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} 384 385type NotifyConfig struct { 386 NotifyAppid *string `json:"notify_appid,omitempty"` 387} 388 389type StockStoreScope string 390 391func (e StockStoreScope) Ptr() *StockStoreScope { 392 return &e 393} 394 395const ( 396 STOCKSTORESCOPE_NONE StockStoreScope = "NONE" 397 STOCKSTORESCOPE_ALL StockStoreScope = "ALL" 398 STOCKSTORESCOPE_SPECIFIC StockStoreScope = "SPECIFIC" 399) 400 401type StockSentCountInfo struct { 402 TotalCount *int64 `json:"total_count,omitempty"` 403 TodayCount *int64 `json:"today_count,omitempty"` 404} 405 406type StockState string 407 408func (e StockState) Ptr() *StockState { 409 return &e 410} 411 412const ( 413 STOCKSTATE_AUDITING StockState = "AUDITING" 414 STOCKSTATE_SENDING StockState = "SENDING" 415 STOCKSTATE_PAUSED StockState = "PAUSED" 416 STOCKSTATE_STOPPED StockState = "STOPPED" 417 STOCKSTATE_DEACTIVATED StockState = "DEACTIVATED" 418) 419 420type UserProductCouponTag string 421 422func (e UserProductCouponTag) Ptr() *UserProductCouponTag { 423 return &e 424} 425 426const ( 427 USERPRODUCTCOUPONTAG_MEMBER UserProductCouponTag = "MEMBER" 428 USERPRODUCTCOUPONTAG_MEMBER_ACTIVITY UserProductCouponTag = "MEMBER_ACTIVITY" 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 AvailableSeconds *int64 `json:"available_seconds,omitempty"` 459} 460 461type ExchangeCouponUsageRule struct { 462 Threshold *int64 `json:"threshold,omitempty"` 463 ExchangePrice *int64 `json:"exchange_price,omitempty"` 464} 465 466type CouponUsageMethod string 467 468func (e CouponUsageMethod) Ptr() *CouponUsageMethod { 469 return &e 470} 471 472const ( 473 COUPONUSAGEMETHOD_OFFLINE CouponUsageMethod = "OFFLINE" 474 COUPONUSAGEMETHOD_MINI_PROGRAM CouponUsageMethod = "MINI_PROGRAM" 475 COUPONUSAGEMETHOD_APP CouponUsageMethod = "APP" 476 COUPONUSAGEMETHOD_PAYMENT_CODE CouponUsageMethod = "PAYMENT_CODE" 477) 478 479type CouponAvailableStoreInfo struct { 480 Description *string `json:"description,omitempty"` 481 MiniProgramAppid *string `json:"mini_program_appid,omitempty"` 482 MiniProgramPath *string `json:"mini_program_path,omitempty"` 483} 484 485type AppJumpType string 486 487func (e AppJumpType) Ptr() *AppJumpType { 488 return &e 489} 490 491const ( 492 APPJUMPTYPE_H5 AppJumpType = "H5" 493 APPJUMPTYPE_PASSCODE_LINK AppJumpType = "PASSCODE_LINK" 494 APPJUMPTYPE_USAGE_GUIDE AppJumpType = "USAGE_GUIDE" 495) 496 497type CouponCodeDisplayMode string 498 499func (e CouponCodeDisplayMode) Ptr() *CouponCodeDisplayMode { 500 return &e 501} 502 503const ( 504 COUPONCODEDISPLAYMODE_INVISIBLE CouponCodeDisplayMode = "INVISIBLE" 505 COUPONCODEDISPLAYMODE_BARCODE CouponCodeDisplayMode = "BARCODE" 506 COUPONCODEDISPLAYMODE_QRCODE CouponCodeDisplayMode = "QRCODE" 507) 508 509type EntranceMiniProgram struct { 510 Appid *string `json:"appid,omitempty"` 511 Path *string `json:"path,omitempty"` 512 EntranceWording *string `json:"entrance_wording,omitempty"` 513 GuidanceWording *string `json:"guidance_wording,omitempty"` 514} 515 516type EntranceOfficialAccount struct { 517 Appid *string `json:"appid,omitempty"` 518} 519 520type ComboPackageChoice struct { 521 Name *string `json:"name,omitempty"` 522 Price *int64 `json:"price,omitempty"` 523 Count *int64 `json:"count,omitempty"` 524 ImageUrl *string `json:"image_url,omitempty"` 525 MiniProgramAppid *string `json:"mini_program_appid,omitempty"` 526 MiniProgramPath *string `json:"mini_program_path,omitempty"` 527} 528 529type FixedWeekPeriod struct { 530 DayList []WeekEnum `json:"day_list,omitempty"` 531 DayPeriodList []PeriodOfTheDay `json:"day_period_list,omitempty"` 532} 533 534type TimePeriod struct { 535 BeginTime *string `json:"begin_time,omitempty"` 536 EndTime *string `json:"end_time,omitempty"` 537} 538 539type WeekEnum string 540 541func (e WeekEnum) Ptr() *WeekEnum { 542 return &e 543} 544 545const ( 546 WEEKENUM_MONDAY WeekEnum = "MONDAY" 547 WEEKENUM_TUESDAY WeekEnum = "TUESDAY" 548 WEEKENUM_WEDNESDAY WeekEnum = "WEDNESDAY" 549 WEEKENUM_THURSDAY WeekEnum = "THURSDAY" 550 WEEKENUM_FRIDAY WeekEnum = "FRIDAY" 551 WEEKENUM_SATURDAY WeekEnum = "SATURDAY" 552 WEEKENUM_SUNDAY WeekEnum = "SUNDAY" 553) 554 555type PeriodOfTheDay struct { 556 BeginTime *int64 `json:"begin_time,omitempty"` 557 EndTime *int64 `json:"end_time,omitempty"` 558} 559
应答参数
折叠全部参数
200 OK
coupon_code 必填 string(40)
【用户商品券Code】 用户商品券的唯一标识
coupon_state 必填 string
【用户商品券状态】
可选取值
CONFIRMING: 待确认,用户商品券发放需要品牌方调用【确认发放用户商品券API(单券)】或【确认发放用户商品券API(多次优惠)】后才能生效PENDING: 已发放待生效,用户商品券已发放成功但尚未到达可用开始时间EFFECTIVE: 已生效,用户商品券已成功发放且到达可用开始时间USED: 已核销,用户商品券已核销EXPIRED: 已过期,用户商品券已超过有效期,不再可用DELETED: 已删除,用户主动删除该券DEACTIVATED: 已失效,品牌方主动调用【失效用户商品券API】或【失效用户商品券组API】使用户商品券失效
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
【发券渠道】 描述用户商品券是经由什么渠道发送的
可选取值
BRAND_MANAGE: 摇一摇有优惠,通过摇一摇有优惠渠道发放API: 服务商自主发券,服务商通过发券接口自主发券到商家名片RECEIVE_COMPONENT: 小程序领券组件,服务商通过小程序领券组件发券MEMBER: 会员,品牌方通过会员相关活动或渠道进行发券STICKER_GIFT: 贴图有礼,用户参与品牌贴图有礼活动后发放
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)
【失效请求单号】 品牌方失效券请求时传入的的请求流水号。当且仅当 coupon_state 为 DEACTIVATED 时提供,返回品牌方调用【失效用户商品券API】或【失效用户商品券组API】时传入的请求流水号
deactivate_time 选填 string
【失效时间】 失效时间,当且仅当 coupon_state 为 DEACTIVATED 时提供。遵循rfc3339标准格式,格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE,yyyy-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)
deactivate_reason 选填 string(150)
【失效原因】 失效券的原因,当且仅当 coupon_state 为 DEACTIVATED 时提供,返回品牌方调用【失效用户商品券API】或【失效用户商品券组API】时传入的失效原因
single_usage_detail 选填 object
【单券使用详情】 当且仅当 usage_mode 为 SINGLE 时提供
use_request_no 选填 string
【券核销请求单号】 券核销的请求流水号,当且仅当用户商品券状态 coupon_state 为 USED 时提供
use_time 选填 string
【券核销时间】 券被核销的时间,当且仅当用户商品券状态 coupon_state 为 USED 时提供。遵循rfc3339标准格式,格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE,yyyy-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)
return_request_no 选填 string
【退券请求单号】 品牌退券时传入的请求流水号,当且仅当券发生了退回后提供此字段
return_time 选填 string
【退券时间】 券被退回的时间,当且仅当券发生了退回后提供此字段。遵循rfc3339标准格式,格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE,yyyy-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)
associated_order_info 选填 object
【券核销的微信支付订单信息】 券核销对应的微信支付订单信息,当且仅当用户商品券状态 coupon_state 为 USED 时提供,
注:
1、associated_order_info与 associated_pay_score_order_info 会根据核销请求时的传入参数决定返回对应字段
2、订单信息必须至少传入 transaction_id 与 out_trade_no 之一,亦可同时传入,同时传入时应保证二者指向同一笔微信支付单。
transaction_id 选填 string
【微信支付单号】 由微信支付生成的支付单唯一标识,可以唯一定位到一笔微信支付单。
注:订单信息必须至少传入 transaction_id 与 out_trade_no 之一,亦可同时传入,同时传入时应保证二者指向同一笔微信支付单。
out_trade_no 选填 string
【商户订单号】 在微信支付支付时传入的商户订单号,在商户侧具有唯一性,因此提供此字段时应同时提供下单商户号:
如果此单为服务商模式下单,则需提供 父商户号
mchid以及 子商户号sub_mchid如果此单为直连商户模式下单,则需提供 直连商户号
mchid
注:订单信息必须至少传入 transaction_id 与 out_trade_no 之一,亦可同时传入,同时传入时应保证二者指向同一笔微信支付单。
mchid 选填 string
【商户号】 当提供 out_trade_no 时此字段必传,否则可以省略。参考如下规则传入:
若为服务商模式,则此字段为服务商商户号
若为直连商户模式,则此字段为商户号
sub_mchid 选填 string
【子商户号】 当提供 out_trade_no 时,参考如下规则传入:
若为服务商模式,则此字段必填,为子商户号
若为直连商户模式,则此字段为空
不提供 out_trade_no 时可忽略此字段
associated_pay_score_order_info 选填 object
【券核销的关联微信支付分订单信息】 券核销的关联微信支付分订单信息,当且仅当用户商品券状态 coupon_state 为 USED 时提供,
注:
1、associated_order_info与 associated_pay_score_order_info 会根据核销请求时的传入参数决定返回对应字段
2、订单信息必须至少传入 order_id 与 out_order_no 之一,亦可同时传入,同时传入时应保证二者指向同一笔微信支付单。
order_id 选填 string
【微信支付服务订单号】 支付分订单在微信侧的唯一标识。
注:订单信息必须至少传入 order_id 与 out_order_no 之一,亦可同时传入,同时传入时应保证二者指向同一笔微信支付单。
out_order_no 选填 string
【商户服务订单号】 商户系统内部服务订单号,要求32个字符内,只能是数字、大小写字母_-| 且在同一个商户号下唯一。:
如果此单为服务商模式下单,则需提供 父商户号
mchid以及 子商户号sub_mchid如果此单为直连商户模式下单,则需提供 直连商户号
mchid
注:订单信息必须至少传入 order_id 与 out_order_no 之一,亦可同时传入,同时传入时应保证二者指向同一笔微信支付服务单。
mchid 选填 string
【商户号】 当提供 out_order_no 时此字段必传,否则可以省略。参考如下规则传入:
若为服务商模式,则此字段为服务商商户号
若为直连商户模式,则此字段为商户号
sub_mchid 选填 string
【子商户号】 当提供 out_order_no 时,参考如下规则传入:
若为服务商模式,则此字段必填,为子商户号
若为直连商户模式,则此字段为空
不提供 out_order_no 时可忽略此字段
saved_amount 选填 integer
【优惠金额】 使用本券的实际优惠金额,单位为分
注:
当本券为全场/品类折扣券(scope=
ALL或CATEGORY)时,提供的是传入的值
use_product_no_list 选填 array[string]
【核销商品编码列表】 核销商品编码列表
注:
当该券优惠范围为单品或品类且商户核销时传入的商品编码列表正确时提供
product_coupon 必填 object
【商品券信息】 该用户商品券对应的商品券详情
product_coupon_id 必填 string(40)
【商品券ID】 商品券的唯一标识,由微信支付生成
scope 必填 string
【优惠范围】 商品券优惠范围
可选取值
ALL: 全场商品可用券,此时券类型type仅可配置为NORMAL或DISCOUNTSINGLE: 部分商品可用券,此时券类型type配置不受限制,即可配置为NORMAL、DISCOUNT或EXCHANGECATEGORY: 品类券。适用于商户对某一品类商品提供优惠的场景;系统侧不维护商品/品类清单,具体可用商品范围由商户在display_info描述、图片等字段中向用户告知,并在核销时由商户自行判定。此时券类型type仅可配置为NORMAL或DISCOUNT
type 必填 string
【商品券类型】 商品券的优惠类型
可选取值
NORMAL: 满减券DISCOUNT: 折扣券EXCHANGE: 兑换券,仅在scope为SINGLE时可配置
usage_mode 必填 string
【使用模式】 商品券使用模式
可选取值
SINGLE: 单券,即用户只能使用一次,使用后券失效PROGRESSIVE_BUNDLE: 多次优惠,由一组批次组成,每阶梯次序对应一个批次。用户按顺序使用,每次核销后发放下一张券,直到用完为止
single_usage_info 选填 object
【单券模式信息】 单券模式配置信息,仅当 usage_mode 为 SINGLE 时提供,其他场景不提供。
normal_coupon 选填 object
【满减券使用规则】 本商品券内所有批次均以此规则提供满减优惠,当且仅当 type 为 NORMAL 且 scope 为 ALL 或 CATEGORY 时必填,其他类型不应填写。
threshold 必填 integer
【门槛金额】 使用门槛金额,单位为分,达到该门槛后可享受满减优惠。门槛可以为0,0元和0.01元都为无门槛。例如:
满 100 元可用填
10000满 0.01 元可用填
1
discount_amount 必填 integer
【固定减免金额】 固定减免金额,单位为分,必须大于0。
discount_coupon 选填 object
【折扣券使用规则】 本商品券内所有批次均以此规则提供折扣优惠,当且仅当 type 为 DISCOUNT 且 scope 为 ALL 或 CATEGORY 时必填,其他类型不应填写。
threshold 必填 integer
【门槛金额】 使用门槛金额,单位为分,达到该门槛后可享受折扣优惠。门槛可以为0,0元和0.01元都为无门槛。例如:
满 100 元可用填
10000满 0.01 元可用填
1
percent_off 必填 integer
【固定减免百分比】 表示减免金额为总金额的百分比,必须大于0。例如:填入 30 表示减免 30%,即打 7 折
progressive_bundle_usage_info 选填 object
【多次优惠模式信息】 多次优惠模式配置信息,当且仅当 usage_mode 为 PROGRESSIVE_BUNDLE 时提供,其他模式不提供。
count 必填 integer
【可使用次数】 多次优惠领取后用户可使用次数,最少3次,最多15次
interval_days 选填 integer
【多次优惠使用间隔天数】 多次优惠多次使用之间需要间隔的天数,最高7天。例如:
间隔
0天表示不限制,使用后当天仍然可以继续使用下一次优惠间隔
1天表示使用后当天不再可用,下一次优惠需要等到次日 00:00:00 才能使用间隔
2天表示使用后当天和次日不再可用,下一次优惠需要等到第三天 00:00:00 才能使用依此类推……
默认情况下为 0 天,即不限制,使用后当天仍然可以继续使用下一次优惠
display_info 必填 object
【展示信息】 商品券展示信息
name 必填 string(25)
【商品券名称】 商品券名称,长度为3-25个UTF-8字符
image_url 必填 string
【商品券图片】 商品图片的链接地址,仅支持通过【图片上传API】获取的图片URL地址。
请参考商品券图片设计规范进行设计
要求图片宽高比1:1,建议尺寸1080*1080
大小不超过2M
建议图片格式:透明PNG格式
需要注意保留透明边距(上下左右各120px)
background_url 必填 string
【商品券背景图】 商品背景图片的URL地址,仅支持通过【图片上传API】获取的图片URL地址。
要求图片宽高比65:77,建议尺寸1170*1326
大小不超过2M
建议图片格式:JPG/PNG格式
需要注意保留「商品名称」与「商品图」的安全区域
detail_image_url_list 选填 array[string]
【商品券详情图列表】 商品详情图URL地址列表,用于最多可上传8张图片,仅支持通过【图片上传API】获取的图片URL地址。
要求图片宽高比65:77,建议尺寸1170*1326
大小不超过2M
建议图片格式:JPG/PNG格式
original_price 选填 integer
【商品原价】 单位为分,用于对外展示,最大为 10000000。不填写时默认为 0
combo_package_list 选填 array[object]
【适用商品组合】 当 scope 为 SINGLE 必填,用于对外展示,其他优惠范围选填。最多配置 50 个组合
name 必填 string(25)
【适用商品名】 长度不超过25个UTF-8字符
pick_count 必填 integer
【可选单品数量】 用户可以从 choice_list 中选择的选项数量,例如 10 选 3,则这里填 3
choice_list 必填 array[object]
【单品列表】 套餐内包含的选项列表,记录每个单品的信息,最多99个单品,且不能少于设置的pick_count数量
name 必填 string(25)
【单品名称】 长度不超过25个UTF-8字符
price 必填 integer
【单品价格】 单位为分,必须大于0。
count 必填 integer
【单品数量】 最多99个
image_url 选填 string
【单品图片】 单品图片URL地址,仅支持通过【图片上传API】获取的图片URL地址,接入领券组件和核销组件的品牌方建议填写。
要求图片宽高比1:1,建议尺寸1080*1080
大小不超过2M
建议图片格式:透明PNG格式
需要注意保留透明边距(上下左右各120px)
mini_program_appid 选填 string
【单品跳转小程序AppID】 品牌方或服务商可展示单品的小程序AppID,小程序需与品牌方或服务商存在绑定关系,接入领券组件和核销组件的品牌方或服务商建议填写。需和 mini_program_path 一同填写。
mini_program_path 选填 string
【单品跳转小程序路径】 单品展示信息在小程序内的跳转路径,接入领券组件和核销组件的品牌方或服务商建议填写。需和 mini_program_appid 一同填写。
out_product_no 选填 string
【外部商品ID】 商户创建商品券时主动传入的外部商品ID,原样返回
state 必填 string
【商品券状态】 商品券状态
可选取值
AUDITING: 审批中,审批完成前商品券不可用EFFECTIVE: 生效中,商品券已生效,可以正常使用DEACTIVATED: 已失效,品牌方主动调用失效接口使商品券失效
deactivate_request_no 选填 string(128)
【失效请求单号】 当且仅当 state 为 DEACTIVATED 时提供,返回品牌方调用【失效商品券API】时传入的请求流水号
deactivate_time 选填 string
【失效时间】 当且仅当 state 为 DEACTIVATED 时提供,遵循rfc3339标准格式,格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE,yyyy-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35+08:00表示,北京时间2015年5月20日 13点29分35秒。
deactivate_reason 选填 string(150)
【失效原因】 当且仅当 state 为 DEACTIVATED 时提供,返回品牌方调用【失效商品券API】时传入的失效原因
brand_id 必填 string
【品牌ID】 微信支付为品牌方分配的唯一标识,该品牌应与服务商存在授权关系
available_product_no_list 选填 array[string]
【可用商品编码列表】 商户创建商品券时主动传入的可用商品编码,原样返回
business_mode 必填 string
【业务模式】 商品券的业务模式;本能力上线前创建的存量商品券统一返回 FREE
可选取值
FREE: 普通券,用户可直接领取。
stock 必填 object
【批次信息】 该用户商品券发券时使用的批次详情
product_coupon_id 必填 string(40)
【商品券ID】 商品券的唯一标识,由微信支付生成
stock_id 必填 string(40)
【批次ID】 商品券批次的唯一标识,由微信支付生成
remark 选填 string(20)
【备注】 仅配置品牌可见,用于自定义信息
coupon_code_mode 必填 string
【券Code分配模式】 决定发券时用户商品券Code如何产生
可选取值
WECHATPAY: 微信支付随机生成,发券时由微信支付系统自动随机生成券码,品牌方无需干预,微信支付随机生成的券Code长度限制为40个字符以内UPLOAD: 品牌方预上传Code,品牌方需先使用【预上传券Code API(单券)】或【预上传券Code API(多次优惠)】上传自定义Code,微信支付系统发券时从中随机选取,当预存Code不足时可能影响发券,品牌应及时补充API_ASSIGN: 品牌方自行指定,品牌方通过【向用户发放商品券API】自行发券时指定,微信支付系统不再进行自动分配。特别注意:这种模式的商品批次只可由品牌方自行发券,无法在摇一摇有优惠等微信支付渠道投放;商品券的usage_mode为PROGRESSIVE_BUNDLE时不可使用本模式
coupon_code_count_info 选填 object
【品牌方预上传的券Code数量信息】 当且仅当 coupon_code_mode 为 UPLOAD 时存在此字段
total_count 必填 integer
【已上传的Code总数】 品牌方为此批次已经上传过的券Code总数量
available_count 必填 integer
【当前可用的Code数】 品牌方为此批次已经上传过的券Code中,当前剩余可用的券Code数量
stock_send_rule 必填 object
【发放规则】 发放规则
max_count 必填 integer
【发放次数总上限】 批次在生命周期内总发放次数,最多 100,000,000 次
max_count_per_day 选填 integer
【每日发放次数上限】 批次在每天内发放次数上限,每日刷新,最多 100,000,000 次。默认不限制每日发放上限
max_count_per_user 必填 integer
【每个用户领取次数上限】 每个用户最多可领取本批次的次数,最多 100 次。
single_usage_rule 选填 object
【单券使用规则】 当且仅当 usage_mode 为 SINGLE 时提供,其他场景不提供
coupon_available_period 必填 object
【券可核销时间】 确定用户领券后在什么时间段内可以核销
available_begin_time 必填 string
【批次开始时间】 遵循rfc3339标准格式,格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE,yyyy-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35+08:00表示,北京时间2015年5月20日 13点29分35秒。
距离当前创建批次的时间不能超过90天,批次有效期最长不超过366天,摇优惠场景建议设置批次时间大于等于5天
available_end_time 必填 string
【批次结束时间】 遵循rfc3339标准格式,格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE,yyyy-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35+08:00表示,北京时间2015年5月20日 13点29分35秒。
批次有效期最长不超过366天
available_days 选填 integer
【券生效后N天内可用】 日期区间内,券生效后 N 天内有效,最多365天。例如:
生效当天内有效填 1
生效后2天内有效填 2
依此类推……
用户在有效期开始前领取商品券,则从有效期第1天开始计算天数,用户在有效期内领取商品券,则从领取当天开始计算天数,无论用户何时领取商品券,商品券在活动有效期结束后均不可用。
可配合 wait_days_after_receive 一同填写,也可单独填写。
注:不可与 irregular_available_period_list 同时配置
wait_days_after_receive 选填 integer
【领券后需等待N天才生效】 日期区间内,用户领券后需等待 N 天才开始生效,最多30天。例如:
领券后当天开始生效则无需填写
领券后第二天开始生效则填写 1
用户在有效期开始前领取商品券,则从有效期第1天开始计算天数,用户在有效期内领取商品券,则从领取当天开始计算天数。无论用户何时领取商品券,商品券在活动有效期结束后均不可用。
需配合 available_days 一同填写,不可单独填写。
注:不可与 irregular_available_period_list 同时配置
weekly_available_period 选填 object
【每周固定可用时间】 日期区间内,每周固定时间可以使用。可与 available_days 和 wait_days_after_receive 一同配置,一同配置时条件需同时满足券才可用(时间范围取交集)。
注:不可与 irregular_available_period_list 同时配置
day_list 必填 array[string]
【每周可用星期数】 每周特定星期X可用,在日期区间内每周循环有效。例如 配置 ["MONDAY", "FRIDAY"] 表示每周一和周五可用。
可选取值
MONDAY: 周一可用TUESDAY: 周二可用WEDNESDAY: 周三可用THURSDAY: 周四可用FRIDAY: 周五可用SATURDAY: 周六可用SUNDAY: 周日可用
day_period_list 选填 array[object]
【当天可用时间段】 生效当天特定时间段内有效,可以配置多个时间段。最多可以配置 3 个时间段。不配置则全天可用。
begin_time 必填 integer
【当天可用开始时间】 当天可用时间距离当天 00:00:00 的秒数,如 60 表示当天 00:01:00 开始可用。取值范围 [0,86399] 且必须小于 end_time
end_time 必填 integer
【当天可用结束时间】 当天结束可用时间距离当天 00:00:00 的秒数,如 86399 表示当天 23:59:59 结束可用。取值范围 [0,86399] 且必须大于 begin_time
irregular_available_period_list 选填 array[object]
【指定可用时间段】 可以配置多个无规律时间段,不同区间内请勿重叠,最多可配置2个区间。
注:不可与 available_days、wait_days_after_receive、weekly_available_period 同时配置
begin_time 必填 string
【开始时间】 区间开始时间,遵循rfc3339标准格式,格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE,yyyy-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35+08:00表示,北京时间2015年5月20日 13点29分35秒。
end_time 必填 string
【结束时间】 区间结束时间,遵循rfc3339标准格式,格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE,yyyy-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35+08:00表示,北京时间2015年5月20日 13点29分35秒。
available_seconds 选填 integer
【领取后N秒内有效】 日期区间内,用户领券后立即生效,自领取时刻起 N 秒内可用,不与自然日对齐。最大为86400(24小时),且仅支持 3600 的整数倍。
注:不可与 available_days、wait_days_after_receive、weekly_available_period、irregular_available_period_list 同时配置
normal_coupon 选填 object
【满减券使用规则】 当且仅当 type 为 NORMAL 且 scope 为 SINGLE 时必填,其他类型不应填写
threshold 必填 integer
【门槛金额】 使用门槛金额,单位为分,达到该门槛后可享受满减优惠。门槛可以为0,0元和0.01元都为无门槛。例如:
满 100 元可用填
10000满 0.01 元可用填
1
discount_amount 必填 integer
【固定减免金额】 固定减免金额,单位为分,必须大于0。
discount_coupon 选填 object
【折扣券使用规则】 当且仅当 type 为 DISCOUNT 且 scope 为 SINGLE 时必填,其他类型不应填写
threshold 必填 integer
【门槛金额】 使用门槛金额,单位为分,达到该门槛后可享受折扣优惠。门槛可以为0,0元和0.01元都为无门槛。例如:
满 100 元可用填
10000满 0.01 元可用填
1
percent_off 必填 integer
【固定减免百分比】 表示减免金额为总金额的百分比,必须大于0。例如:填入 30 表示减免 30%,即打 7 折
exchange_coupon 选填 object
【兑换券使用规则】 当且仅当 type 为 EXCHANGE 且 scope 为 SINGLE 时必填,其他类型不应填写
threshold 必填 integer
【门槛金额】 使用门槛金额,单位为分,达到该门槛后可进行兑换。门槛可以为0,0元和0.01元都为无门槛兑换。例如:
满 100 元可用填
10000满 0.01 元可用填
1
exchange_price 必填 integer
【固定兑换价格】 单位为分,必须大于或等于0。
usage_rule_display_info 必填 object
【券使用规则展示信息】 券使用规则展示信息
coupon_usage_method_list 必填 array[string]
【券使用方式列表】 可以配置多种使用方式
可选取值
OFFLINE: 线下滴码核销,点击券“立即使用”跳转展示券二维码详情(投放计划暂不支持此核销方式)MINI_PROGRAM: 线上小程序核销,点击券“立即使用”跳转至配置的商家小程序(需要添加小程序AppID和Path)APP: APP核销,在商家APP内核销PAYMENT_CODE: 微信支付付款码核销,用户点击券“立即使用”将跳转至微信支付钱包付款码,服务商扫描付款码后可通过付款码获取到用户openid,通过openid查询并核销用户券,核销后再发起下单,适合线下支付场景
mini_program_appid 选填 string
【小程序AppID】 品牌方或服务商小程序AppID,可在微信公众平台查看,该小程序与品牌或服务商存在绑定关系。
在 coupon_usage_method_list 中包含 MINI_PROGRAM 时必填,需和 mini_program_path 一同填写。
mini_program_path 选填 string
【小程序跳转路径】 品牌方或服务商小程序内部跳转路径。
在 coupon_usage_method_list 中包含 MINI_PROGRAM 时必填,需和 mini_program_appid 一同填写。
app_path 选填 string
【APP的H5跳转路径】 品牌方或服务商APP的H5跳转路径。在 app_jump_type 为 H5 时必填。
usage_description 必填 string(1000)
【券使用说明】 用于说明详细的券规则,长度不超过1000个UTF-8字符
coupon_available_store_info 选填 object
【券可用门店信息】 用于描述全部可用门店信息,可配置小程序跳转地址进行展示
description 必填 string(1000)
【券可用门店描述】 告知用户本券可在哪些门店使用,长度不超过1000个UTF-8字符
mini_program_appid 选填 string
【小程序AppID】 品牌方或服务商小程序AppID,用于展示可用门店列表的详细信息,可在微信公众平台查看,该小程序与品牌或服务商存在绑定关系。需和 mini_program_path 一同填写。
mini_program_path 选填 string
【小程序跳转路径】 品牌方或服务商小程序内部展示可用门店列表的详细信息的页面跳转路径,需和 mini_program_appid 一同填写。
app_jump_type 选填 string
【APP跳转类型】 APP跳转类型,在 coupon_usage_method_list 中包含 APP 时必填。
可选取值
H5: 跳转H5,点击券立即使用跳转至配置的H5页面PASSCODE_LINK: 口令链接,点击券立即使用展示口令链接供用户复制使用USAGE_GUIDE: 展示使用指引,引导前往APP核销
passcode_link 选填 string
【口令链接】 口令链接。在 app_jump_type 为 PASSCODE_LINK 时必填。
coupon_display_info 必填 object
【用户商品券展示信息】 用户商品券在卡包中的展示详情,包括引导用户的自定义入口
code_display_mode 必填 string
【用户商品券Code展示模式】 决定用户商品券Code在卡包中的展示形态
可选取值
INVISIBLE: 不展示CodeBARCODE: 条形码QRCODE: 二维码
background_color 选填 string
【背景颜色】 券的背景颜色,可设置10种颜色,色值请参考下方说明。颜色取值为颜色图中的颜色名称,不填默认为 Color020 。

entrance_mini_program 选填 object
【小程序入口】 展示跳转小程序的入口
appid 必填 string
【小程序AppID】 品牌方或服务商小程序的AppID,可在微信公众平台查看,该小程序与品牌或服务商存在绑定关系
path 必填 string
【小程序跳转路径】 品牌方小程序内部跳转路径
entrance_wording 必填 string(5)
【入口文案】 小程序入口文案,长度不超过5个UTF-8字符
guidance_wording 必填 string(6)
【引导文案】 小程序入口引导文案,长度不超过6个UTF-8字符
entrance_official_account 选填 object
【公众号入口】 展示跳转公众号的入口
appid 必填 string
【公众号AppID】 微信公众号唯一标识,可在微信公众平台查看,该公众号应与品牌方或服务商存在绑定关系
notify_config 必填 object
【事件通知配置】 发生券相关事件时,微信支付会向服务商发送通知,需要提供通知相关配置
notify_appid 必填 string
【事件通知AppID】 服务商或者品牌的AppID,支持小程序、服务号、公众号、APP类型的AppID,可在微信公众平台查看,用于券事件通知时计算用户的OpenID,需要与服务商或者品牌存在绑定关系
store_scope 必填 string
【可用门店范围】 控制该批次可以在品牌下哪些门店使用
可选取值
NONE: 无关联门店,该批次对外不展示可用门店信息ALL: 所有门店可用,该批次在品牌下的所有门店可用,品牌无需为该批次关联门店列表SPECIFIC: 特定门店可用,品牌需调用关联门店接口关联门店,关联后该批次在关联的门店可用
sent_count_info 必填 object
【已发放次数】 本批次已发放次数
total_count 必填 integer
【已发放总次数】 批次在生命周期内已发放次数
today_count 必填 integer
【当天已发放次数】 批次在当天已发放次数
state 必填 string
【批次状态】 商品券批次状态
可选取值
AUDITING: 审批中SENDING: 发放中PAUSED: 已暂停STOPPED: 已停止,当前已到达结束时间DEACTIVATED: 已失效,品牌方主动调用失效接口使批次失效
deactivate_request_no 选填 string(128)
【失效请求单号】 当且仅当 state 为 DEACTIVATED 时提供,返回品牌方调用失效接口时传入的请求流水号
deactivate_time 选填 string
【失效时间】 当且仅当 state 为 DEACTIVATED 时提供,遵循rfc3339标准格式,格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE,yyyy-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35+08:00表示,北京时间2015年5月20日 13点29分35秒。
deactivate_reason 选填 string(150)
【失效原因】 当且仅当 state 为 DEACTIVATED 时提供,返回品牌方调用【失效商品券批次API】时传入的失效原因
brand_id 必填 string
【品牌ID】 微信支付为品牌方分配的唯一标识,该品牌应与服务商存在授权关系
attach 选填 string
【自定义附加信息】 调用发券接口时品牌方使用 attach 字段主动设置的附加信息。微信支付不会解析该信息,仅在查询用户商品券和回调中原样返回。
注: 发券渠道多样,只有品牌方通过发券接口发放的券才会在查询和回调中携带此字段,其他渠道发放的券 attach 为空。
channel_custom_info 选填 string(1000)
【渠道自定义信息】 使用微信支付提供的其他渠道(比如「摇一摇有优惠」)发放商品券时,渠道可能会设置该渠道特定的自定义信息,请根据 send_channel 字段判断如何解析本字段。不同渠道的自定义信息格式不同,请根据对应渠道的文档解析。
coupon_tag_info 选填 object
【用户商品券标签信息】 用户商品券标签信息
coupon_tag_list 选填 array[string]
【用户商品券标签列表】 用户商品券标签列表
可选取值
MEMBER: 会员标签,标识该用户商品券为会员券MEMBER_ACTIVITY: 会员活动标签,标识该用户券为会员活动券
member_tag_info 选填 object
【会员标签信息】 当用户商品券标签列表中有MEMBER时,该字段必填
member_card_id 选填 string
【会员卡模板ID】 通过商家名片会员API创建会员卡模板成功后,获得的会员卡模板ID
brand_id 必填 string
【品牌ID】 微信支付为品牌方分配的唯一标识,该品牌应与服务商存在授权关系
应答示例
200 OK
使用户券失效
1{ 2 "coupon_code" : "Code_123456", 3 "coupon_state" : "DEACTIVATED", 4 "valid_begin_time" : "2025-08-02T00:00:00+08:00", 5 "valid_end_time" : "2025-08-31T23:59:59+08:00", 6 "receive_time" : "2025-08-02T00:00:00+08:00", 7 "send_request_no" : "MCHSEND202003101234", 8 "send_channel" : "API", 9 "confirm_request_no" : "MCHCONFIRM202003101234", 10 "confirm_time" : "2025-08-02T00:00:05+08:00", 11 "deactivate_request_no" : "MCHDEACTIVATE202003101234", 12 "deactivate_time" : "2025-08-03T12:01:00+08:00", 13 "deactivate_reason" : "商品已下线,使用户商品券失效", 14 "single_usage_detail" : { 15 "use_request_no" : "MCHUSE202003101234", 16 "use_time" : "2025-08-03T12:00:00+08:00", 17 "associated_order_info" : { 18 "transaction_id" : "4200000000123456789123456789" 19 }, 20 "return_request_no" : "MCHRETURN202003101234", 21 "return_time" : "2025-08-03T12:01:00+08:00" 22 }, 23 "product_coupon" : { 24 "product_coupon_id" : "1000000013", 25 "scope" : "ALL", 26 "type" : "DISCOUNT", 27 "usage_mode" : "SINGLE", 28 "business_mode" : "FREE", 29 "single_usage_info" : { 30 "discount_coupon" : { 31 "threshold" : 10000, 32 "percent_off" : 20 33 } 34 }, 35 "display_info" : { 36 "name" : "全场满100立打8折-新名字", 37 "image_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx", 38 "background_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx", 39 "detail_image_url_list" : [ 40 "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/xxx" 41 ] 42 }, 43 "state" : "EFFECTIVE", 44 "out_product_no" : "Product_1234567890", 45 "brand_id" : "120344" 46 }, 47 "stock" : { 48 "product_coupon_id" : "1000000013", 49 "stock_id" : "1000000013001", 50 "remark" : "8月工作日有效批次", 51 "coupon_code_mode" : "UPLOAD", 52 "coupon_code_count_info" : { 53 "total_count" : 0, 54 "available_count" : 0 55 }, 56 "stock_send_rule" : { 57 "max_count" : 10000000, 58 "max_count_per_user" : 1 59 }, 60 "single_usage_rule" : { 61 "coupon_available_period" : { 62 "available_begin_time" : "2025-08-01T00:00:00+08:00", 63 "available_end_time" : "2025-08-31T23:59:59+08:00", 64 "available_days" : 30, 65 "weekly_available_period" : { 66 "day_list" : [ 67 "MONDAY", 68 "TUESDAY", 69 "WEDNESDAY", 70 "THURSDAY", 71 "FRIDAY" 72 ] 73 } 74 } 75 }, 76 "usage_rule_display_info" : { 77 "coupon_usage_method_list" : [ 78 "OFFLINE", 79 "MINI_PROGRAM", 80 "PAYMENT_CODE" 81 ], 82 "mini_program_appid" : "wx1234567890", 83 "mini_program_path" : "/pages/index/product", 84 "usage_description" : "工作日可用", 85 "coupon_available_store_info" : { 86 "description" : "所有门店可用,可使用小程序查看门店列表", 87 "mini_program_appid" : "wx1234567890", 88 "mini_program_path" : "/pages/index/store-list" 89 } 90 }, 91 "coupon_display_info" : { 92 "code_display_mode" : "QRCODE", 93 "background_color" : "Color010", 94 "entrance_mini_program" : { 95 "appid" : "wx1234567890", 96 "path" : "/pages/index/product", 97 "entrance_wording" : "欢迎选购", 98 "guidance_wording" : "获取更多优惠" 99 }, 100 "entrance_official_account" : { 101 "appid" : "wx1234567890" 102 } 103 }, 104 "notify_config" : { 105 "notify_appid" : "wx4fd12345678" 106 }, 107 "store_scope" : "NONE", 108 "sent_count_info" : { 109 "total_count" : 0, 110 "today_count" : 0 111 }, 112 "state" : "SENDING", 113 "brand_id" : "120344" 114 }, 115 "attach" : "any attach content", 116 "brand_id" : "120344" 117} 118
错误码
以下是本接口返回的错误码列表。详细错误码规则,请参考微信支付接口规则-错误码和错误提示
状态码 | 错误码 | 描述 | 解决方案 |
|---|---|---|---|
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 | 请求超过接口频率限制 | 请稍后使用原参数重试 |
