美團(tuán)智能POS機(jī)支付接口接入指南

?支付接口問(wèn)答 ????|???? ?2019-02-26 21:45

第一章 引言

編寫目的

本文檔描述ERP接入美團(tuán)POS調(diào)用收銀、退款、掃碼、打印功能,包括調(diào)用方式、數(shù)據(jù)交互等。為參加項(xiàng)目建設(shè)的美團(tuán)公司以及美團(tuán)授權(quán)的第三方合作方研發(fā)、產(chǎn)品、開發(fā)等相關(guān)人員。該文檔未經(jīng)許可不得外傳。

更新說(shuō)明

  • V0.1 初始化文稿
  • V0.2 整理支付,退款接口,刪除打印接口。打印使用藍(lán)牙打印
  • V0.3 添加定義開始收銀功能的說(shuō)明
  • V0.4 添加設(shè)置打印參數(shù)的接口, 針對(duì)posCashierErp-1.4.jar
  • V1.5 添加預(yù)收款,預(yù)收款完成,預(yù)收款撤銷接口。 請(qǐng)確認(rèn)POSCashier版本是3.3.5之后的版本。

注意事項(xiàng)

  1. 在聯(lián)調(diào)階段使用調(diào)試POS機(jī),對(duì)ERP APP簽名無(wú)要求;真實(shí)商家使用非調(diào)試POS機(jī),ERP APP除自身簽名外,需要交由美團(tuán)做硬件廠商簽名。
  2. 美團(tuán)驗(yàn)券、閃惠功能接入,統(tǒng)一采用美團(tuán)開放平臺(tái)接口或SDK。
  3. 不建議ERP調(diào)用收銀時(shí)指定支付方式,支付方式選擇作為收銀模塊必備功能。

第二章 接入指南

1. 申請(qǐng)AppKey

請(qǐng)聯(lián)系商務(wù)人員申請(qǐng)接入方ID,軟件商通過(guò)創(chuàng)建項(xiàng)目(接入方式注意選擇“調(diào)起POS收銀臺(tái)”)獲得。項(xiàng)目審核通過(guò)后,系統(tǒng)會(huì)自動(dòng)分配,只能是2000--30000之間的號(hào)碼,否則會(huì)無(wú)法交易(創(chuàng)建項(xiàng)目操作指南見https://platform.meituan.com/doc/buffetcourse)。

2. 下載SDK

在下載頁(yè)面下載SDK,包含了一個(gè)Library 和一個(gè)Demo

目錄 說(shuō)明
posCashierErpLib Library, 包含一個(gè)jar文件,導(dǎo)入到自己的工程中
erpDemo Demo 目錄,里面是一些使用的例子

3. 在你的代碼中使用SDK

  1. 導(dǎo)入SDK library到直接的工程中
  2. 在Acitivty或者Framgent中初始化接口對(duì)象, 注意只接受activity和fragment作為參數(shù)

     private ErpApi erpApi;erpApi = ErpApiFactory.createErpApi(this);
    
  3. 使用美團(tuán)Pos功能進(jìn)行收銀 直接在需要收銀的地方,調(diào)用下面的接口,就可以啟動(dòng)美團(tuán)的收銀功能。 我們推薦用戶使用不指定支付類型的方式,美團(tuán)POS在收銀的時(shí)候,會(huì)提供支付類型選擇功能。

                         //不指定支付類型,支付1分錢
                         PayReq payReq = new PayReq();
                         payReq.setCounterNo("款臺(tái)號(hào)");
                         payReq.setOperator("operator");
                         payReq.setErpAppkey(erpKey);
                         payReq.setErpOrderId("");
                         payReq.setTotalFee(1);
                         payReq.setPayType(ERP_PAY_TYPE_NONE);
                         erpApi.pay(payReq);
    
  4. 獲取收銀的的結(jié)果 在 onActivityResult 中添加結(jié)果解析函數(shù)。對(duì)于收銀功能,返回的的結(jié)果會(huì)通過(guò)解析函數(shù)返回一個(gè) PayResp 對(duì)象。 PayResp中包含了返回的結(jié)果。

     @Override
         protected void onActivityResult(int requestCode, int resultCode, Intent data) {
             BaseResp resp = erpApi.handleActivityResult(requestCode, resultCode, data);
             if (resp != null) {
                 if (resp.isSuccess()) {
                     if (resp instanceof PayResp) {
                         //獲取支付結(jié)果
                         payResp = (PayResp) resp;
                     } else if (resp instanceof RefundResp) {
                         //獲取退款結(jié)果
                         RefundResp refundResp = (RefundResp) resp;
                     }
                     showToast("success:" + resp.toString());
                 } else {
                     showToast("failed:" + resp.toString());
                 }
             } else {
                 super.onActivityResult(requestCode, resultCode, data);
             }
         } 
    
  5. 退款功能的工作流程和收銀類似

4. 工作流程說(shuō)明

以收銀為例子

3rd App->>Erp Api: 調(diào)用收銀函數(shù)
Erp Api->>美團(tuán)POS:    啟動(dòng)POS提供的服務(wù)
美團(tuán)POS->>3rd App: onActivityResult 返回收銀結(jié)果
3rd App->>Erp Api: 調(diào)用結(jié)果解析函數(shù)handleActivityResult
Erp Api->>3rd App: 返回解析結(jié)果PayResp

第三章 接口說(shuō)明

用戶需要使用的接口都在 ErpApi.java 里面,每個(gè)接口都有詳細(xì)的說(shuō)明,直接看 ErpApi.java 這個(gè)文件就能獲取詳細(xì)的信息

3.1 服務(wù)返回值處理函數(shù)

    /**
     * 對(duì)服務(wù)的返回值進(jìn)行處理
     * 放在 onActivityResult(int requestCode, int resultCode, Intent data) 里面
     * 用來(lái)處理ERP服務(wù)返回的數(shù)據(jù)。
     *
     * @return BaseResp 返回的數(shù)據(jù), 以支付為例,可以通過(guò)
     * if (resp instanceof PayResp) 來(lái)判斷是否是支付的結(jié)果,然后轉(zhuǎn)換成PayResp獲取支付的結(jié)果。
     *
     */
    BaseResp handleActivityResult(int requestCode, int resultCode, Intent data);

BaseResp參數(shù)說(shuō)明

字段名稱 類型說(shuō)明 描述
isSuccess boolean 是否執(zhí)行成功
getCode int 返回結(jié)果-1:成功;-2:異常,;-3:取消(注意:沒(méi)有采用Activity.RESULT_CANCELED);-4:打印時(shí)紙張異常(缺紙、卡紙)
getMessage String 返回的結(jié)果說(shuō)明信息,一般用在執(zhí)行失敗的情況

3.2 支付接口

    /**
     * 支付接口
     *
     * 在onActivityResult 返回?cái)?shù)據(jù), 返回的數(shù)據(jù),用{@link #handleActivityResult(int, int, Intent)} 進(jìn)行解析
     * @param payReq 指定支付的參數(shù) 參數(shù)的含義參考 {@link com.sankuai.poscashier.erp.model.PayReq}
     * 返回值會(huì)解析成 PayResp的類型。{@link com.sankuai.poscashier.erp.model.PayResp}
     */
    void pay(PayReq payReq);

輸入PayReq參數(shù)說(shuō)明:

  字段名稱 字段類型 是否必須 描述
  totalFee long Y 支付金額(單位“分”)
兼容int類型,推薦用long
 
  payType int N default:0,支付寶:1,微信:2,銀行卡:3,applyPay:4; 建議直接使用默認(rèn)值0,在收銀臺(tái)選擇支付方式  
  erpOrderId String Y erp訂單id,不允許有重復(fù),輔助對(duì)賬用  
  erpAppkey String Y 接入方ID,軟件商通過(guò)創(chuàng)建項(xiàng)目(接入方式注意選擇“調(diào)起POS收銀臺(tái)”)獲得。項(xiàng)目審核通過(guò)后,系統(tǒng)會(huì)自動(dòng)分配,只能是2000--30000之間的號(hào)碼,否則會(huì)無(wú)法交易(創(chuàng)建項(xiàng)目操作指南見https://platform.meituan.com/doc/buffetcourse)。  
  operator String N 支付時(shí)的外部操作員  
  counterNo String N 款臺(tái)號(hào)  

在onActivityResult中返回的值PayResp說(shuō)明:

字段 類型 描述
payType int 支付類型支付類型 payType, 值參考支付類型定義
traceNo String 流水號(hào)
batchNo String 批次號(hào)
referNo String 參考號(hào)
cardNo String 銀行卡支付的卡號(hào)
buyerId String 微信支付寶支付的時(shí)候,獲取用戶ID
cardId String 內(nèi),外卡的標(biāo)記
orderId String 美團(tuán)內(nèi)部的訂單號(hào),撤銷和預(yù)收款完成的時(shí)候需要使用,建議記錄下來(lái),可以使用orderID退款

3.3 退款,預(yù)收款撤銷接口

    /**
     * 退款,預(yù)收款撤銷接口
     *
     * @param refundReq 退貨的參數(shù) {@link com.sankuai.poscashier.erp.model.RefundReq}
     * 在onActivityResult 返回?cái)?shù)據(jù), 返回的數(shù)據(jù),用{@link #handleActivityResult(int, int, Intent)} 進(jìn)行解析
     * 返回值會(huì)解析成 RefundResp的類型。{@link com.sankuai.poscashier.erp.model.RefundResp}
     */
    void refund(RefundReq refundReq);

退款參數(shù)RefundReq說(shuō)明

字段 類型 是否必須 描述
amount long Y 退款金額 以分為單位
payType int Y 支付類型,參考支付類型定義
batchNo String Y 批次號(hào)(來(lái)源于支付接口)
traceNo String Y 流水號(hào)(來(lái)源于支付接口)
orderId String N 訂單號(hào),來(lái)源于支付接口。如果有訂單號(hào),強(qiáng)烈建議使用訂單號(hào)來(lái)退款,訂單號(hào)退款可以避免對(duì)本地?cái)?shù)據(jù)的依賴。如果有了這個(gè)字段,batchNo和traceNo可以不傳。退款的是會(huì)根據(jù)訂單號(hào)從服務(wù)器獲取訂單詳情,然后根據(jù)詳情來(lái)退款。注意:預(yù)收款撤銷,目前只支持使用orderId
operator String N 操作員打印簽購(gòu)單的時(shí)候使用,可以為null,如果是null,就不會(huì)打印對(duì)應(yīng)的字段
counterNo String N 款臺(tái)號(hào) 打印簽購(gòu)單的時(shí)候使用,可以為null,如果是null,就不會(huì)打印對(duì)應(yīng)的字段

在onActivityResult中返回的值RefundResp說(shuō)明: 同BaseResp的說(shuō)明

3.4 掃碼接口

/**
* 掃碼接口
* 掃碼支持前置、后置攝像頭,默認(rèn)采用前置攝像頭。暫不對(duì)ERP APP開放,可在掃碼頁(yè)面切換。
* 在onActivityResult 返回?cái)?shù)據(jù)
*/
public abstract void scan();

3.5 其他接口

/**
* 判斷是否是美團(tuán)POS機(jī)
*/
public static boolean ErpUtil.isMTPos();

3.6 設(shè)置打印參數(shù)

    /**
     * 設(shè)置參數(shù)
     *
     * 主要是針對(duì)一些特殊的自定義需求,大部分ERP對(duì)接都用不到.
     * 在這里目前可以使設(shè)置操作員號(hào)和款臺(tái)號(hào),在打印小票的時(shí)候會(huì)打印出這兩個(gè)字段。 這個(gè)地方設(shè)置的參數(shù)會(huì)一直保存在
     * pos機(jī)中,需要使用方去控制什么時(shí)候清除、修改數(shù)據(jù)。 比如設(shè)置了操作員號(hào)和款臺(tái)號(hào)之后,打印會(huì)一直打印這兩個(gè)字段,
     * 直到使用方主動(dòng)去清除數(shù)據(jù),或者修改數(shù)據(jù)。
     *
     * @param setParameterReq
     */
    void setParameter(SetParameterReq setParameterReq );

3.7 預(yù)收款

    /**
     * 預(yù)收款
     *
     * @param preAuthReq 參數(shù)含義 {@link com.sankuai.poscashier.erp.model.PreAuthReq}
     * 返回值會(huì)解析成PreAuthResp的格式
     */
    void preAuth(PreAuthReq preAuthReq);

輸入PreAuthReq參數(shù)說(shuō)明:

字段 類型 是否必須 描述
totalFee long Y 支付金額(單位“分”)
payType int Y 支付寶:1,微信:2, 目前只支持支付寶和微信
erpOrderId String Y erp訂單id,不允許有重復(fù),輔助對(duì)賬用
erpAppkey String Y erp app唯一標(biāo)識(shí)

在onActivityResult中返回的值PreAuthResp說(shuō)明:

字段 類型 描述
payType int 支付類型支付類型 payType, 值參考支付類型定義
traceNo String 流水號(hào)
batchNo String 批次號(hào)
referNo String 參考號(hào)
orderId String 美團(tuán)內(nèi)部的訂單號(hào),撤銷和預(yù)收款完成的時(shí)候需要使用,請(qǐng)記錄下來(lái)
buyerId String 微信支付寶支付的時(shí)候,獲取用戶ID

3.8 預(yù)收款完成

    /**
     * 預(yù)收款完成
     *
     * @param preAuthCompleteReq {@link com.sankuai.poscashier.erp.model.PreAuthCompleteReq}
     * 返回值會(huì)解析成 PreAuthCompleteResp
     */
    void preAuthComplete(PreAuthCompleteReq preAuthCompleteReq);

輸入PreAuthCompleteReq參數(shù)說(shuō)明:

字段 類型 是否必須 描述
totalFee long Y 預(yù)收款完成的金額(單位分)
orderId String Y 美團(tuán)的訂單號(hào),在預(yù)收款的時(shí)候返回的值
erpAppkey String Y 接入方ID

在onActivityResult中返回的值PreAuthCompleteResp說(shuō)明:

字段 類型 描述
payType int 支付類型支付類型 payType, 值參考支付類型定義
traceNo String 流水號(hào)
batchNo String 批次號(hào)
referNo String 參考號(hào)
orderId String 美團(tuán)內(nèi)部的訂單號(hào)
buyerId String 微信支付寶支付的時(shí)候,獲取用戶ID
totalFee long 預(yù)收款完成的金額(單位分)

3.9 預(yù)收款撤銷

這個(gè)和退款是同一個(gè)接口,請(qǐng)參考退款接口

第四章 其他說(shuō)明

如何把launcher上的收銀臺(tái)啟動(dòng)項(xiàng)替換成自己的Activity

第三方開發(fā)的收銀APP,只要在對(duì)應(yīng)的Activity做如下聲明:

<intent-filter>
<action android:name="com.sankuai.poscashier.action.CASHIER"/>
<category android:name="android.intent.category.DEFAULT"/>
</intent-filter>

點(diǎn)擊“開始收銀”啟動(dòng)收銀臺(tái)的時(shí)候,就會(huì)優(yōu)先啟動(dòng)第三方聲明的Activity

###支付類型定義

名稱 說(shuō)明
ERP_PAY_TYPE_NONE 0 沒(méi)有指定支付類型
ERP_PAY_TYPE_ALI 1 支付寶支付
ERP_PAY_TYPE_WEIXIN 2 微信支付
ERP_PAY_TYPE_BANK 3 銀行卡支付
ERP_PAY_TYPE_APPLE 4 Apple apy

內(nèi)卡,外卡定義說(shuō)明

國(guó)際信用卡公司中文 國(guó)際信用卡公司英文 3位代碼
銀聯(lián)卡 China Union Pay CUP
威士卡 VISA VIS
萬(wàn)事達(dá)卡 Master Card MCC
萬(wàn)事達(dá)卡 Maestro Card MAE
JCB卡 JCB JCB
大來(lái)卡 Dinner Club DCC
運(yùn)通卡 American Express AMX

如何獲取設(shè)備sn

設(shè)備sn其實(shí)就是 android.os.Build.SERIAL 這個(gè)值


轉(zhuǎn)載請(qǐng)備注文章來(lái)自:http://m.ssll180.com/zhifujiekou/1061.html

您的轉(zhuǎn)發(fā)對(duì)我們很重要

?


【免責(zé)聲明】本站對(duì)文中陳述、觀點(diǎn)判斷保持中立,不對(duì)所包含內(nèi)容的準(zhǔn)確性、可靠性或完整性提供任何明示或暗示的保證,目的在于傳遞更多信息。

看了以上文章的44.75%用戶還看了以下內(nèi)容:


看了以上文章的26.02%用戶還在看以下內(nèi)容:


看了以上文章的16.43%用戶還看了以下內(nèi)容:




POS機(jī)網(wǎng)文章上一篇:支付安全知識(shí) ;POS機(jī)網(wǎng)文章下一篇:支付寶支付接口測(cè)試