# 國泰金流串接 (EPOS)

這次要串接的是國泰提供的 [EPOS](https://sslpayment.uwccb.com.tw/EPOSPortal/index.aspx) 後台系統，它也是透過API串接來進行整合。
過去有串接過傳統的第三方金流的經驗，像是**藍新金流**、**綠界金流**，所以串接起來相對來說容易，因為其實這些金流相關流程都大同小異。

＊ 簡單說明一下所有串接的流程：

## 整體流程

# 特約商店： 你向國泰申請的帳號 ; 
# 國泰刷卡系統： 自動導向的國泰網頁

1. 「特約商店」以「Form Post」方式將「訂單付款資訊」傳遞給「國泰世華刷卡系統」。 
   -> 這時候的頁面會由“客戶官網”跳至“國泰刷卡機頁面”（輸入信用卡資訊)

2. 「用戶」將信用卡號等資料輸入完畢按下“確定鍵”後，會立即將信用卡付款資料傳送至「國泰世華信用卡授權網頁」(3ds)進行資料驗證與授權。   
   -> 此時會跳轉到另外一個頁面(信用卡確認付款頁面)，簡訊認證&用戶確認付款
   
3. 取得授權後，「授權網頁」回傳「商家提供的授權接收頁面」(callback_url)。
   -> 此時應該會跳到你的 callback_url 去驗證他回給你的 `strRsXML`
   
4. 同上，在驗證回傳資料後(Method: Post)必須回傳(return)一個 {XML Data} 提供下一個頁面導向給「國泰刷卡系統」。
   -> 此時就是 Response 一個 {RETURL} 給「國泰」

5. 最後會以(4.) 提供的RETURL來進行最後資料的傳遞。
   -> 這時才會 create Order 的時刻，表示付款確認並在`EPOS`系統有此筆紀錄

## 串接初始化
> 筆者所使用的語言是用 `Python3`，但因為文件所提供的範例為 `ASP.NET` 所以需要轉換一下。

#### ＊ 首先你必須建立三個 class 去處理整個 checkout 流程

* Checkout
* Callback
* Redirect

---

#### ＊ 將以「Form post」的方式傳遞 XML Data 至「網路刷卡機主網址」

=== *注意 name=strRqXML 不需更改 ===

# 將 value 丟入你所 build 的 XML (cavalue 要自己算)
# https://sslpayment.uwccb.com.tw/EPOSService/Payment/

<form name="main" action="{貼上主機網址}" method="post" >  
    <input type=hidden name="strRqXML" value="{你build的xml}">
</form>


=== *驗證值*必須按照提供的順序加密  ===
XML => {
    <?xml version='1.0' encoding='UTF-8'?>
    <MERCHANTXML>
        <CAVALUE>驗證值</CAVALUE>
        <MSGID>TRS0004</MSGID>
        <ORDERINFO>
            <STOREID>特店代號</STOREID>
            <ORDERNUMBER>訂單編號</ORDERNUMBER>
            <AMOUNT>授權金額</AMOUNT>
            <LANGUAGE>語系</LANGUAGE>
        </ORDERINFO>
    </MERCHANTXML>
}

---

#### ＊ 頁面跳轉至「國泰輸入信用卡頁面」，此時不需做任何處理。

此步驟為“用戶操作之行為”，與串接流程無直接相關

1. 輸入信用卡號
2. 寄送簡訊至信用卡綁定手機
3. 填入手機驗證碼
4. 確認送出

---

#### ＊ 當用戶付款完成，頁面即跳轉至你向國泰設定的 callback_url 頁面。

# 必須先向國泰窗口設定「商家授權結果接受網頁」(callback_url)
# 「國泰世華刷卡機」會將授權結果(strRsXML) 一樣以「FORM POST」回傳到「商家授權結果接收網頁」

=== ＊注意第四點的 RETURL 可以包含 PATH & Query Params ===
=== * 但是 在CAVALUE 驗證值時 只能包含 DOMAIN NAME     ===


1. 此時 API 以必須接收 FORM DATA(XML)的方式接收傳遞的資料
2. 接受資料並解析(PARSE) {strRsXML} 的值是否正確
3. 驗證“驗證值”是否一致(STOREID+ORDERNUMBER+AMOUNT...+CUBKEY)
4. 驗證無誤後，回傳 XML 給 「國泰世華刷卡機」
    RETURN => {
        <?xml version='1.0' encoding='UTF-8'?>
        <MERCHANTXML>
            <CAVALUE>驗證值</CAVALUE>
            <RETURL>商家訂單結果網址</RETURL>
        </MERCHANTXML>
    }

#### ＊ 最後將頁面導回 (Redirect) “商家訂單網頁”。

# 「國泰世華網路刷卡機」確認商店已收到授權結果後，將客戶導回商家網站
# 並回傳 “商店代碼” 與 “訂單編號” 供商店(strOrderInfo)比對

1. 此階段 API 同樣必須以 FORM POST (XML)的方式接收「國泰刷卡機」傳遞的資料
2. 接收資料並解析(PARSE){strOrderInfo}
3. 驗證“驗證值”是否一致(STOREID+ORDERNUMBER+CUBKEY)
4. 驗證無誤即開始 create Order Instance
    StrOrderInfo => {
       <?xml version='1.0' encoding='UTF-8'?>
       <CUBXML>
           <CAVALUE>驗證值</CAVALUE>
           <ORDERINFO>
              <STOREID>特店代號</STOREID>
              <ORDERNUMBER>訂單編號</ORDERNUMBER>
           </ORDERINFO>
       </CUBXML>
    }

---

## 總體心得
> [color=#6905a8]
> [color=#ba3103]
> [color=#3eba2e]

1. 串接起來有部分不順利，原因來自於文件寫得不夠清楚，像是value 是要放 XMLData 的標示不夠清楚
2. 再來是“輸入”、“輸出” 一詞實在太籠統，不太清楚實際的操作方式
3. 未提及 Callback URL 必須在哪裡設定，以及**無法自行設定很麻煩**
4. RETURL 驗證時只需驗證 DOMAIN 的部分很奇怪！？

## 相關文件

- [國泰EPOS(一般與分期付款)](https://drive.google.com/file/d/1bXBbS0mP6Lvg7bUzdmsxwey-wAPm04nA/view?usp=sharing)
- [國泰EPOS(API規格說明)](https://drive.google.com/file/d/1mO81kDfoziXaIHkOVNrL7cubhm225PKG/view?usp=sharing)

##### --- 筆記時間戳記 ---
>
> [time=Thu, Apr 29, 2021 2:00 PM]
> [color=#e24fd9]

---

###### tags: `api integration`