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