Skip to content

Integrate TAIWAN QRCode Pay Refund

Description

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

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

Resource

POST /v1/payment/integrate/refund

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
cardNumber string 同原交易
processingCode string 處理代碼，請輸入 002543
amt string 交易金額，本欄位含二位小數位,需右靠左補 0
例如:台幣 123 元，其表示為 000000012300
traceNumber string 端末交易序號
localTime string 交易時間(hhmmss)
localDate string 交易日期(yyyyMMdd)
posEntryMode string 設備輸入型態，請輸入071
posConditionCode string 設備能力代碼，請輸入77
orderNumber string 訂單編號
txnCurrencyCode string 同原交易
orgTxnData orgTxnData 原始交易資訊

Request Body Parameters - orgTxnData (財金版專用)

Name Type Description
tag01 string 原交易類型，原 mti
tag02 string 端末設備型態,請輸入 002541
tag03 string 原交易金額，原 amt，本欄位含二位小數位,需右靠左補 0
例如:台幣 123 元，其表示為 000000012300
tag04 string 付款成功回傳的 systemDateTime 系統日期時間
tag08 string 付款成功回傳的 srrn 系統追蹤號

2. 華南版 (HNCB)

Name Type Description
storeId string 華銀收款方特店代號，X(20)
(自帶金流時必填)
orgEndpointCode string 華銀端末代號，X(08)
(自帶金流時必填，亦相容 endpointCode)
verifyCode string 華銀簽章密鑰，全通路計算 sign 後自動排除不送出
(自帶金流時必填)
terminalId string 機台號/端末號，X(30)，例如 "0101" (必填)
orgOrderNumber string 原訂單編號，N(18)，右靠左補 0 (必填，亦相容 orderNumber)
txnDateTime string 退款時間 (yyyyMMddHHmmss)，N(14) (必填)
orgAmt string 原交易金額，含二位小數（例如：台幣 100 元 → 10000），N(12) (必填，亦相容 amount)
txnSeqno string 華銀原交易序號，X(20) (必填)
isOrderRefund string 是否整筆訂單退款："Y" 全額退款 (目前僅支援全額退款/沖正) (optional)
orgCurrency string 幣別碼，請輸入 "901" (optional，預設 "901")
txnDir string 交易方向，請輸入 "RQ" (optional，預設 "RQ")
storeMemo string 店家備註 (optional)

Request Examples

範例一：財金版 (FISC)

{
  "type": "TAIWAN_QRCODE_PAY",
  "tw_pay_version": "1",
  "request": {
    "merchantId": "005276932381001",
    "terminalId": "10016338",
    "verifyCode": "5E8B6E1998F421204C6576544FE1A26B44FC775982D8CE2E",
    "acqBank": "005",
    "mti": "0200",
    "cardNumber": "4612630156100200",
    "processingCode": "002543",
    "amt": "000000934000",
    "traceNumber": "112105",
    "localTime": "112105",
    "localDate": "20221025",
    "posEntryMode": "071",
    "posConditionCode": "77",
    "orderNumber": "P2022102500005",
    "txnCurrencyCode": "901",
    "orgTxnData": {
      "tag01": "0200",
      "tag02": "002541",
      "tag03": "000000934000",
      "tag04": "1025112022",
      "tag08": "943003933901"
    }
  },
  "store_id": "0",
  "is_test": false
}

範例二：華南版 (HNCB)

{
  "type": "TAIWAN_QRCODE_PAY",
  "tw_pay_version": "0",
  "is_test": false,
  "request": {
    "storeId": "008123456780001",
    "orgEndpointCode": "00000001",
    "verifyCode": "5E8B6E1998F421204C6576544FE1A26B",
    "terminalId": "0101",
    "orgOrderNumber": "000020260910000001",
    "txnDateTime": "20260910140500",
    "orgAmt": "10000",
    "txnSeqno": "20260910140005012345",
    "isOrderRefund": "Y",
    "orgCurrency": "901",
    "txnDir": "RQ"
  }
}

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 端末交易序號
acqBank string 收單行代碼
srrn string 系統追蹤號
responseCode string 回應碼:
  • 0000: 成功
  • 其他: 失敗
terminalId string 端末代號
merchantId string 特店代號
orderNumber string 訂單編號
verifyCode string 驗證碼
tw_pay_version string TaiwanPay 通道版本 ("1" 代表財金版)

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

Name Type Description
storeId string 華銀收款方特店代號
endpointCode string 華銀端末代號
terminalId string 機台號/端末號
orderNumber string 訂單編號
txnDir string 交易方向 (RS)
txnDateTime string 交易時間 (yyyyMMddHHmmss)
txnAmt string 交易金額
txnCurrency string 幣別碼 (901)
txnSeqno string 華銀交易序號
respCode string 回應碼：4001 為成功，其餘為失敗代碼
respDesc string 回應代碼說明
sign string 華銀回傳之簽章
tw_pay_version string TaiwanPay 通道版本 ("0" 代表華南版)

Response Examples

範例一：財金版 (FISC) 回應

{
  "mti": "0210",
  "cardNumber": "4612630156100200",
  "processingCode": "002543",
  "amt": "000000934000",
  "systemDateTime": "1025112153",
  "traceNumber": "112105",
  "acqBank": "005",
  "srrn": "943003933902",
  "responseCode": "0000",
  "terminalId": "10016338",
  "merchantId": "005276932381001",
  "orderNumber": "P2022102500005",
  "verifyCode": "B12E974A228EB0B8EACDC2D5779AF983AAF9280471D4E8FCB12BC7D5B7B3DD2A",
  "tw_pay_version": "1"
}

範例二：華南版 (HNCB) 回應

{
  "storeId": "008123456780001",
  "endpointCode": "00000001",
  "terminalId": "0101",
  "orderNumber": "000020260910000001",
  "txnDir": "RS",
  "txnDateTime": "20260910140505",
  "txnAmt": "10000",
  "txnCurrency": "901",
  "txnSeqno": "20260910140505999999",
  "respCode": "4001",
  "respDesc": "退款成功",
  "sign": "3F89A1B2C...",
  "tw_pay_version": "0"
}

IntegrateRefund API Workflow

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

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

    C->>OP: POST /v1/payment/integrate/refund (帶入 tw_pay_version, request)
    activate OP
    OP->>OP: 執行 check_params_process (檢核必要欄位與自帶金流參數)
    alt 自帶金流參數缺少金鑰 verifyCode
        OP-->>C: 400 錯誤回應 (金流參數資料錯誤)
    end
    OP->>OP: 判定 tw_pay_version (0: HNCB, 1: FISC)
    alt tw_pay_version == "0" (華南版)
        OP->>OP: 組裝退款電文並以 verifyCode 進行 Base64+SHA-256 加簽
        OP->>PS: POST {taiwan_pay_url}/refund
        PS-->>OP: 回傳華南退款結果 JSON
    else tw_pay_version == "1" (財金版)
        OP->>OP: 組裝 FiscIIRefund2543 XML 電文與 3DES 簽章
        OP->>PS: POST {fisc_url}/refund2543
        PS-->>OP: 回傳財金 XML 結果
    end
    OP-->>C: 回傳 200 (直接回傳 JSON Object 結果)
    deactivate OP

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

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

當華南版退款請求參數缺漏、格式不符或為空值（null）時，全通路閘道將於入口處提早攔截並回傳 HTTP 400，不發送外部請求至銀行端： - terminalId：必填，1~30 碼字串。 - orgOrderNumber / orderNumber：二擇一必填，1~18 碼（不限字元集，由銀行判定）。 - orgAmt / amount：二擇一必填，純數字（含兩位小數）。 - txnSeqno / isOrderRefund：二擇一必填。帶 isOrderRefund=Y 表以訂單編號退款；否則須提供銀行端交易序號 txnSeqno。 - 錯誤訊息結構範例：{"message": "欄位 terminalId 錯誤 Field required"} 或 {"message": "orgOrderNumber 與 orderNumber 必須至少提供一項且長度不超過 18 碼"}。