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


