美團智能POS機支付接口接入指南

?支付接口問答 ????|???? ?2019-02-26 21:45

第一章 引言

編寫目的

本文檔描述ERP接入美團POS調用收銀、退款、掃碼、打印功能,包括調用方式、數據交互等。為參加項目建設的美團公司以及美團授權的第三方合作方研發、產品、開發等相關人員。該文檔未經許可不得外傳。

更新說明

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

注意事項

  1. 在聯調階段使用調試POS機,對ERP APP簽名無要求;真實商家使用非調試POS機,ERP APP除自身簽名外,需要交由美團做硬件廠商簽名。
  2. 美團驗券、閃惠功能接入,統一采用美團開放平臺接口或SDK。
  3. 不建議ERP調用收銀時指定支付方式,支付方式選擇作為收銀模塊必備功能。

第二章 接入指南

1. 申請AppKey

請聯系商務人員申請接入方ID,軟件商通過創建項目(接入方式注意選擇“調起POS收銀臺”)獲得。項目審核通過后,系統會自動分配,只能是2000--30000之間的號碼,否則會無法交易(創建項目操作指南見https://platform.meituan.com/doc/buffetcourse)。

2. 下載SDK

在下載頁面下載SDK,包含了一個Library 和一個Demo

目錄 說明
posCashierErpLib Library, 包含一個jar文件,導入到自己的工程中
erpDemo Demo 目錄,里面是一些使用的例子

3. 在你的代碼中使用SDK

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

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

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

     @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) {
                         //獲取支付結果
                         payResp = (PayResp) resp;
                     } else if (resp instanceof RefundResp) {
                         //獲取退款結果
                         RefundResp refundResp = (RefundResp) resp;
                     }
                     showToast("success:" + resp.toString());
                 } else {
                     showToast("failed:" + resp.toString());
                 }
             } else {
                 super.onActivityResult(requestCode, resultCode, data);
             }
         } 
    
  5. 退款功能的工作流程和收銀類似

4. 工作流程說明

以收銀為例子

3rd App->>Erp Api: 調用收銀函數
Erp Api->>美團POS:    啟動POS提供的服務
美團POS->>3rd App: onActivityResult 返回收銀結果
3rd App->>Erp Api: 調用結果解析函數handleActivityResult
Erp Api->>3rd App: 返回解析結果PayResp

第三章 接口說明

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

3.1 服務返回值處理函數

    /**
     * 對服務的返回值進行處理
     * 放在 onActivityResult(int requestCode, int resultCode, Intent data) 里面
     * 用來處理ERP服務返回的數據。
     *
     * @return BaseResp 返回的數據, 以支付為例,可以通過
     * if (resp instanceof PayResp) 來判斷是否是支付的結果,然后轉換成PayResp獲取支付的結果。
     *
     */
    BaseResp handleActivityResult(int requestCode, int resultCode, Intent data);

BaseResp參數說明

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

3.2 支付接口

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

輸入PayReq參數說明:

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

在onActivityResult中返回的值PayResp說明:

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

3.3 退款,預收款撤銷接口

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

退款參數RefundReq說明

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

在onActivityResult中返回的值RefundResp說明: 同BaseResp的說明

3.4 掃碼接口

/**
* 掃碼接口
* 掃碼支持前置、后置攝像頭,默認采用前置攝像頭。暫不對ERP APP開放,可在掃碼頁面切換。
* 在onActivityResult 返回數據
*/
public abstract void scan();

3.5 其他接口

/**
* 判斷是否是美團POS機
*/
public static boolean ErpUtil.isMTPos();

3.6 設置打印參數

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

3.7 預收款

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

輸入PreAuthReq參數說明:

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

在onActivityResult中返回的值PreAuthResp說明:

字段 類型 描述
payType int 支付類型支付類型 payType, 值參考支付類型定義
traceNo String 流水號
batchNo String 批次號
referNo String 參考號
orderId String 美團內部的訂單號,撤銷和預收款完成的時候需要使用,請記錄下來
buyerId String 微信支付寶支付的時候,獲取用戶ID

3.8 預收款完成

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

輸入PreAuthCompleteReq參數說明:

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

在onActivityResult中返回的值PreAuthCompleteResp說明:

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

3.9 預收款撤銷

這個和退款是同一個接口,請參考退款接口

第四章 其他說明

如何把launcher上的收銀臺啟動項替換成自己的Activity

第三方開發的收銀APP,只要在對應的Activity做如下聲明:

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

點擊“開始收銀”啟動收銀臺的時候,就會優先啟動第三方聲明的Activity

###支付類型定義

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

內卡,外卡定義說明

國際信用卡公司中文 國際信用卡公司英文 3位代碼
銀聯卡 China Union Pay CUP
威士卡 VISA VIS
萬事達卡 Master Card MCC
萬事達卡 Maestro Card MAE
JCB卡 JCB JCB
大來卡 Dinner Club DCC
運通卡 American Express AMX

如何獲取設備sn

設備sn其實就是 android.os.Build.SERIAL 這個值


轉載請備注文章來自:http://www.setsauna.com/zhifujiekou/1061.html

您的轉發對我們很重要

?


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

看了以上文章的44.75%用戶還看了以下內容:


看了以上文章的26.02%用戶還在看以下內容:


看了以上文章的16.43%用戶還看了以下內容:




POS機網文章上一篇:支付安全知識 ;POS機網文章下一篇:支付寶支付接口測試