朋友的券-配置库存、充值券点


上一篇 : 朋友的券=创建朋友的券 下一篇: 朋友的券-投放朋友的券



配置库存、充值券点

该部分介绍开发者怎样为card_id配置库存以及充值、管理账号的券点。

1接口说明

创建朋友的券成功后,开发者可以通过接口为card_id配置库存,不同于普通券的是,朋友的券库存须使用券点(
什么是券点?
兑换,券点分为免费券点和付费券点,免费券点由微信平台赠送产生,而付费券点由开发者充值产生。

2接口调用流程

0.png

3API详情

该部分主要介绍库存、券点接口的调用方法和传递参数。

3.1开通券点账户接口

本接口用于开发者为当前appid开通券点账户并获得免费券点奖励

接口调用请求说明

HTTP请求方式: GET https://api.weixin.qq.com/card/pay/activate?access_token=ACCESS_TOKEN

返回数据示例

{"errcode": 0, "errmsg": "ok", "reward": 200}

返回数据示例

参数名 描述
errcode 错误码
errmsg 错误信息
reward 奖励券点数量,以元为单位,微信卡券对每一个新开通券点账户的商户奖励200个券点,点击查看券点规则 什么是券点?

3.2对优惠券批价

本接口用于提前查询本次新增库存需要多少券点

接口调用请求说明

HTTP请求方式: POST https://api.weixin.qq.com/card/pay/getpayprice?access_token=ACCESS_TOKEN

参数说明

参数 是否必须 说明
POST数据 Json数据
access_token 调用接口凭证

POST数据

{"card_id": "pbLatjpQxxxxxxxxCEV_cLTwoB7yU", "quantity": "1"}

请求参数说明

参数名 必填 类型 示例值 描述
card_id string(32) pFS7Fjg8kV1IdDz01r4SQwMkuCKc 需要来配置库存的card_id
quantity int 100 本次需要兑换的库存数目

返回数据示例

{
   "errcode": 0,
   "errmsg": "ok",
   "order_id": "P9zzllX2VJ5NgiF9kFVarX7bc8r-ms_5Dy091evc2eIuxtZvZobeomE1p9Dw8v7lFBhqKM4YgrZa54uuWhf3hw7KquEOfmx5FplGKRIf7Ag5Ww-YdxP-KeT6LeJBttb1xpY0Uf7g8DNHrbUyHopolqfUqPBBLDEmB7Z-91I8",
   "price": "0.2",
   "free_coin": "0.2",
   "pay_coin": "0"
}
参数名 描述
errcode 错误码
errmsg 错误信息
order_id 本次批价的订单号,用于下面的确认充值库存接口,仅对当前订单有效且仅可以使用一次,60s内可用于兑换库存。
price 本次需要支付的券点总额度
free_coin 本次需要支付的免费券点额度
pay_coin 本次需要支付的付费券点额度

注意:

关于券点机制详情请见
什么是券点?

3.2查询券点余额接口

本接口用于开发者查询当前券点账户中的免费券点/付费券点数目以及总额。

接口调用请求说明

HTTP请求方式: GET https://api.weixin.qq.com/card/pay/getcoinsinfo?access_token=ACCESS_TOKEN

返回数据示例

{"errcode": 0,
"errmsg": "ok",
"free_coin": 200
"pay_coin": 1
"total_coin": 201
}

返回参数说明

参数名 描述
errcode 错误码
errmsg 错误信息
free_coin 免费券点数目
pay_coin 免费券点数目
total_coin 全部券点数目

3.3确认兑换库存接口

本接口用于确认兑换库存,确认后券点兑换为库存,过程不可逆。

接口调用请求说明

HTTP请求方式: POST https://api.weixin.qq.com/card/pay/confirm?access_token=ACCESS_TOKEN

参数说明

参数 是否必须 说明
POST数据 Json数据
access_token 调用接口凭证

POST数据

{
   "card_id": "pbLatjpxxxxlCEV_cLTwoB7yU",
   "order_id": "P9zzllX2VJ5NgiF9kFVarX7bc8r-ms_5Dy091evc2eIuxtZvZobeomE1p9Dw8v7lFBhqKM4YgrZa54uuWhf3hw7KquEOfmx5FplGKRIfkbR7Ag5WwYdxP-KeT6LeJBttb1xpYxxxxxxxxxxxxHrbUyHopolqfUqPBBLDEmB7Z-91I8",
   "quantity": "1"
}

请求参数说明

参数名 必填 类型 示例值 描述
card_id string(32) pFS7Fjg8kV1IdDz01r4SQwMkuCKc 需要来兑换库存的card_id
quantity int 100 本次需要兑换的库存数目
order_id string P9zzllX2VJ5NgiF9kFVarX7bc8r 仅可以使用上面得到的订单号,保证批价有效性

返回数据示例

{"errcode":0, "errmsg":"ok"}

参数说明

参数名 描述
errcode 错误码
errmsg 错误信息

特别注意

上一步获得的order_id须在60s内使用,否则确认兑换库存接口将会失效

3.4充值券点接口

开发者可以通过此接口为券点账户充值券点,1元等于1点。开发者调用接口后可以获得一个微信支付的支付二维码链接, 开发者可以将链接转化为二维码扫码支付。

接口调用请求说明

HTTP请求方式: POST https://api.weixin.qq.com/card/pay/recharge?access_token=ACCESS_TOKEN

参数说明

参数 是否必须 说明
POST数据 Json数据
access_token 调用接口凭证

POST数据

{"coin_count": 100}

请求参数说明

参数名 必填 类型 示例值 描述
coin_count int 10000 需要充值的券点数目,1点=1元

返回数据示例

{
   "errcode": 0,
   "errmsg": "ok",
   "order_id": "100005790120***221401000171",
   "qrcode_url": "weixin://wxpay/bizpayurl?pr=xxxxxxxxx",
   "qrcode_buffer": "pwxs*************xxxxxxxxxx"
}
参数名 描述
errcode 错误码
errmsg 错误信息
order_id 本次支付的订单号,用于查询订单状态
qrcode_url 支付二维码的的链接,开发者可以调用二维码生成的公开库转化为二维码显示在网页上,微信扫码支付
qrcode_buffer 二维码的数据流,开发者可以使用写入一个文件的方法显示该二维码

注意:

开发者可以参考以下方法将buffer显示二维码

<?php $file = fopen("test.jpg","w"); echo fwrite(qrcode_buffer); fclose($file); ?>

3.5查询订单详情接口

本接口用于查询充值订单的状态

接口调用请求说明

HTTP请求方式: POST https://api.weixin.qq.com/card/pay/getorder?access_token=ACCESS_TOKEN

参数说明

参数 是否必须 说明
POST数据 Json数据
access_token 调用接口凭证

POST数据

{"order_id": "100005790********401000171"}

请求参数说明

参数名 必填 类型 示例值 描述
order_id int 10000 上一步中获得的订单号,作为一次交易的唯一凭证

返回数据示例

{
   "errcode": 0,
   "errmsg": "ok",
   "order_info": {
       "order_id": "100005790120151221401000171",
       "status": "ORDER_STATUS_FINANCE_SUCC",
       "create_time": 1450712798,
       "pay_finish_time": 1450712905,
       "desc": "微信支付充值",
       "free_coin_count": "0",
       "pay_coin_count": "1",
       "refund_free_coin_count": "0",
       "refund_pay_coin_count": "0",
       "openid": "oWE-GwF1gGoyVVZC5PG6GXd4cKMY",
       "order_type": "ORDER_TYPE_WXPAY"
   }
}

返回数据说明

参数名 描述
errcode 错误码
errmsg 错误信息
order_info 订单信息结构体
order_id 订单号
status 订单状态, ORDER_STATUS_WAITING 等待支付 ORDER_STATUS_SUCC 支付成功 ORDER_STATUS_FINANCE_SUCC 加代币成功 ORDER_STATUS_QUANTITY_SUCC 加库存成功 ORDER_STATUS_HAS_REFUND 已退币 ORDER_STATUS_REFUND_WAITING 等待退币确认 ORDER_STATUS_ROLLBACK 已回退,系统失败 ORDER_STATUS_HAS_RECEIPT 已开发票
create_time 订单创建时间
pay_finish_time 支付完成时间
desc 支付描述,一般为微信支付充值
free_coin_count 本次充值的付费券点数量,以元为单位
pay_coin_count 二维码的数据流,开发者可以使用写入一个文件的方法显示该二维码
refund_free_coin_count 回退的免费券点
refund_pay_coin_count 回退的付费券点
openid 支付人的openid
order_tpye 订单类型,ORDER_TYPE_WXPAY为充值

3.6查询券点流水详情接口

本接口用于查询券点的流水详情。

接口调用请求说明

HTTP请求方式: POSThttps://api.weixin.qq.com/card/pay/getorderlist?access_token=ACCESS_TOKEN

参数说明

参数 是否必须 说明
POST数据 Json数据
access_token 调用接口凭证

POST数据

{
   "offset": 0,
   "count": 5,
   "order_type": "ORDER_TYPE_WXPAY",
   "nor_filter": {
       "status": "ORDER_STATUS_SUCC"
   },
   "sort_info": {
       "sort_key": "SORT_BY_TIME",
       "sort_type": "SORT_DESC"
   },
   "begin_time": "1440420538",
   "end_time": "1450713203"
}

请求参数说明

参数名 必填 类型 示例值 描述
offset int 0 分批查询的起点,默认为0
count int 50 分批查询的数量
begin_time int 14552146398 批量查询订单的起始事件,为时间戳,默认1周前
end_time int 14552146398 批量查询订单的结束事件,为时间戳,默认为当前时间
order_type string ORDER_TYPE_WXPAY 所要拉取的订单类型 ORDER_TYPE_SYS_ADD 平台赠送 ORDER_TYPE_WXPAY 充值 ORDER_TYPE_REFUND 库存回退券点 ORDER_TYPE_REDUCE 券点兑换库存 ORDER_TYPE_SYS_REDUCE 平台扣减
nor_filter JSON结构 ORDER_STATUS_QUANTITY_SUCC 反选,不要拉取的订单
status string ORDER_STATUS_REFUND_WAITING 不要拉取的订单状态 订单状态包括: ORDER_STATUS_WAITING 等待支付 ORDER_STATUS_SUCC 支付成功 ORDER_STATUS_FINANCE_SUCC 加代币成功 ORDER_STATUS_QUANTITY_SUCC 加库存成功 ORDER_STATUS_HAS_REFUND 已退币 ORDER_STATUS_REFUND_WAITING 等待退币确认 ORDER_STATUS_ROLLBACK 已回退,系统失败 ORDER_STATUS_HAS_RECEIPT 已开发票
sort_info JSON结构
对结果排序
sort_key string SORT_BY_TIME 排序依据,SORT_BY_TIME 以订单时间排序
sort_type string SORT_DESC 排序规则,SORT_ASC 升序 SORT_DESC 降序

返回数据示例

{
   "errcode": 0,
   "errmsg": "ok",
   "total_num": 1,
   "order_list": [
       {
           "order_id": "100005790120151221401000171",
           "status": "ORDER_STATUS_FINANCE_SUCC",
           "create_time": 1450712798,
           "pay_finish_time": 1450712905,
           "desc": "微信支付充值",
           "free_coin_count": "0",
           "pay_coin_count": "1",
           "refund_free_coin_count": "0",
           "refund_pay_coin_count": "0",
           "openid": "oWE-GwF1gGoyVVZC5PG6GXd4cKMY",
           "order_type": "ORDER_TYPE_WXPAY"
       }
   ]
}

返回数据说明

参数名 描述
errcode 错误码
errmsg 错误信息
total_num 符合条件的订单总数量
order_list 显示的订单详情列表,根据offset和count来显示
order_id 订单号
status 订单状态, ORDER_STATUS_WAITING 等待支付 ORDER_STATUS_SUCC 支付成功 ORDER_STATUS_FINANCE_SUCC 加代币成功 ORDER_STATUS_QUANTITY_SUCC 加库存成功 ORDER_STATUS_HAS_REFUND 已退币 ORDER_STATUS_REFUND_WAITING 等待退币确认 ORDER_STATUS_ROLLBACK 已回退,系统失败 ORDER_STATUS_HAS_RECEIPT 已开发票
create_time 订单创建时间
pay_finish_time 支付完成时间
desc 支付描述,一般为微信支付充值
free_coin_count 本次充值的付费券点数量,以元为单位
pay_coin_count 二维码的数据流,开发者可以使用写入一个文件的方法显示该二维码
refund_free_coin_count 回退的免费券点
refund_pay_coin_count 回退的付费券点
openid 支付人的openid
order_tpye 订单类型,ORDER_TYPE_WXPAY为充值

3.7券点流水详情事件推送

当券点发生变动时,微信服务器会将本次变动的类型、券点数额以及时间等信息推送给开发者服务器。

详情请见:
券点流水详情事件推送


上一篇 : 朋友的券=创建朋友的券 下一篇: 朋友的券-投放朋友的券