淺析微信支付:公眾平臺卡券功能開通、HTML5線上發券(JS-SDK介面)、檢視卡券詳情

YClimb發表於2018-12-04

本文是【淺析微信支付】系列文章的第十六篇,主要講解如何使用微信公眾平臺的卡券功能、如何使用HTML5在網頁展示使用者領券以及微信卡券和商戶平臺代金券的關係。


淺析微信支付系列已經更新十六篇了喲~,沒有看過的朋友們可以看一下哦。

淺析微信支付:開通免充值產品功能及如何進行介面升級指引

淺析微信支付:商戶平臺代金券或立減優惠開通、指定使用者代金券發放、查詢等

淺析微信支付:商戶平臺開通現金紅包、指定使用者發放、紅包記錄查詢

淺析微信支付:支付驗收示例和驗收指引

淺析微信支付:如何使用沙箱環境測試

前幾篇文章主要介紹瞭如何在【微信商戶平臺】使用代金券和滿減優惠折扣等產品功能,有不少小夥伴說到,【微信公眾平臺】也有一個卡券功能,那麼他們有什麼差別呢?這個卡券功能該如何使用?本文會給大家一個解釋。

兩者的差別

首先,我們來解釋商戶平臺和微信平臺各自優惠券的區別,如果有人試過,那麼應該知道,兩者是不通用的,不通用的,不通用的!!!

至於這裡要重點標識不通用?因為在開通微信卡券功能後,在商戶平臺也會出現微信卡券對應優惠券資訊,雖然沒有發券的功能,只是展示,但如果我們走介面發券,就會出現 發券失敗,不支援傳送xxx型別的優惠券 的錯誤,這時就尷尬了;

還沒完,因為平臺不同,所以微信卡券和支付優惠券傳送、領取的方式(介面)也是不同的,包括使用者領取時跳轉到的頁面也不相同,這個也請大家注意。

所以,我們需要將這兩種券作為兩種不同種類的券來處理就可以了。

公眾平臺卡券功能開通

登陸公眾平臺 https://mp.weixin.qq.com,點選左側[功能-新增功能外掛],進入外掛庫頁面,進入[卡券功能],可以開通卡券功能。

申請條件: 必須開通微信支付功能!!!!

功能介紹: 卡券功能,是提供給商戶或第三方的一套派發優惠券,經營管理會員的工具,可在公眾平臺或通過介面建立卡券,多種渠道投放給使用者,使用者用券時需核銷卡券,核銷後可檢視資料、進行對賬。

主要能力:

●朋友共享的優惠券——可利用社交鏈快速擴散傳播,一人領券,本人和朋友皆可看到並使用。檢視視訊介紹

●普通優惠券——傳統優惠券電子版,領取後僅本人可見可用,支援多種型別:折扣券、代金券、兌換券、團購券、優惠券。

●會員卡——支援折扣、積分等玩法,並提供會員管理、資料包表等豐富工具,便於商戶高效運營會員。

●微信買單——無需進行微信支付開發,同時與會員卡,代金券,折扣券打通,為你積累使用者消費資料,用於經營參考

●儲值功能——會員卡商戶無需申請,可直接通過API介面,使用“餘額展示”功能,將會員餘額顯示在微信會員卡首頁。具有預付卡資質的商家可申請“儲值”功能,申請成功後,可通過API介面設定此入口,幫助會員通過微信支付為會員卡充值。

●第三方代制模式——經商戶授權後,可代子商戶快速接入並使用卡券功能,支援通過公眾平臺或API介面實現該功能。

官方開發文件地址:

https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421141229
複製程式碼

這裡就已知小夥伴們已經開通卡券功能,如何手動建立優惠券可以在公眾平臺上操作,很簡單,這裡就不說了,本文主要講如何使用介面的方式來建立卡券、使用者領取、查詢卡券詳情。

微信卡券指引

官方文件地址:

https://mp.weixin.qq.com/cgi-bin/readtemplate?t=cardticket/faq_tmpl&type=info&token=&lang=zh_CN#0
複製程式碼

下面是卡券功能開通指引對應的申請渠道、申請條件:

卡券功能開通指引

有需要的小夥伴可以通讀一下上面官方文件,讀完之後就會對微信卡券有所認識了,差不多基礎業務都能做到心中有數咯。

如果是開發者,直接看下面微信卡券介面文件就行,畢竟我們更關心介面相關的資訊,官方文件如下:

https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421141229
複製程式碼

下載卡券資料包:

https://mp.weixin.qq.com/zh_CN/htmledition/comm_htmledition/res/cardticket/wx_card_document.zip?token=&lang=zh_CN
複製程式碼

根據官方文件的步驟,需要整整七步,下面為具體步驟:

  1. 獲取access_token
  2. 上傳卡券logo
  3. 建立卡券
  4. 建立二維碼投放
  5. 顯示二維碼
  6. 設定測試白名單
  7. 核銷卡劵

官方的文件主要是使用了沙箱測試賬號來測試並驗證,關於介面測試號申請可以通過以下連結來取得:

https://mp.weixin.qq.com/debug/cgi-bin/sandbox?t=sandbox/login
複製程式碼

下面我們來一步步分析介面。

獲取access_token

頁面地址:http://mp.weixin.qq.com/debug/

介面型別:基礎支援

介面列表:獲取access_token介面

注意事項:引數填寫開發者的appid和secret

點選檢查問題,即可返回access_token,access_token的有效期是兩小時,兩小時之後須重新獲取

介面地址:獲取access_token介面 https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140183

這裡的獲取微信全域性access_token介面就不講了,能看到這篇文章的小夥伴應該早就寫過了,哈哈哈。

上傳卡券logo

頁面地址:http://mp.weixin.qq.com/debug/

介面型別:基礎支援

介面列表:上傳圖片素材介面

access_token: 上一步獲得的access_token

buffer:你選擇的圖片

點選檢查問題,即可獲取圖片url,在下一步建立卡劵的引數中需要

介面地址:上傳圖片介面 https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1451025056

此介面就是上傳商戶logo,可以獲得一個卡券logo連結,基本上就用一次,如果不想使用此介面來上傳logo,可以在公眾平臺手動建立優惠券時上傳logo,上傳後可以在logo圖片上滑鼠右鍵-複製圖片路徑,也是一樣的(不想調介面的可以用這個歪招哈哈哈哈)。

建立卡券

頁面地址:http://mp.weixin.qq.com/debug/

介面型別:卡劵介面

介面列表:建立卡劵介面

access_token:第一步獲得的access_token

建立卡券介面地址:

https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1451025056
複製程式碼

以下為呼叫介面示例:

https://api.weixin.qq.com/card/create?access_token=xxx
複製程式碼

JSON示例:

{
    "card": {
        "card_type": "CASH", 
        "cash": {
            "base_info": {
                "logo_url": "https://mmbiz.qlogo.cn/mmbiz_png/E5Q3G4ku9nf7UiafOetcAPLyfia7kdWWWauHukNN7ZXnggtZcTzEPGa8IUDiaLIv14EkNdPvmbCFyHibh0G8tia7Eibw/0?wx_fmt=png", // 此處是上傳logo的圖片地址
                "pay_info": {
                    "swipe_card": {
                        "use_mid_list": [
                            "xxx" // 商戶號
                        ], 
                        "create_mid": "xxx", // 商戶號
                        "is_swipe_card": true
                    }
                }, 
                "brand_name": "測試代金券", 
                "code_type": "CODE_TYPE_NONE", 
                "title": "111", 
                "color": "Color090",  // 主題顏色
                "service_phone": "18888888888", 
                "description": "不可與其他優惠同享如需團購券發票,請在消費時向商戶提出", 
                "date_info": {
                    "type": "DATE_TYPE_FIX_TIME_RANGE", 
                    "begin_timestamp": 1536768000,  // 開始時間
                    "end_timestamp": 1536940800 // 結束時間
                }, 
                "can_share": false, 
                "center_title": "立即使用", 
                "center_app_brand_user_name": "gh_7195ea80d2e6@app", 
                "center_app_brand_pass": "pages/index/index", 
                "can_give_friend": false, 
                "sku": {
                    "quantity": 500000
                }, 
                "get_limit": 30, 
                "custom_url_name": "立即使用", 
                "custom_url": "http://www.qq.com", 
                "custom_url_sub_title": "6個漢字tips", 
                "promotion_url_name": "更多優惠", 
                "promotion_url": "http://www.qq.com"
            }, 
            "advanced_info": {
                "use_condition": {
                    "accept_category": "鞋類", 
                    "reject_category": "阿迪達斯", 
                    "can_use_with_other_discount": true, 
                    "least_cost": "51"
                }, 
                "abstract": {
                    "abstract": "微信餐廳推出多種新季菜品,期待您的光臨", 
                    "icon_url_list": [
                        "http://mmbiz.qpic.cn/mmbiz/p98FjXy8LacgHxp3sJ3vn97bGLz0ib0Sfz1bjiaoOYA027iasqSG0sjpiby4vce3AtaPu6cIhBHkt6IjlkY9YnDsfw/0"
                    ]
                }, 
                "text_image_list": [
                    {
                        "image_url": "http://mmbiz.qpic.cn/mmbiz/p98FjXy8LacgHxp3sJ3vn97bGLz0ib0Sfz1bjiaoOYA027iasqSG0sjpiby4vce3AtaPu6cIhBHkt6IjlkY9YnDsfw/0", 
                        "text": "此菜品精選食材,以獨特的烹飪方法,最大程度地刺激食 客的味蕾"
                    }, 
                    {
                        "image_url": "http://mmbiz.qpic.cn/mmbiz/p98FjXy8LacgHxp3sJ3vn97bGLz0ib0Sfz1bjiaoOYA027iasqSG0sj piby4vce3AtaPu6cIhBHkt6IjlkY9YnDsfw/0", 
                        "text": "此菜品迎合大眾口味,老少皆宜,營養均衡"
                    }
                ], 
                "time_limit": [
                    {
                        "type": "MONDAY", 
                        "begin_hour": 0, 
                        "end_hour": 10, 
                        "begin_minute": 10, 
                        "end_minute": 59
                    }, 
                    {
                        "type": "HOLIDAY"
                    }
                ], 
                "business_service": [
                    "BIZ_SERVICE_FREE_WIFI", 
                    "BIZ_SERVICE_WITH_PET", 
                    "BIZ_SERVICE_FREE_PARK", 
                    "BIZ_SERVICE_DELIVER"
                ]
            }, 
            "reduce_cost": 5
        }
    }
}
複製程式碼

通過以上介面和引數可以建立一個優惠券資訊,json示例也可以使用官方的,這裡有幾個問題需要重點說一下:

  1. use_mid_list 商戶號需要填寫本商戶的
  2. color 顏色可以根據文件中選擇
  3. begin_timestamp、end_timestamp 這兩個時間非常重要,首先結束時間必須大於開始時間,並且需要大於一定的限度,測試時最好跨度大於一天;還需要注意的是時間格式必須是10位數值,例如:1536768000,其他格式會報錯。
  4. time_limit 下的值根據文件中的要求填寫
  5. sku、get_limit 引數按要求填寫
  6. logo_url 使用微信官方的logo圖片地址

注意事項:date_info中用的是Unix時間戳,注意把begin_timestamp修改小於當前時間,end_timestamp修改成今天之後的時間,這樣在後面核銷卡劵測試才能成功

建立二維碼投放

頁面地址:mp.weixin.qq.com/debug

介面型別:卡劵介面

介面列表:建立二維碼ticket介面

access_token:第一步獲得的access_token

介面文件地址:

https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1451025062
複製程式碼

介面呼叫示例:

https://api.weixin.qq.com/card/qrcode/create?access_token=TOKEN
複製程式碼

json引數:

{
    "action_name":"QR_CARD",
    "expire_seconds":1800,
    "action_info":{
        "card":{
            "card_id":"pFS7Fjg8kV1IdDz01r4SQwMkuCKc",
            "code":"198374613512",
            "openid":"oFS7Fjl0WsZ9AMZqrI80nbIq8xrA",
            "is_unique_code":false,
            "outer_str":"12b"
        }
    }
}
複製程式碼

顯示二維碼

在上一步的返回中點選欄位show_qrcode_url欄位中的連結,即可顯示卡券領取二維碼。 開啟微信掃一掃,然後領取卡劵,如果顯示卡劵未通過稽核,那麼需要下一步設定測試白名單,如果可以領取就忽略第六步。

設定測試白名單

文件地址:

https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1451025062
複製程式碼

核銷卡劵

文件地址:

https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1451025239
複製程式碼

注意事項:僅支援稽核通過且在有效期內的卡劵

HTML5網頁發券(JS-SDK)

上面通過二維碼發券的方式,我覺得官方文件已經解釋清楚了,且介面也比較簡單,所以這裡就不贅述,主要需要講的是這裡的 HTML5網頁發券(JS-SDK),官方文件連結如下:

https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1451025062
複製程式碼

HTML5線上發券(JS-SDK介面)

看了上面的圖,小夥伴大概知道是什麼意思了吧,簡單點說,就是使用者在咋們系統H5中點選按鈕,可以彈出微信官方的領取優惠券介面,官方的頁面是微信提供的,我們無需開發,只需要關注如何呼叫官方的方法即可。

官方解釋如下:微信提供的addCard介面供商戶前端網頁呼叫,用於將一張或多張卡券新增到使用者卡包

介面地址如下(在以下頁面搜尋addCard即可直達):

https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421141115
複製程式碼

批量新增卡券介面

上面是新增卡券的介面,我們重點關注這幾個引數:

  1. cardId:卡券ID,如果是商戶平臺,則是批次ID
  2. cardExt:卡券的擴充套件引數。需進行 JSON 序列化為字串傳入
  3. cardExt>openid:指定領取者的 openid,只有該使用者能領取。 bind_openid 欄位為 true 的卡券必須填寫,bind_openid 欄位為 false 不可填寫。
  4. cardExt>code:使用者領取的 code,僅自定義 code 模式的卡券須填寫,非自定義 code 模式卡券不可填寫
  5. cardExt>nonce_str:隨機字串,由開發者設定傳入,加強安全性(若不填寫可能被重放請求)。隨機字串,不長於 32 位。推薦使用大小寫字母和數字,不同新增請求的 nonce_str 須動態生成,若重複將會導致領取失敗。
  6. cardExt>signature:簽名,商戶將介面列表中的引數按照指定方式進行簽名,簽名方式使用 SHA1,具體簽名方案參見:卡券簽名
  7. cardExt>timestamp:時間戳,東八區時間,UTC+8,單位為秒
  8. cardExt>outer_str:領取渠道引數,用於標識本次領取的渠道值。
  9. cardExt>fixed_begintimestamp:卡券在第三方系統的實際領取時間,為東八區時間戳(UTC+8,精確到秒)。當卡券的有效期類為 DATE_TYPE_FIX_TERM 時專用,標識卡券的實際生效時間,用於解決商戶系統內起始時間和領取微信卡券時間不同步的問題。

根據代金券批次ID得到組合的cardList

首先,獲取cardList介面需要先獲取access_token,再獲取api_ticket,最後組裝成想要的集合,下面是示例程式碼。

根據代金券批次ID得到組合的cardList:

/**
 * 根據代金券批次ID得到組合的cardList
 *
 * @param cardId 卡包ID
 * @return cardList
 * @author yclimb
 * @date 2018/9/21
 */
public JSONArray getCardList(String cardId) {
    if (StringUtils.isBlank(cardId)) {
        return null;
    }
    try {

        // 獲取[商戶名稱]公眾號的 access_token
        String accessToken = this.getAccessToken(WXConstants.WX_MINI_PROGRAM_CODE);
        String timestamp = String.valueOf(WXPayUtil.getCurrentTimestamp());
        String nonce_str = WXPayUtil.generateNonceStr();

        // 卡券的擴充套件引數。需進行 JSON 序列化為字串傳入
        JSONObject cardExt = new JSONObject();
        //cardExt.put("code", "");
        //cardExt.put("openid", "");
        //cardExt.put("fixed_begintimestamp", "");
        //cardExt.put("outer_str", "");
        cardExt.put("timestamp", timestamp);
        cardExt.put("nonce_str", nonce_str);

        /**
         * 1.將 api_ticket、timestamp、card_id、code、openid、nonce_str的value值進行字串的字典序排序。
         * 2.將所有引數字串拼接成一個字串進行sha1加密,得到signature。
         * 3.signature中的timestamp,nonce欄位和card_ext中的timestamp,nonce_str欄位必須保持一致。
         */
        Map<String, String> map = new HashMap<>(8);
        //map.put("code", "");
        //map.put("openid", "");
        map.put("api_ticket", this.getWxCardApiTicket(accessToken));
        map.put("timestamp", timestamp);
        map.put("card_id", cardId);
        map.put("nonce_str", nonce_str);
        cardExt.put("signature", WXPayUtil.SHA1(WXPayUtil.dictionaryOrder(map, 2)));

        // 卡券物件
        JSONObject cardInfo = new JSONObject();
        cardInfo.put("cardId", cardId);
        cardInfo.put("cardExt", cardExt.toJSONString());

        // 需要新增的卡券列表
        JSONArray cardList = new JSONArray(1);
        cardList.add(cardInfo);

        return cardList;
    } catch (Exception e) {
        WXPayUtil.getLogger().error(e.getMessage(), e);
    }
    return null;
}
複製程式碼

獲取微信全域性accessToken:

/**
 * 獲取微信全域性accessToken
 *
 * @param code 標識
 * @return accessToken
 */
public String getAccessToken(String code) {

    // 取redis資料
    String key = WXConstants.WECHAT_ACCESSTOKEN + code;
    String accessToken = (String) redisTemplate.opsForValue().get(key);
    if (accessToken != null) {
        return accessToken;
    }

    // 通過介面取得access_token
    JSONObject jsonObject = restTemplate.getForObject(MessageFormat.format(WXURL.BASE_ACCESS_TOKEN, WXPayConstants.APP_ID, WXPayConstants.SECRET), JSONObject.class);
    String token = (String) jsonObject.get("access_token");
    if (StringUtils.isNotBlank(token)) {
        // 儲存redis
        redisTemplate.opsForValue().set(key, token, 7000, TimeUnit.SECONDS);
        return token;
    } else {
        log.error("獲取微信accessToken出錯,微信返回資訊為:[{}]", jsonObject.toString());
    }
    return null;
}
複製程式碼

獲取卡券 api_ticket 的 api:

/**
 * 獲取卡券 api_ticket 的 api
 * 請求路徑:https://api.weixin.qq.com/cgi-bin/ticket/getticket?access_token={0}&type=wx_card
 *
 * @param access_token token
 * @return api_ticket json obj
 * @author yclimb
 * @date 2018/9/21
 */
public String getWxCardApiTicket(String access_token) {
    if (StringUtils.isBlank(access_token)) {
        return null;
    }
    try {

        // redis key
        String redisKey = RedisKeyUtil.keyBuilder(RedisKeyEnum.IMALL_WXCARD_APITICKET, access_token);

        // 從redis中獲取快取
        Object obj = redisTemplate.opsForValue().get(redisKey);
        if (obj != null) {
            return obj.toString();
        }

        // 獲取卡券 api_ticket
        String api_ticket = restTemplate.getForObject(WXURL.BASE_API_TICKET, String.class, access_token);
        WXPayUtil.getLogger().info("getWxCardApiTicket:api_ticket:{}", api_ticket);
        if (StringUtils.isBlank(api_ticket)) {
            return null;
        }
        JSONObject jsonObject = JSON.parseObject(api_ticket);
        if (0 != jsonObject.getIntValue("errcode")) {
            return null;
        }

        // 設定到redis中,下次取直接拿快取即可,防止多次生成
        String ticket = jsonObject.getString("ticket");
        redisTemplate.opsForValue().set(redisKey, ticket, jsonObject.getIntValue("expires_in"), TimeUnit.SECONDS);

        return ticket;
    } catch (Exception e) {
        WXPayUtil.getLogger().error(e.getMessage(), e);
    }
    return null;
}
複製程式碼

以上程式碼可以獲取cardList,將此引數替換到微信官方方法中即可喚起領券頁面;需要注意的是,公眾平臺和商戶平臺的券領取的方式不同,這裡是以公眾平臺為例子,如果小夥伴要用商戶平臺這樣為使用者發券,是無法成功的喲。

檢視卡券詳情

開發者可以呼叫該介面查詢某個card_id的建立資訊、稽核狀態以及庫存數量。

介面呼叫:

HTTP請求方式:POST
URL:https://api.weixin.qq.com/card/get?access_token=TOKEN
引數:card_id,卡券ID
複製程式碼

介面文件(進入連結後查詢 檢視卡券詳情 可快速定位):

https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1451025272
複製程式碼

此介面官方介紹已經很詳細,這裡就不細講了,大家參考官方文件即可。

結語

以上為微信公眾平臺-卡券功能相關的解釋和原始碼,小夥伴們一定要注意看看官方文件哦,具體的原始碼可以看作者的github,裡面對每個方法有詳細的註釋。

如果小夥伴有遇到解決不了的問題,可以關注作者微信公眾號,加入討論群中發出疑問,和小夥伴們一起解決哦~

預告:下一篇文章會講發放獎勵的另一種方式 公眾平臺-社交立減金活動,敬請期待!!!

​如果想要提前一覽原始碼的小夥伴,可以先看看我的 github,地址如下: ​ ​​https://github.com/YClimb/wxpay-sdk/blob/master/README.md ​

關注作者微信公眾號,點選下方討論群,掃碼即可加入微信支付討論群與小夥伴一起探討哦~

到此本文就結束了,關注公眾號檢視更多推送!!!


關注我的公眾號


相關文章