查询先享卡订单API

最新更新时间:2020.06.12 版本说明


商户可以通过商户领卡号查询指定的先享卡,可用于对账或者界面展示。

接口说明

适用对象:直连商户

请求URL:https://api.mch.weixin.qq.com/v3/discount-card/cards/{out_card_code}

请求方式:GET

接口规则:https://wechatpay-api.gitbook.io/wechatpay-api-v3


path 指该参数为路径参数

query 指该参数为URL参数

body 指该参数需在请求JSON传参


请求参数

参数名 变量 类型[长度限制] 必填 描述
商户领卡号 out_card_code string[1,32] path 商户在请求领卡预受理接口时传入的领卡请求号,同一个商户号下必须唯一,要求32个字符内,只能是数字、大小写字母_-|*
示例值:233bcbf407e87789b8e471f251774f95

请求示例


https://api.mch.weixin.qq.com/v3/discount-card/cards/233bcbf407e87789b8e471f251774f95
    
{
JAVA示例代码
}
    

返回参数

参数名 变量 类型[长度限制] 必填 描述
先享卡ID card_id string[1,64] 先享卡ID,唯一标识一个先享卡。
示例值:233bcbf407e87789b8e471f251774f95
先享卡模板ID card_template_id string[1,64] 先享卡卡模板ID,唯一定义此资源的标识。创建模板后可获得。
示例值:87789b2f25177433bcbf407e8e471f95
用户标识 openid string [1,128] 微信用户在商户对应appid下的唯一标识
示例值:oUpF8uMuAJ2pxb1Q9zNjWeS6o
商户领卡号 out_card_code string[1,32] 商户在请求领卡预受理接口时传入的领卡请求号,同一个商户号下必须唯一,要求32个字符内,只能是数字、大小写字母_-|*
示例值:6e8369071cd942c0476613f9d1ce9ca3
公众账号ID appid string[10,32] 微信公众平台分配的与传入的商户号建立了支付绑定关系的appid,可在公众平台查看绑定关系
示例值:wxd678efh567hg6787
商户号 mchid string[1,32] 微信支付分配的商户号
示例值:1230000109
+ 约定时间期限 time_range object 用户领取先享卡之后,约定的生效时间和到期时间。
参数名 变量 类型[长度限制] 必填 描述
约定开始时间 begin_time string[1,32] 用户领取先享卡后,卡约定开始生效的时间,遵循rfc3339标准格式,格式为YYYY-MM-DDTHH:mm:ss.sss+TIMEZONE,YYYY-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss.sss表示时分秒毫秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35.120+08:00表示北京时间2015年05月20日13点29分35秒
示例值:2015-05-20T13:29:35.120+08:00
约定结束时间 end_time string[1,32] 用户领取先享卡后,卡约定失效的时间,遵循rfc3339标准格式,格式为YYYY-MM-DDTHH:mm:ss.sss+TIMEZONE,YYYY-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss.sss表示时分秒毫秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35.120+08:00表示北京时间2015年05月20日13点29分35秒
示例值:2015-05-20T13:29:35.120+08:00
状态 state string[1,16] 先享卡的守约状态:
ONGOING:约定进行中,表示用户在约定有效期内,尚未完成所有目标时,守约状态为约定进行中。
SETTLING:约定到期核对中,在约定有效期结束后的一段时间,商户可对卡记录进行校对并做必要调整,守约状态为约定到期核对调整中。
FINISHED:已完成约定,表示用户在约定有效期内,已完成所有目标,守约状态为已完成约定。
UNFINISHED:未完成约定,表示用户在约定有效期到期后,最终未完成所有约定目标,或用户提前退出约定,守约状态为未完成约定。
示例值:ONGOING
未完成约定原因 unfinished_reason string[1,16] 用户未完成约定的原因,当订单守约状态为UNFINISHED时,返回此字段
DUE_TO_QUIT:到期未完成约
EARLY_QUIT:提前退出约定
示例值:DUE_TO_QUIT
享受优惠总金额 total_amount int64 表示用户享受优惠的总金额,单位为:分;
示例值:1000
+ 用户退回优惠的付款信息 pay_information object 当状态为UNFINISHED(用户未完成约定)时,且需要退回已享受的优惠金额时,返回此字段;
参数名 变量 类型[长度限制] 必填 描述
付款金额

pay_amount

int64

用户需要退回优惠而付款的金额,单位为:分;
示例值:100
付款状态

pay_state

string[1,8)

用户付款状态:
PAYING:付款中
PAID:已付款
示例值:2015-05-20T13:29:35.120+08:00
微信支付订单号

transaction_id

string[1,64)

微信支付订单号,仅在订单成功收款时才返回
示例值:1009660380201506130728806387
支付时间

pay_time

string[1,32)

用户成功支付的时间,仅在订单成功收款时才返回。遵循rfc3339标准格式,格式为YYYY-MM-DDTHH:mm:ss.sss+TIMEZONE,YYYY-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss.sss表示时分秒毫秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35.120+08:00表示北京时间2015年05月20日13点29分35秒
示例值:2015-05-20T13:29:35.120+08:00
创卡时间 create_time string[1,32] 创卡时间,遵循rfc3339标准格式,格式为YYYY-MM-DDTHH:mm:ss.sss+TIMEZONE,YYYY-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss.sss表示时分秒毫秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35.120+08:00表示北京时间2015年05月20日13点29分35秒
示例值:2015-05-20T13:29:35.120+08:00
+ 目标列表 objectives array 用户先享卡目标列表
参数名 变量 类型[长度限制] 必填 描述
目标ID objective_id string[1,32] 由先享卡平台生成,唯一标识一个先享卡目标。商户需要记录该目标ID,进行同步用户记录。
示例值:123456
目标名称 name string[1,20] 目标的名称
示例值:一周购买三次商品
目标数量 count int 履约目标需要完成的数量,必须大于0。
示例值:1
目标单位 unit string[1,5] 目标的单位
示例值:次
目标描述 description string[1,50] 对先享卡目标的补充信息。
示例值:特价商品
+ 目标完成记录 objective_completion_records array 用户完成的目标明细列表。
参数名 变量 类型[长度限制] 必填 描述
目标完成流水号 objective_completion_serial_no string[1,32] 目标流水号,由商户侧生成,由数字、字母组成,由商户侧保证商户系统内全局唯一性,用于做目标同步时的幂等判断。
示例值:578354545
目标ID objective_id string[1,32] 微信先享卡为每个先享卡目标分配的唯一ID。
示例值:123456
目标完成时间 completion_time string[1,32] 用户履约行为发生的时间,遵循rfc3339标准格式,格式为YYYY-MM-DDTHH:mm:ss.sss+TIMEZONE,YYYY-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss.sss表示时分秒毫秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35.120+08:00表示北京时间2015年05月20日13点29分35秒。

示例值:2015-05-20T13:29:35.120+08:00
目标完成类型 completion_type string[1,8] 目标完成类型,枚举值: 
INCREASE:增加数量,表示用户发生了履约行为
DECREASE:减少数量,表示取消用户的履约行为(例如用户取消购买、退货退款等)
示例值:INCREASE
目标完成描述 description string[1,20] 用户本次履约的描述。
示例值:购买商品
目标完成数量 completion_count int 用户本次履约的数量,必须大于0。
示例值:1
备注说明 remark string[1,50] 对于用户履约情况的一些补充信息。
示例值:特价商品
+ 优惠列表 rewards array 用户先享卡优惠列表
参数名 变量 类型[长度限制] 必填 描述
优惠ID reward_id string[1,32] 由先享卡平台生成,唯一标识一个先享卡目标。商户需要记录该优惠ID,进行同步用户记录。
示例值:123456
优惠名称 name string[1,20] 优惠名称
示例值:八折优惠
优惠数量类型 count_type string[1,18] 优惠数量的类型标识,枚举值:
COUNT_UNLIMITED:不限数量
COUNT_LIMIT:有限数量
示例值:COUNT_LIMIT
优惠数量 count int 本项优惠可使用的数量,必须大于0。
示例值:1
优惠单位 unit string[1,5] 优惠的单位
示例值:个
优惠金额 amount int64 1、优惠金额,此项优惠对应的优惠总金额,单位:分,必须大于0。
2、此项优惠已享累计金额≤创建模板时配置的此项奖励的奖励金额,
例如:优惠为【满10元减3元优惠券4张】时,用户一次消费使用了2张优惠券,优惠金额为本次优惠总金额6元,优惠数量为本次使用优惠的优惠券数量2张
示例值:100
优惠描述 description string[1,50] 对先享卡优惠的补充信息
示例值:特价商品优惠
+ 优惠使用记录 reward_usage_records array 优惠使用记录列表。
参数名 变量 类型[长度限制] 必填 描述
优惠使用记录流水号 reward_usage_serial_no string[1,32] 商户侧生成,由数字、字母组成,由商户侧保证商户系统内全局唯一性,用于做奖励同步时的幂等判断。
示例值:578354
优惠ID reward_id string[1,32] 微信先享卡为每个先享卡优惠分配的唯一ID
示例值:123456
优惠使用时间 usage_time string[1,32] 用户使用优惠的时间,遵循rfc3339标准格式,格式为YYYY-MM-DDTHH:mm:ss.sss+TIMEZONE,YYYY-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss.sss表示时分秒毫秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35.120+08:00表示北京时间2015年05月20日13点29分35秒(需要增加所有跟时间有关的参数的描述)
示例值:2015-05-20T13:29:35.120+08:00
优惠使用类型 usage_type string[1,8] 目标完成类型,枚举值: 
INCREASE:增加数量,表示用户发生了履约行为
DECREASE:减少数量,表示取消用户的履约行为(例如用户取消购买、退货退款等)
示例值:INCREASE
优惠使用描述 description string[1,20] 用户获得奖励的描述
示例值:购买商品
优惠使用数量 usage_count int 用户本次获得的奖励数量,必须大于0。
示例值:1
优惠金额 amount int 1、优惠金额,用户此项本次享受的优惠对应的优惠总金额,单位:分,必须大于0。
2、子优惠已享金额累计≤创建模板时配置的此子优惠的价值金额 例如:优惠为【满10元减3元优惠券4张】时,用户一次消费使用了2张优惠券,优惠金额为本次优惠总金额6元,优惠数量为本次使用优惠的优惠券数量2张
示例值:100
备注说明 remark string[1,50] 对于用户奖励情况的一些补充信息
示例值:特价商品
邀请者用户标识 sharer_openid string[1,128] 微信用户在商户对应appid下的唯一标识。
仅当此卡是通过“邀请有礼”渠道领卡时,会返回此字段;指此先享卡是通过此[邀请者]邀请领卡成功的。当此先享卡完成约定时,商户可给此[邀请者]下发应邀请有礼的奖励
示例值:oUpF8uMuAJ2pxb1Q9zNjWUHsd

返回示例


{
  "unfinished_reason" : "DUE_TO_QUIT",
  "mchid" : "1230000109",
  "create_time" : "2015-05-20T13:29:35.12+08:00",
  "openid" : "oUpF8uMuAJ2pxb1Q9zNjWeS6o",
  "pay_information" : {
    "transaction_id" : "1009660380201506130728806387",
    "pay_state" : "PAYING",
    "pay_amount" : 100,
    "pay_time" : "2015-05-20T13:29:35.12+08:00"
  },
  "sharer_openid" : "oUpF8uMuAJ2pxb1Q9zNjWUHsd",
  "card_id" : "233bcbf407e87789b8e471f251774f95",
  "card_template_id" : "87789b2f25177433bcbf407e8e471f95",
  "out_card_code" : "6e8369071cd942c0476613f9d1ce9ca3",
  "time_range" : {
    "end_time" : "2015-05-20T13:29:35.12+08:00",
    "begin_time" : "2015-05-20T13:29:35.12+08:00"
  },
  "total_amount" : 1000,
  "appid" : "wxd678efh567hg6787",
  "objectives" : [ {
    "unit" : "次",
    "name" : "一周购买三次商品",
    "count" : 1,
    "description" : "特价商品",
    "objective_completion_records" : [ {
      "completion_time" : "2015-05-20T13:29:35.120+08:00",
      "objective_completion_serial_no" : "578354545",
      "description" : "购买商品/取消购买商品",
      "completion_count" : 1,
      "remark" : "特价商品",
      "completion_type" : "INCREASE",
      "objective_id" : "123456"
    }, {
      "completion_time" : "2015-05-20T13:29:35.120+08:00",
      "objective_completion_serial_no" : "578354545",
      "description" : "购买商品/取消购买商品",
      "completion_count" : 1,
      "remark" : "特价商品",
      "completion_type" : "INCREASE",
      "objective_id" : "123456"
    } ],
    "objective_id" : "123456"
  }, {
    "unit" : "次",
    "name" : "一周购买三次商品",
    "count" : 1,
    "description" : "特价商品",
    "objective_completion_records" : [ {
      "completion_time" : "2015-05-20T13:29:35.120+08:00",
      "objective_completion_serial_no" : "578354545",
      "description" : "购买商品/取消购买商品",
      "completion_count" : 1,
      "remark" : "特价商品",
      "completion_type" : "INCREASE",
      "objective_id" : "123456"
    }, {
      "completion_time" : "2015-05-20T13:29:35.120+08:00",
      "objective_completion_serial_no" : "578354545",
      "description" : "购买商品/取消购买商品",
      "completion_count" : 1,
      "remark" : "特价商品",
      "completion_type" : "INCREASE",
      "objective_id" : "123456"
    } ],
    "objective_id" : "123456"
  } ],
  "state" : "ONGOING",
  "rewards" : [ {
    "unit" : "个",
    "amount" : 100,
    "count_type" : "COUNT_LIMIT",
    "name" : "八折优惠",
    "count" : 1,
    "description" : "特价商品优惠",
    "reward_id" : "123456",
    "reward_usage_records" : [ {
      "usage_count" : 100,
      "amount" : 1,
      "usage_type" : "INCREASE",
      "usage_time" : "2015-05-20T13:29:35.120+08:00",
      "reward_usage_serial_no" : "578354",
      "description" : "购买商品",
      "reward_id" : "123456",
      "remark" : "特价商品"
    }, {
      "usage_count" : 100,
      "amount" : 1,
      "usage_type" : "INCREASE",
      "usage_time" : "2015-05-20T13:29:35.120+08:00",
      "reward_usage_serial_no" : "578354",
      "description" : "购买商品",
      "reward_id" : "123456",
      "remark" : "特价商品"
    } ]
  }, {
    "unit" : "个",
    "amount" : 100,
    "count_type" : "COUNT_LIMIT",
    "name" : "八折优惠",
    "count" : 1,
    "description" : "特价商品优惠",
    "reward_id" : "123456",
    "reward_usage_records" : [ {
      "usage_count" : 100,
      "amount" : 1,
      "usage_type" : "INCREASE",
      "usage_time" : "2015-05-20T13:29:35.120+08:00",
      "reward_usage_serial_no" : "578354",
      "description" : "购买商品",
      "reward_id" : "123456",
      "remark" : "特价商品"
    }, {
      "usage_count" : 100,
      "amount" : 1,
      "usage_type" : "INCREASE",
      "usage_time" : "2015-05-20T13:29:35.120+08:00",
      "reward_usage_serial_no" : "578354",
      "description" : "购买商品",
      "reward_id" : "123456",
      "remark" : "特价商品"
    } ]
  } ]
}
 

    http://2323weixin.qq.com
                                

错误码公共错误码

状态码 错误码 描述 解决方案
500 SYSTEM_ERROR 系统错误 5开头的状态码都为系统问题,请使用相同参数稍后重新调用
400 PARAM_ERROR 参数错误 根据错误提示,传入正确参数
404 RESOURCE_NOT_EXISTS 订单不存在,请检查订单号是否正确 请传入正确的订单号
400 INVALID_REQUEST 请求参数符合参数格式,但不符合业务规则 当前状态无需操作
401 SIGN_ERROR 签名验证失败 请检查签名参数和方法是否都符合签名算法要求
403 NO_AUTH 权限异常 请开通商户号相关权限,请联系产品或商务申请
429 FREQUENCY_LIMITED 请求超过频率限制 请求未受理,请降低频率后重试

版本说明

关闭
V1.1
2020.06.12
1. 优惠和目标结构调整,增加优惠和目标的信息字段;用户优惠记录中的count更名为usage_count;用户目标记录中的count更名为completion_count;
2.增加可选字段sharer_openid;
V1.0
2020.06.04
1. 查询先享卡订单接口上线

技术咨询

反馈有奖