支援的終端機型號
- Landi A8 / A8S：支援所有支付方式
- PAX A920：僅支援 QR Code 支付
1. POS-KEY
POS-KEY 為交易資料加密金鑰，由 Haojin App 產生。
系統預設為 啟用加密。
商戶可於商戶平台（MMS）開啟 / 關閉加密或重新產生 POS-KEY，並需於 Haojin App 重新整理裝置後才會生效。
重新產生 POS-KEY
Haojin App → 我的 → 設定 → POS-Key → 產生
查詢 POS-KEY
商戶平台 → 設定 → 裝置設定 → POS Key 管理
2. 加密方式（Encryption）
- 所有交易資料皆使用 AES-128 / CBC / PKCS5Padding
- 加密金鑰：POS-KEY
- IV：
qfpay202306_hjsh
- 加密後再進行 Base64 編碼
3. 請求資料格式（Request Payload）
| 參數 | 必填 | 型態 | 說明 |
|---|
amt | 是 | Double | 交易金額（例：10.1 = HKD 10.10） |
func_type | 是 | String | 功能指令代碼 |
channel | 是 | String | 錢包 / 支付方式 |
out_trade_no | 否 | String | 商戶交易參考號 |
camera_id | 否 | Integer | 0=後鏡頭（預設），1=前鏡頭 |
payment_timeout | 否 | Integer | 支付逾時時間（秒） |
wait_card_timeout | 否 | Integer | 等待刷卡時間（預設 120 秒） |
3.1 付款（Payment）
- QR Code 模式：MPM / CPM 依最近一次使用自動切換
camera_id 可指定前 / 後鏡頭- 刷卡交易：
wait_card_timeout 為最大等待時間
- 錢包交易：
payment_timeout 為整筆交易等待時間
- PayMe 最長僅支援 120 秒
scan_type：
moveToBack：
{
"content": {
"amt": 100,
"camera_id": 0,
"channel": "card_payment",
"func_type": 1001,
"moveToBack": 1,
"out_trade_no": "456799999999",
"wait_card_timeout": 120,
"scan_type": "SCAN_PAY"
},
"digest": "76b9186077cdc2bc5d78ae921309811d"
}
3.2 退款（Refund / Void）
| 欄位 | 必填 | 型別 | 說明 |
|---|
orderId | 是 | String | QFPay 交易編號（syssn） |
refund_amount | 否 | String | 退款金額（預設最大可退金額） |
allow_modify_flag | 否 | Integer | 0=不可修改（預設），1=可修改 |
Visa / Mastercard / 銀聯卡 / 美國運通卡
當日退款必須全額退款，不支援當日部分退款。
{
"content": {
"allow_modify_flag": 1,
"func_type": 1002,
"moveToBack": 1,
"orderId": "order_id",
"refund_amount": "0.05"
},
"digest": "9C8E9FB05C7C24B6CA04EBFA1263EF41"
}
3.3 列印收據
{
"content": {
"orderId": "12345678",
"func_type": 3001
},
"digest": "79fd145311d54d03e4e685d50f15dd7f"
}
3.4 列印交易摘要
{
"content": {
"func_type": 3002
},
"digest": "79fd145311d54d03e4e685d50f15dd7f"
}
3.5 交易查詢
支援參數 out_trade_no
{
"content": {
"orderId": "12345678",
"func_type": 4001
},
"digest": "99CE8BF9C7304AC964522D10F51660B4"
}
3.6 取消付款 / 退款請求
{
"content": {
"func_type": 5001
},
"digest": "99CE8BF9C7304AC964522D10F51660B4"
}
4. 簽名產生機制（Signature Generation）
計算流程
// original payload
content = {"amt":100,"channel":"card_payment","func_type":1001,"out_trade_no":"456799999999"}
// sort keys in ascending order
format_content = {amt=100,channel='card_payment',func_type=1001,out_trade_no='456799999999'}
// if value is empty, use '' (empty string)
// signature
digest = md5(format_content + pos_key)
- 先將
content 進行 AES 加密
- 再以加密結果計算
digest
5. 欄位定義
5.1 func_type
| 數值 | 說明 |
|---|
| 1001 | 交易 |
| 1002 | 退款 |
| 3001 | 列印收據 |
| 3002 | 列印交易摘要 |
| 4001 | 交易查詢 |
| 5001 | 取消請求 |
5.2 channel
CPM = 消費者出示碼
MPM = 商戶出示碼
| 值 | 說明 | PayType |
|---|
| card_payment | Visa / Mastercard | 802808 |
| wx | 微信支付 | 800208 / 800201 |
| alipay | 支付寶 | 800108 / 800101 |
| payme | PayMe | 805808 / 805801 |
| union | 銀聯閃付 | 800708 / 800701 |
| fps | FPS | 802001 |
| octopus | 八達通 | 803708 |
| unionpay_card | 銀聯卡 | 806708 |
| amex_card | 美國運通 | 806808 |
6. 回應格式
{
"respcd": "6000",
"data": "{...}",
"respmsg": "xxxxxxxxxx",
"resperr": "xxxxxxxxxx"
}
回應代碼
| 代碼 | 說明 |
|---|
| 4003 | 請求被拒絕 |
| 5001 | 解密失敗 |
| 4004 | 請求方法錯誤（請使用 POST） |
| 4005 | 其他錯誤 |
| 4006 | 參數錯誤 |
| 6000 | 請求成功 |
| 6001 | 使用者取消 |
| 6002 | 請求失敗 |
7. USB 傳輸方式
- 以 USB 連接 POS 與收銀機
- 依 USB 協議封裝資料
- 回傳資料需解析後再進行 AES 解密
8. HTTP 通訊協議
- 預設 Port：
9001
- 使用
POST
- Header：
| 欄位 | 值 |
|---|
| Content-Type | application/json |
API 路徑
| 操作 | 路徑 |
|---|
| 發起交易 | /api/pos/trade |
| 發起退款 | /api/pos/cancel |
| 列印收據 | /api/pos/print_receipt |
| 列印交易摘要 | /api/pos/transaction_info |
| 查詢交易結果 | /api/pos/query_transaction |
| 取消交易請求 | /api/pos/cancel_request |
9. TCP 協議
- 預設 Port：9002
- 使用 Socket
- 所有內容皆為 AES 加密
10. USB 封包結構
| 欄位 | 說明 | 長度 |
|---|
| Start indicator | 0x2f6e | 2 Bytes |
| version | 0x01 | 1 Byte |
| payload type | 0x10/0x20/0x30 | 1 Byte |
| ref number | 0x01~0x7f | 1 Byte |
| payload length | 總長度 | 2 Bytes |
| data length | 資料長度 | 2 Bytes |
| data segment | 主體資料 | Variable |
| End indicator | 0x2f6e | 2 Bytes |
0x2f6e 為 ASCII 字串 /n 的十六進制表示，不是換行字元。
Timeout
回應逾時：1000ms
串列埠設定
| 設定 | 值 |
|---|
| Baud rate | 9600 |
| Stop bit | 1 |
| Parity | 0 |
| Data bits | 8 |
| Flow control | Off |
USB-to-Serial 支援
| 晶片 | 支援 |
|---|
| PL2303 HXD | 支援 |
| CH340 | 不支援 |
| FT232 | 不支援 |
此限制僅適用於 USB 模式整合。
若使用 HTTP / TCP 整合方式，則不受晶片限制。
封包範例
明文： {“content”:”{"amt":100,"channel":"wx","funcType":1,"mode":1}”,“digest”:“2f0c4683e25a7b9407265033070e9034”}
Hex: 2f6e011001007f00747b22636f6e74656e74223a227b5c22616d745c223a3130302c5c226368616e6e656c5c223a5c2277785c222c5c2266756e63547970655c223a312c5c226d6f64655c223a317d222c22646967657374223a223266306334363833653235613762393430373236353033333037306539303334227d2f6e