Integrate TAIWAN QRCode Pay Search

Description

TAIWAN Pay 條碼支付查詢（整合金流端點）。
支援「財金版 (FISC)」與「華南版 (HNCB)」雙版本收單機制。
情境：

• 依廠商金流參數設定進行付款：金流參數為必填、門市代碼不需要填
• 依全通路金流參數設定進行付款：門市代碼為必填、金流參數不需要填

Resource

GET /v1/payment/integrate/search

Authorization

採用 OAuth 2.0 Bearer Token，詳細使用流程請參考 Auth Login。

Query Parameters

Name	Type	Description
type	string	付款方式，請輸入 TAIWAN_QRCODE_PAY
tw_pay_version	string	TaiwanPay 通道版本： 0: 華南銀行 (HNCB) 1: 財金資訊 (FISC，預設值) (optional)
request	Request	請求參數 (JSON 字串)
store_id	string	門市代碼 (optional)
is_test	boolean	是否為測試環境 在全通路正式環境預設為 false 在全通路測試環境預設為 true (optional)

---

Query Parameters - Request

1. 財金版 (FISC)

Name	Type	Description
merchantId	string	商店代號 (自帶金流時必填)
terminalId	string	末端代號 (自帶金流時必填)
verifyCode	string	認證代碼 (自帶金流時必填)
acqBank	string	收單行代碼 (自帶金流時必填)
mti	string	交易類型，請輸入 0800
cardNumber	string	卡(帳)號 (optional)
processingCode	string	處理代碼，請輸入 000173
traceNumber	string	端末交易序號
localTime	string	交易時間 (hhmmss)
localDate	string	交易日期 (yyyyMMdd)
orderNumber	string	訂單編號
orgTxnData	OrgTxnData	原始交易資訊

OrgTxnData (財金版)

Name	Type	Description
tag01	string	原交易類型
tag02	string	原處理代碼，原交易若為QRCode掃碼購物交易需比照消費扣款購物(變動費率)交易放置002541，目前限定查詢002541、002542、002543
tag03	string	原交易金額，本欄位含二位小數位,需右靠左補 0 例如:台幣 123 元，其表示為 000000012300
tag05	string	原端末交易序號 (optional)
tag06	string	原交易時間 (optional)
tag07	string	原交易日期 (optional)

2. 華南版 (HNCB)

Name	Type	Description
storeId	string	華銀收款方特店代號，X(20) (自帶金流時必填)
endpointCode	string	華銀端末代號，X(08) (自帶金流時必填)
verifyCode	string	華銀簽章密鑰，全通路計算 sign 後自動排除不送出 (自帶金流時必填)
terminalId	string	機台號/端末號，X(30)，例如 "0101" (optional)
orderNumber	string	訂單編號，N(18)，右靠左補 0 (必填)
inqDateTime	string	查詢交易日期時間 (yyyyMMdd 或 yyyyMMddHHmmss) (optional，預設當日)
txnDir	string	交易方向，請輸入 "RQ" (optional，預設 "RQ")
txnSeqno	string	原華南交易序號 (optional，若提供可精確比對)

---

Request Examples

範例一：財金版 (FISC)

GET /v1/payment/integrate/search?type=TAIWAN_QRCODE_PAY&tw_pay_version=1&store_id=0&is_test=false&request={"merchantId":"005276932381001","terminalId":"10016338","verifyCode":"5E8B6E1998F421204C6576544FE1A26B44FC775982D8CE2E","acqBank":"005","mti":"0800","orderNumber":"P2022102002","processingCode":"000173","traceNumber":"115400","localTime":"115400","localDate":"20221025","orgTxnData":{"tag01":"0200","tag02":"002541","tag03":"000000001000"}}

範例二：華南版 (HNCB)

GET /v1/payment/integrate/search?type=TAIWAN_QRCODE_PAY&tw_pay_version=0&store_id=0&is_test=false&request={"storeId":"008123456780001","endpointCode":"00000001","verifyCode":"5E8B6E1998F421204C6576544FE1A26B","terminalId":"0101","orderNumber":"000020260910000001","inqDateTime":"20260910","txnDir":"RQ"}

---

Response Body Parameters

整合金流 API 回傳格式為標準 JSON 物件（依據通道版本回傳對應欄位，包含 tw_pay_version 通道版本標記）：

1. 財金版 (FISC)

Name	Type	Description
mti	string	交易類型，訂單查詢交易 API 為 0810
cardNumber	string	卡(帳)號
processingCode	string	處理代碼，訂單查詢交易 API 為 000173
systemDateTime	string	系統日期時間
traceNumber	string	端末交易序號
srrn	string	系統追蹤號
responseCode	string	回應碼: 0000: 成功 其他: 失敗
terminalId	string	端末代號
merchantId	string	特店代號
orderNumber	string	訂單編號
otherInfo	OtherInfo	附加資料
verifyCode	string	驗證碼
tw_pay_version	string	TaiwanPay 通道版本 ("1" 代表財金版)
orgTxnData	OrgTxnData	原始交易資訊

2. 華南版 (HNCB)

Name	Type	Description
storeId	string	特店代號
endpointCode	string	端末代號
terminalId	string	機台號
orderNumber	string	訂單編號
txnDir	string	交易方向 ("RS")
txnType	string	交易類型 ("2541": 扣款成功, "2542": 取消, "2543": 退款)
txnDateTime	string	交易時間 (yyyyMMddHHmmss)
txnAmt	string	交易金額
txnSeqno	string	交易序號 (華南原廠唯一交易號)
respCode	string	回應代碼 ("4001": 成功；其餘為失敗)
respDesc	string	回應代碼說明
carrierType	string	手機條碼載具類別
carrierId1	string	手機條碼載具號碼
sign	string	華南原廠回傳之簽章值
tw_pay_version	string	TaiwanPay 通道版本 ("0" 代表華南版)

3. Response Body Parameters - OtherInfo (財金版專用)

Name	Type	Description
tag01	string	收單行資訊
tag02	string	特店負責人員行動電話
tag03	string	特店營業名稱
tag04	string	特店統一編號
tag05	string	端末設備查核碼
tag06	string	繳納期限(截止日)
tag07	string	銷帳編號
tag08	string	被查詢交易之授權回應碼
tag09	string	新驗證參數資訊
tag10	string	新驗證參數檢查值
tag11	string	通知交易之回應碼
tag12	string	端末設備型態
tag13	string	特店交易型態
tag14	string	費用資訊
tag15	string	電子發票手機條碼
tag16	string	行動裝置端使用者IP
tag17	string	互動式附言欄1
tag18	string	互動式附言欄2
tag19	string	互動式附言欄3
tag20	string	付款方識別資訊1
tag21	string	臨櫃銷帳編號
tag22	string	臨櫃繳納期限
tag23	string	臨櫃交易金額
tag24	string	付款方識別資訊2
tag25	string	繳費支付工具類型及手續費
tag26	string	繳費SessionID
tag30	string	轉入行代碼
tag31	string	轉入帳號
tag80	string	端末設備型態代號
tag81	string	掃碼交易補充資訊
tag82	string	結帳日
tag83	string	非促銷商品金額
tag90	string	卡號比對資訊
tag91	string	傳送機構
tag92	string	CVC2卡片末三碼
tag97	string	QR Code雜湊內容
tag98	string	錢包服務提供者
tag99	string	訊息押碼
tag100	string	加密之卡號
tag101	string	QRCode交易卡別
tag102	string	Merchant PAN
tag103	string	銀聯QRC Voucher Number
tag104	string	郵遞區號
tag105	string	退貨重送識別碼
tag108	string	付款方電話
tag109	string	付款方電子郵件
tag110	string	付款方英文姓氏
tag111	string	TSP Transaction Data
tag112	string	PAR
tag113	string	MAID
tag114	string	PFID
tag115	string	Funding Source

4. Response Body Parameters - OrgTxnData (財金版專用)

Name	Type	Description
tag01	string	原交易類型
tag02	string	原處理代碼，原交易若為 QRCode 掃碼購物交易需比照消費扣款購物(變動費率)交易放置 002541，目前限定查詢 002541、002542、002543
tag03	string	原交易金額
tag04	string	原系統日期時間
tag05	string	原端末交易序號
tag06	string	原交易時間
tag07	string	原交易日期
tag08	string	原系統追蹤號
tag10	string	訂單狀態: 3: 取消訂單 8: 已退貨 9: 授權成功 X: 失敗
tag11	string	累積退貨金額

---

Response Examples

範例一：財金版 Response

{
  "mti": "0810",
  "cardNumber": "0006147854124258",
  "processingCode": "000170",
  "systemDateTime": "0508190018",
  "traceNumber": "190018",
  "srrn": "128190018440",
  "responseCode": "0000",
  "terminalId": "00010001",
  "merchantId": "006263015610001",
  "otherInfo": {
    "tag08": "0000"
  },
  "verifyCode": "4B58E25D96A522220579F874DB51FCD88B54C0123338E231A72F41007164A319",
  "orgTxnData": {
    "tag04": "0508190014",
    "tag08": "943003103933"
  },
  "tw_pay_version": "1"
}

範例二：華南版 Response

{
  "storeId": "008123456780001",
  "endpointCode": "00000001",
  "terminalId": "0101",
  "orderNumber": "000020260910000001",
  "txnDir": "RS",
  "txnType": "2541",
  "txnDateTime": "20260910140005",
  "txnAmt": "10000",
  "txnSeqno": "20260910140005012345",
  "respCode": "4001",
  "respDesc": "成功",
  "carrierType": "3J0002",
  "carrierId1": "/UPP2YM2",
  "sign": "5E4F3A...",
  "tw_pay_version": "0"
}

---

IntegrateSearch API Workflow

%%{init: {'securityLevel': 'loose', 'theme':'base'}}%%

sequenceDiagram
    autonumber
    participant C as Client (MajiPOS)
    participant OP as OmniPlatform (IntegrateSearch)
    participant PS as PayServer (FISC / HNCB)

    C->>OP: Request [GET] /v1/payment/integrate/search (帶入 tw_pay_version)
    activate OP
    OP->>OP: 參數檢核 (外部金流自帶參數 vs 門市設定)
    alt tw_pay_version == "0" (華南版)
        OP->>OP: 排除內部參數，依規則計算 Base64+SHA256 Sign 簽章
        OP->>PS: POST {taiwan_pay_url}/inquery (JSON Payload)
    else tw_pay_version == "1" (財金版)
        OP->>OP: 組裝 FiscIIOrderInquery SOAP/XML
        OP->>PS: POST {taiwan_pay_focas_fisc_url}/orderinquery (XML Payload)
    end
    activate PS
    PS-->>OP: 回傳原廠查詢結果 (JSON / XML)
    deactivate PS
    OP->>OP: 解析原廠回應為字典格式
    OP-->>C: Response (直接回傳 JSON Object 結果)
    deactivate OP

錯誤處理與檢核規範 (Validation & Error Codes)

參數檢核錯誤 (HTTP 400 Bad Request)

當華南版查詢請求參數缺漏、格式不符或為空值（null）時，全通路閘道將於入口處提早攔截並回傳 HTTP 400，不發送外部請求至銀行端： - orderNumber / txnSeqno：二擇一必填，1~18 碼單號（orderNumber）或最多 20 碼交易序號。 - inqDateTime：選填，8 或 14 碼數字（格式 yyyyMMdd 或 yyyyMMddHHmmss，預設為當日）。 - 錯誤訊息結構範例：{"message": "orderNumber 與 txnSeqno 必須至少提供一項"}。