NAV

一碼付 APP 手冊

訂單掃碼(特約商店傳入QRCode)

產出QRCode之容錯率請使用 : L(7%)

範例

{
  "storeUid": "289151880009",
  "storeName": "高鉅科技股份有限公司",
  "orderId": "onepay0001",
  "amount": "16300",
  "receiptType": "",
  "invoice": {
    "rateType": 1,
    "inputType": "3",
    "cloudType": "2",
    "mobileCode": "/WHWJO+P",
    "naturalPerson": "TP03000001234567",
    "loveCode": "5216",
    "b2bId": "28915188",
    "taxId": "28915188"
  },
  "echo": {
    "value0": "運送方式:面交",
    "value0CanShow": true,
    "value1": "訂單備註2",
    "value1CanShow": true,
    "value2": "訂單備註3",
    "value2CanShow": false,
    "value3": "訂單備註4",
    "value3CanShow": false,
    "value4": "訂單備註5",
    "value4CanShow": false
  },
  "itemList": [
    {
      "id": "A0001",
      "name": "大摩 鎏金四季系列 冬季 VINTAGE 2001 (台灣限定)",
      "price": "100",
      "quantity": "2",
      "total": "200"
    },
    {
      "id": "A0002",
      "name": "格蘭菲迪 26年 干邑桶單一麥芽威士忌",
      "price": "200",
      "quantity": "3",
      "total": "600"
    },
    {
      "id": "A0003",
      "name": "艾柏迪 28年 OLOROSO雪莉桶",
      "price": "300",
      "quantity": "5",
      "total": "1500"
    },
    {
      "id": "A0004",
      "name": "奶與蜜 元素系列 紅葡萄酒桶單一麥芽威士忌",
      "price": "400",
      "quantity": "10",
      "total": "4000"
    },
    {
      "id": "A0005",
      "name": "格蘭花格 紅門窖藏原酒系列 三入套組",
      "price": "500",
      "quantity": "20",
      "total": "10000"
    }
  ]
}

特約商店傳入QRCode之Json規範說明

項次 欄位 說明 型別 備註
1 storeUid 特約商店商務代號 string 必要
2 storeName 特約商店名稱 string
3 orderId 特約商店訂單編號 string 必要,最大長度為30,不可重複
4 amount 訂單總金額 string 必要
5 itemList 商品列表 array 必要,請參考商品列表請求欄位說明
6 invoice 發票資料 object 請參考發票請求欄位說明
7 receiptType 收據類型︰
1=免用統一發票
2=農漁民收據
string 發票資料跟收據類型只能擇一傳入
不接受兩者同時傳入
8 echo echo資料 object 請參考echo欄位說明

API設定串接

請確認各項參數傳送時是使用 Http POST 方式串接Restful API。
以「JSON」格式直接傳送、回傳參數。
事前準備:

  1. 從應用市場中安裝最新版本的MYPAY APP、一碼付 APPP。
  2. 進入MYPAY APP進行登入,並確認登入是否成功(登入成功會看到上方有商店名稱,下方有登出的按鈕)。
  3. 進入一碼付 APP進行登入,並在主選單頁中點選【API設定】,進入後設定URL後,再點選左上返回鍵回到主選單頁將會儲存URL。

Request欄位說明

項次 欄位 說明 型別 備註
1 type 類型:
1=取得Server狀態
2=交易結果回傳
3=退款結果回傳
4=驗證折扣碼
string 必要
2 data 資料欄位,其內容值對應所屬的type而有所不同,請參考以下對應的說明 string 當type為2、3、4時必要
其內容值都必須為合法的JSON Object { ... }

data資料欄位說明(當Request的type為1時<取得Server狀態>)

項次 欄位 說明 型別 備註
1

Response欄位說明(當Request的type為1時<取得Server狀態>)

項次 欄位 說明 型別 備註
1 共同欄位 Response的共同欄位 請參考Response共同欄位說明
2 dateTime 回應時間 string 格式為yyyyMMddHHmmss

data資料欄位說明(當Request的type為2時<交易結果回傳>)

項次 欄位 說明 型別 備註
1 storeUid 特約商店商務代號 string
2 userId 在特店中註冊的帳號名稱 string
3 orderId 訂單編號,依據類型不同分為:
收銀=為一碼付APP自行產生的訂單編號
訂單掃碼=為合作夥伴傳入的訂單編號
string
4 pfn 付款類型 string 請參考付款類型說明
5 uid 對應該訂單的uid,可用來查詢金流交易 string
6 key 對應該訂單的key,可用來查詢金流交易 string
7 finishTime 交易時間 string
8 code 回傳碼 string 請參考回傳碼說明
9 msg 回傳訊息 string
10 amount 交易金額 string
11 actualAmount 實際交易金額 string
12 currency 交易幣別︰
TWD=新台幣
CNY=人民幣
string
13 actualCurrency 實際交易幣別 string
14 cardNo 卡號 string
15 aCode 授權碼 string
16 itemList 商品列表 list 請參考商品列表請求欄位說明
17 invoice 發票資料 object 請參考發票結果欄位說明
18 echo echo資料 object 請參考echo欄位說明
19 onePassEcho 一碼付echo資料 string 其內容值都為合法的JSON Object
{
"storeUid": "...",
"storeName": "...",
"externalStoreUid": "...",
"externalStoreName": "..."
}

storeUid為交易的特店編號
storeName為交易的特店名稱
externalStoreUid為外部的交易特店編號
externalStoreName為外部的交易特店名稱

Response欄位說明(當Request的type為2時<交易結果回傳>)

項次 欄位 說明 型別 備註
1 共同欄位 Response的共同欄位 請參考Response共同欄位說明
2 dateTime 回應時間 string 格式為yyyyMMddHHmmss

data資料欄位說明(當Request的type為3時<退款結果回傳>)

項次 欄位 說明 型別 備註
1 storeUid 特約商店商務代號 string
2 userId 在特店中註冊的帳號名稱 string
3 orderId 訂單編號,為原始交易的訂單編號 string
4 pfn 付款類型 string 請參考付款類型說明
5 uid 對應該訂單的uid,可用來查詢金流交易 string
6 key 對應該訂單的key,可用來查詢金流交易 string
7 finishTime 交易時間 string
8 code 回傳碼 string 請參考回傳碼說明
9 msg 回傳訊息 string
10 amount 交易金額 string
11 actualAmount 實際交易金額 string
12 currency 交易幣別︰
TWD=新台幣
CNY=人民幣
string
13 actualCurrency 實際交易幣別 string

Response欄位說明(當Request的type為3時<退款結果回傳>)

項次 欄位 說明 型別 備註
1 共同欄位 Response的共同欄位 請參考Response共同欄位說明
2 dateTime 回應時間 string 格式為yyyyMMddHHmmss

data資料欄位說明(當Request的type為4時<驗證折扣碼>)

項次 欄位 說明 型別 備註
1 storeUid 特約商店商務代號 string 必要
2 userId 在特店中註冊的帳號名稱 string 必要
3 storeName 特約商店名稱 string
4 orderId 特約商店訂單編號 string 必要,最大長度為30,不可重複
5 amount 訂單總金額 string 必要
6 itemList 商品列表 array 必要,請參考商品列表請求欄位說明
7 invoice 發票資料 object 請參考發票請求欄位說明
8 receiptType 收據類型︰
1=免用統一發票
2=農漁民收據
string 發票資料跟收據類型只能擇一傳入
不接受兩者同時傳入
9 echo echo資料 object 請參考echo欄位說明
10 partner 合作夥伴相關資料 object 必要,請參考合作夥伴相關資料欄位說明

Response欄位說明(當Request的type為4時<驗證折扣碼>)

項次 欄位 說明 型別 備註
1 共同欄位 Response的共同欄位 請參考Response共同欄位說明
2 result 回傳資料 string 其內容值都為合法的JSON Object { ... }
內容請參考回傳資料欄位說明

資料欄位說明

Request資料欄位說明

商品列表請求欄位說明

項次 欄位 說明 型別 備註
1 id 商品編號 string 必要
2 name 商品名稱 string 必要,商品名稱不能有冒號(:)
3 price 商品單價 string 必要
4 quantity 商品數量 string 必要
5 total 商品總價(總價 = 單價 x 數量) string 必要

發票請求欄位說明

項次 欄位 說明 型別 備註
1 rateType 稅率類型︰
1=應稅
2=零稅率
3=免稅
int
2 inputType 類型︰
1=雲端發票
2=發票捐贈
3=實體發票
string
3 cloudType 雲端發票類型︰
2=手機條碼
3=自然人憑證條碼
4=以E-Mail寄送
string 類型為1才有作用
4 mobileCode 手機條碼 string 雲端發票類型為2才有作用
5 naturalPerson 自然人憑證條碼
(格式請自行驗證)
string 雲端發票類型為3才有作用
6 loveCode 愛心碼
(格式請自行驗證)
string 類型為2才有作用
7 b2bId 統一編號
(格式請自行驗證)
string 類型為3才有作用
8 taxId 統一編號
(格式請自行驗證)
string 類型為1才有作用

echo欄位說明

項次 欄位 說明 型別 備註
1 value0 資料0 string
2 value0CanShow 是否顯示資料0 boolean
3 value1 資料1 string
4 value1CanShow 是否顯示資料1 boolean
5 value2 資料2 string
6 value2CanShow 是否顯示資料2 boolean
7 value3 資料3 string
8 value3CanShow 是否顯示資料3 boolean
9 value4 資料4 string
10 value4CanShow 是否顯示資料4 boolean

合作夥伴相關資料欄位說明

項次 欄位 說明 型別 備註
1 couponCode 折扣碼 string 必要

發票結果欄位說明

項次 欄位 說明 型別 備註
1 state 發票開立狀態︰
0=不處理或已無效(預設)
1=等候處理中
2=發票開立成功
3=發票開立失敗(系統或特約商店發票相關設定不正確)
4=作癈
5=發票開立失敗(系統發生錯誤)
6=折讓
int
2 rateType 稅率類型︰
1=應稅
2=零稅率
3=免稅
int
3 inputType 類型︰
1=雲端發票
2=發票捐贈
3=實體發票
4=外部發票
5=免用統一發票收據
6=農漁民收據
int
4 titleType 發票標題類型︰
1=文字
2=圖片URL
int
5 title 發票標題資料 string 依發票標題類型決定資料的內容為標題文字或圖片網址
6 amount 金額 string
7 date 發票時間 string
8 number 發票號碼 string
9 randomCode 隨機碼 string
10 sellerId 賣方統編 string
11 buyerId 買方統編 string
12 middleBarcode 發票中間barcode string
13 leftQRCode 發票左邊Qr Code string
14 rightQRCode 發票右邊Qr Code string

Response資料欄位說明

Response共同欄位說明

項次 欄位 說明 型別 備註
1 code 回傳碼 string 成功:
必須為200

失敗:
CP001:折扣碼錯誤(長度不正確)
CP002:折扣碼已過期
CP自定義回傳碼:自定義回傳訊息

上述200、CP001、CP002已定義,意義上相同請直接使用該回傳碼,若自行定義其他回傳碼,為了避免和MYPAY的回傳碼重複,所有合作夥伴API的回傳碼都必須加上前綴CP,後面再自行定義回傳碼
2 msg 回傳訊息,請合作夥伴自行定義 string

回傳資料欄位說明

項次 欄位 說明 型別 備註
1 storeUid 特約商店商務代號 string
2 storeName 特約商店名稱 string
3 orderId 特約商店訂單編號 string 最大長度為30,不可重複
4 amount 訂單總金額 string
5 itemList 商品列表 array 除了須與Request的itemList相同之外,須額外加上折扣項目
請參考商品列表結果欄位說明
6 invoice 發票資料 object 請參考發票請求欄位說明
7 receiptType 收據類型︰
1=免用統一發票
2=農漁民收據
string 發票資料跟收據類型只能擇一傳入
不接受兩者同時傳入
8 echo echo資料 object 請參考echo欄位說明
9 validationCode 驗證碼 string 須將Request的storeUid、orderId與amount依順序串接,取得的新字串再轉為UTF-8編碼後,得到的值再使用SHA-256雜湊後,取得的值即為驗證碼

商品列表結果欄位說明

項次 欄位 說明 型別 備註
1 id 商品編號 string
2 name 商品名稱 string 商品名稱不能有冒號(:)
3 price 商品單價 string 若為折扣項目須為負值
4 quantity 商品數量 string
5 total 商品總價(總價 = 單價 x 數量) string 若為折扣項目須為負值

版本紀錄

一碼付 APP

版本號 測試更新日期 正式更新日期 異動
1.5.0 2024-03-05 2024-03-05 更新︰
手機載具、自然人憑證、愛心碼等掃碼流程 - 掃碼成功後不顯示輸入框,掃碼取消或返回後才顯示輸入框,並且點擊Icon下方輸入框可以修改
1.4.9 2024-03-01 2024-03-04 更新︰
1. 所有掃碼換成MYPAY新掃碼
2. 手機載具、自然人憑證、愛心碼等掃碼流程 - 掃碼後拿掉輸入框,並且點擊Icon下方輸入框只能查看不能修改
1.4.8 2024-02-07 2024-03-04 更新︰
手機載具等掃碼換成MYPAY新掃碼
1.4.7 2024-01-15 2024-03-04 新增︰
結帳頁 - 全支付、全盈支付

更新︰
1. 調整新登入流程
2. 結帳頁 - 所有顯示收款QR Code(線上)的Icon
1.4.6 2023-12-27 2024-03-04 新增︰
離線開立開票,發票配號失敗(9999_11)的流程

修正︰
取得特店支援支付方式 - 錯誤時顯示提示訊息不明確的問題
1.4.5 2023-12-07 2024-03-04 更新︰
1. 掃碼結帳頁 - 相機掃碼可連續讀取,並顯示商品同步新增至購物車中
2. 結帳頁 - 補上重新取得特店支援收款方式,Token失效時需重新登入
3. 結帳頁 - 補上TAP交易,交易成功列印失敗的判斷
4. 結帳頁 - 補上TAP交易,Android版本低於8.0的提示訊息
5. 結帳頁 - 更新統編驗證規則
6. 更新 結帳頁 - 列印明細調整為預設選中
1.4.4 2023-10-30 2023-10-30 修正︰
取得收款方式 - 尚未綁定設備時,沒有顯示彈窗的問題
1.4.3 2023-09-27 2023-10-30 更新︰
1. 調整正式開放一卡通,由特店支援收款方式對應顯示Icon
2. 調整取得特店金鑰、特店支援收款方式
1.4.2 2023-08-24 2023-08-24 修正︰
訂單掃碼 - 交易完成後回到首頁主選單Loading不會消失的問題
1.4.1 2023-08-08 2023-08-14 修正︰
部分閃退問題
1.4.0 2023-08-07 2023-08-14 更新︰
優化 - 取得特店支援付款方式
1.3.9 2023-07-06 2023-07-06 部分部署 修正︰
打折模式為折數時,當折數超過100時,小計和結帳金額顯示錯誤的問題
1.3.8 2023-07-06 2023-07-06 部分部署 修正︰
打折模式預設為折數沒反應的問題
1.3.7 2023-07-05 2023-07-06 部分部署 更新︰
1. 收銀 - 打折 計算公式台灣/國外可自由切換
2. 掃碼結帳 - 打折 計算公式台灣/國外可自由切換
1.3.6 2023-05-16 2023-07-06 部分部署 修正︰
處理重複點擊的問題

更新︰
1. 掃碼結帳 - 美而快加入可讀取商品DB白名單
2. 首頁主選單 - 一卡通Icon在平板上不顯示
1.3.5 2023-05-04 2023-05-08 部分部署 新增︰
掃碼結帳 - 新增掃碼Icon可掃Barcode和QRCode

更新︰
1. 商品快捷調整為以特店區分資料
2. 掃碼結帳調整為以特店區分資料
1.3.4 2023-05-04 2023-05-08 部分部署 修正︰
結帳 - 手機載具顯示不完整的問題

更新︰
更新系統權限
1.3.3 2023-04-17 2023-05-08 部分部署 新增︰
訂單掃碼 - 訂單備註,Echo新增value0CanShow等參數,可獨立自行選擇是否顯示
請參考echo欄位說明
1.3.2 2023-04-14 2023-05-08 部分部署 新增︰
結帳 - 列印明細Icon,可列印明細
1.3.1 2023-04-12 新增︰
掃碼結帳,可使用掃碼讀取商品進行結帳
1.3.0 2023-03-24 2023-05-08 部分部署 新增︰
結帳報表,可列印指定時間交易的報表
1.2.9 2023-03-15 2023-03-15 部分部署 更新︰
收銀 - 當訂單打折輸入超過100%時,減價金額更新為空
1.2.8 2023-03-15 2023-03-15 部分部署 更新︰
商品快捷 - 上限數量由15上調為25
1.2.7 2023-03-14 2023-03-15 部分部署 更新︰
1. 收銀 - 折扣預設為空,並優化單品商品點擊折扣的範圍
2. 訂單掃碼 - 折扣碼在沒顯示鍵盤時,可以直接掃碼讀入資料,並覆蓋現有折扣碼
1.2.6 2023-03-10 2023-03-10 部分部署 更新︰
1. 收銀 - 手輸商品改為自訂商品,並固定在第一個
2. 收銀 - 使用自訂商品為已存在商品時,單價及小計會自動帶入
1.2.5 2023-03-09 2023-03-10 部分部署 新增︰
1. 串接特店支援收款方式
2. 收銀 - 平板版面
3. 收銀 - 當購物車內有商品時,返回會顯示提示對話窗
4. 收銀 - 當按下折扣的時候,可以輸入折扣名稱
5. 收銀 - 當商品快捷未滿15項時,新增自訂商品至購物車,會顯示對話窗,已滿15項時則不會顯示

修正︰
1. 收銀 - 商品列表當選中多項商品時,要有多項商品是選中的狀態
2. 結帳 - 當交易成功,列印失敗時,提示對話窗修正為,請至訂單管理重新列印單據
3. 調整logo為svg並在平板上不跑版

更新︰
1. 收銀 - 手輸商品改為自訂商品,並固定在第一個
2. 收銀 - 點商品或折扣進入到商品,不需要鎖定焦點;當沒有單價時,焦點才會預設鎖定在單價
3. 訂單掃碼 - 輸入折扣碼時,限制不能輸入中文,只能輸入英文、數字
4. 訂單掃碼 - 驗證折扣碼錯誤時,可重複輸入折扣碼
1.2.4 2023-02-07 2023-02-10 部分部署 新增︰
結帳 - 收款方式新增悠遊付

更新︰
1. 收銀新版
2. 合作夥伴URL設定 - 更新為API設定
1.2.3 2022-12-27 2022-12-29 更新︰
調整折扣碼的驗證規則
1.2.2 2022-12-14 新增︰
訂單掃碼 - 折扣碼

修正︰
沒有任何一個Icon權限時,沒有錯誤訊息的問題

更新︰
優化交易失敗時,同交易成功返回對應畫面的流程,(收銀 -> 結帳 -> 交易成功 -> 收銀);(收銀 -> 結帳 -> 交易失敗 -> 結帳);(訂單掃碼 -> 結帳 -> 交易成功 -> 首頁主選單);(訂單掃碼 -> 結帳 -> 交易失敗 -> 結帳)
1.2.1 2022-11-16 2022-11-16 新增︰
首頁主選單Icon權限

修正︰
1. 訂單掃碼 - 當系統設定>發票收據設定未開啟時,結帳只能不列印,外部有帶發票/收據資料還是可以列印的問題
2. 交易完成後不會回到對應畫面的問題,收銀 -> 收銀,訂單掃碼 -> 首頁主選單

更新︰
1. 結帳 - 信用卡顯示/隱藏判斷
2. 首頁主選單版面
1.1.3 2022-10-05 2022-10-05 新增︰
1. 系統設定 - 收據類型設定
2. 訂單掃碼 - 更完整的資料格式限制

更新︰
收據類型設定 > 收銀/訂單掃碼 > 結帳 - 顯示/隱藏、自動選擇收據...流程
1.1.1 2022-09-22 2022-09-22 新增︰
1. 平板的結帳頁
2. 是否有安裝正確的MyPay

修正︰
1. 訂單掃碼限制判斷
2. 對話框點擊空白的地方可以關閉的問題

更新︰
1. 系統設定-移除印表機設定,印表機設定-預設主選單顯示
2. 收銀-結帳按鈕高度調高
1.1.0 2022-09-08 新增︰
1. Firebase crashlytics、analytics
2. 系統設定-訂單掃碼限制、發票管理設定、收據管理設定、印表機設定、交易回傳設定、點餐單管理設定
3. 交易回傳-登入和外部的特約商店商務代號、特約商店名稱

更新︰
優化Profile、Setting等SharedPreferences資料
1.0.4 2022-08-12 修正︰
訂單掃碼交易有發票資訊但沒有印出發票的問題

更新︰
1. 任意付交易(收銀、訂單掃碼)改為MyPay交易
2. 訂單管理Cross Page到MyPay
1.0.3 2022-08-04 2022-08-05 修正︰
訂單明細,重印、補印發票按鈕顯示的判斷
1.0.2 2022-08-03 2022-08-03 修正︰
訂單明細,列印發票的titleType改為取API
1.0.1 2022-08-02 新增︰
新增圓形Icon
1.0.0 2022-07-29 新增︰
訂單明細新增重印簽單、重印發票、補印發票
0.0.1 2022-07-08 初版

訂單掃碼(特約商店傳入QRCode)

版本號 修正日期 修訂內容
1.0.9 2023-04-17 新增︰
Echo新增value0CanShow等參數,可獨立自行選擇是否顯示在訂單掃碼 - 訂單備註
請參考echo欄位說明
1.0.8 2022-12-13 新增︰
invoice須帶rateType
1.0.7 2022-12-06 更新︰
1. 商品列表items更新為itemList
2. itemList新增id
1.0.6 2022-11-16 新增︰
收據類型
1.0.5 2022-09-08 新增︰
商品名稱備註,商品名稱不能有冒號(:)

更新︰
一碼付 APP交易結果回傳
1.0.4 2022-08-26 新增︰
特約商店名稱
1.0.3 2022-08-04 新增︰
訂單編號備註,最大長度為30
1.0.2 2022-07-25 更新︰
1. 產出QRCode之容錯率調整成L(7%)
2. 更換範例資料
1.0.1 2022-07-01 新增︰
發票資訊
1.0.0 2022-06-29 初版

API設定串接

版本號 修正日期 修訂內容
1.0.3 2023-03-09 新增︰
回傳碼和回傳訊息規則
1.0.2 2022-12-14 更新︰
1. 調整data型別
2. 更新授權碼的欄位資料,appCode更新為aCode
1.0.1 2022-12-08 更新︰
1. 調整data說明、型別
2. 調整onePassEcho型別、備註
3. data資料欄位說明(當Request的type為3時<退款結果回傳>),移除invoice
1.0.0 2022-12-06 初版