Integrate TAIWAN QRCode Pay

Description

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

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

Resource

POST /v1/payment/integrate/pay

Authorization

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

Request Body Parameters

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

Request Body Parameters - Request

1. 財金版 (FISC)

Name	Type	Description
merchantId	string	商店代號 (自帶金流時必填)
terminalId	string	末端代號 (自帶金流時必填)
verifyCode	string	認證代碼 (自帶金流時必填)
acqBank	string	收單行代碼 (自帶金流時必填)
mti	string	交易類型，請輸入 0200
processingCode	string	處理代碼，請輸入 012541
amt	string	交易金額，本欄位含二位小數位,需右靠左補 0 例如:台幣 123 元，其表示為 000000012300
traceNumber	string	端末交易序號，須配合交易日期時間資訊確保唯一性 長度需等於6
localTime	string	交易時間(hhmmss)
localDate	string	交易日期(yyyyMMdd)
countryCode	string	國別碼，請輸入158。
posEntryMode	string	設備輸入型態 ，請輸入071
posConditionCode	string	設備能力代碼 ，請輸入77
orderNumber	string	訂單編號 長度限制1~19
txnCurrencyCode	string	幣別碼，請輸入901
buyerID	string	消費者條碼

2. 華南版 (HNCB)

Name	Type	Description
storeId	string	華銀收款方特店代號，X(20) (自帶金流時必填)
endpointCode	string	華銀端末代號，X(08) (自帶金流時必填)
verifyCode	string	華銀簽章密鑰，全通路計算 sign 後自動排除不送出 (自帶金流時必填)
terminalId	string	機台號/端末號，X(30)，例如 "0101" (必填)
orderNumber	string	訂單編號，N(18)，右靠左補 0 (必填)
txnDateTime	string	交易時間 (yyyyMMddHHmmss)，N(14) (必填)
txnAmt	string	交易金額，含二位小數（例如：台幣 100 元 → 10000），X(12) (必填)
txnFISCTac	string	消費者條碼字串，X(256) (必填，亦可代入 qrcode 欄位)
txnCurrency	string	幣別碼，請輸入 "901" (optional，預設 "901")
txnDir	string	交易方向，請輸入 "RQ" (optional，預設 "RQ")
txnReMsgType	string	交易類型，被掃請填 "A" (optional)
nonredeement	string	是否不可折抵點數或紅利 (optional)
storeMemo	string	店家備註 (optional)
carrierType	string	電子發票載具類別 (optional)
carrierId1	string	電子發票載具號碼 (optional)

Request Examples

範例一：財金版 (FISC)

{
  "type": "TAIWAN_QRCODE_PAY",
  "tw_pay_version": "1",
  "request": {
    "merchantId": "005276932381001",
    "terminalId": "10016338",
    "verifyCode": "5E8B6E1998F421204C6576544FE1A26B44FC775982D8CE2E",
    "acqBank": "005",
    "mti": "0200",
    "processingCode": "012541",
    "amt": "000000012300",
    "traceNumber": "184845",
    "localDate": "20221025",
    "localTime": "112105",
    "countryCode": "158",
    "posEntryMode": "071",
    "posConditionCode": "77",
    "orderNumber": "P201712310000003000",
    "buyerID": "95AQAABhI0VniQEjRWABI0",
    "txnCurrencyCode": "901"
  },
  "store_id": "0",
  "is_test": false
}

範例二：華南版 (HNCB)

{
  "type": "TAIWAN_QRCODE_PAY",
  "tw_pay_version": "0",
  "request": {
    "storeId": "008123456780001",
    "endpointCode": "00000001",
    "verifyCode": "5E8B6E1998F421204C6576544FE1A26B",
    "terminalId": "0101",
    "orderNumber": "000020260910000001",
    "txnDateTime": "20260910140000",
    "txnAmt": "10000",
    "txnFISCTac": "95AQAABhI0VniQEjRWABI0",
    "txnCurrency": "901",
    "txnDir": "RQ",
    "txnReMsgType": "A"
  },
  "store_id": "0",
  "is_test": false
}

Response Body Parameters

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

1. 財金版 (FISC) 回應內容

Name	Type	Description
mti	string	交易類型
cardNumber	string	卡(帳)號，若條碼內含卡(帳)號資訊，則成功交易回應條碼內之卡(帳)號
processingCode	string	處理代碼
amt	string	交易金額，含二位小數
systemDateTime	string	系統日期時間
traceNumber	string	端末交易序號
localTime	string	交易時間 (hhmmss)
localDate	string	交易日期 (yyyyMMdd)
acqBank	string	收單行代碼
srrn	string	系統追蹤號
responseCode	string	回應碼: 0000: 成功 其他: 失敗
terminalId	string	端末代號
merchantId	string	特店代號
orderNumber	string	訂單編號
verifyCode	string	驗證碼
tw_pay_version	string	TaiwanPay 通道版本 ("1" 代表財金版)
otherInfo	OtherInfo	附加資料 (條件成立才回傳，例如發票載具) (optional)

2. 華南版 (HNCB) 回應內容

Name	Type	Description
storeId	string	特店代號
endpointCode	string	端末代號
terminalId	string	機台號
orderNumber	string	訂單編號
txnDir	string	交易方向 ("RS")
txnDateTime	string	交易時間 (yyyyMMddHHmmss)
txnAmt	string	交易金額
txnCurrency	string	幣別
txnSeqno	string	交易序號 (華南原廠唯一交易號，後續退款/查詢必備)
txnAccNO	string	交易帳號/卡號末五碼
respCode	string	回應代碼 ("0000" 或 "4001" 扣款成功；其餘為失敗)
respDesc	string	回應代碼說明
carrierType	string	手機條碼載具類別（如 "3J0002"，消費者條碼有載具時原廠自動帶出）
carrierId1	string	手機條碼載具號碼（如 "/UPP2YM2"，可直接用於電子發票開立）
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

Response Examples

範例一：財金版 Response

{
  "mti": "0210",
  "cardNumber": "0006147854124258",
  "processingCode": "012541",
  "amt": "000007434000",
  "systemDateTime": "1007160839",
  "traceNumber": "184845",
  "localTime": "184845",
  "localDate": "20180508",
  "acqBank": "005",
  "srrn": "280160839100",
  "responseCode": "0000",
  "terminalId": "00010001",
  "merchantId": "006263015610001",
  "orderNumber": "P201712310000003000",
  "verifyCode": "698408B75204AD6578E3539378BF07217B4ABADEB26FD0E09690B8A4F8BD2291",
  "tw_pay_version": "1"
}

範例二：華南版 Response

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

IntegratePay API Workflow

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

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

    C->>OP: Request [POST] /v1/payment/integrate/pay (帶入 tw_pay_version)
    activate OP
    OP->>OP: 參數檢核 (外部金流自帶參數 vs 門市設定)
    alt tw_pay_version == "0" (華南版)
        OP->>OP: 排除內部參數，依規則計算 Base64+SHA256 Sign 簽章
        OP->>PS: POST {taiwan_pay_url}/order (JSON Payload)
    else tw_pay_version == "1" (財金版)
        OP->>OP: 組裝 FiscIIQRAuth SOAP/XML
        OP->>PS: POST {taiwan_pay_focas_fisc_url}/QRauth (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，不發送外部請求至銀行端： - terminalId：必填，1~30 碼字串。 - orderNumber：必填，1~18 碼（不限字元集，由銀行判定）。 - txnAmt：必填，1~12 碼純數字（金額以分為單位，含兩位小數）。 - qrcode / txnFISCTac：二擇一必填。 - txnDateTime：選填，14 碼數字（yyyyMMddHHmmss）；未提供時由閘道自動補當下時間。 - 錯誤訊息結構範例：{"message": "欄位 terminalId 錯誤 Field required"} 或 {"message": "qrcode 與 txnFISCTac 必須至少提供一項"}。

業務錯誤代碼說明

代碼	說明	呼叫端處理建議
4001	交易成功	交易完成，紀錄交易序號
QR03	訂單編號正本重覆付款	此筆訂單已扣款成功，請勿重複扣款
0601 / 408	交易逾時	款項狀態不明，呼叫端必須調用 /v1/payment/integrate/search 查核最終扣款狀態