<style>
.text-center{
text-align: center; //文字置中
}
</style>
# 藍新金流

## Flow
其實藍新有提供超商，但我們沒有要用，所以就不列出了

<p class="text-center" style="">▲ 信用卡交易流程</p>

3D交易:收單方(Acquirer Domain)、發卡方(Issuer Domain) 和 連接前兩者的 數據交換方(Interoperability Domain)會用OTP密碼驗證交易的那種東西

<p class="text-center" style="">▲ 電子錢包交易流程</p>

<p class="text-center" style="">▲ Ｗeb ATM交易流程</p>


---
## APIs
* Encryption & Decryption
* 交易(MPG)
* 查詢(Query)
* 取消授權(Cancel)
* 請/退款(Close)
* 電子錢包退款(Wallet refund)

### Encryption & Decryption
### 因為金流安全緣故，上面5支API在呼叫的時候都需要加密過
會用到AES256、SHA256、CheckCode.

1. 將商店之 API 串接金鑰(Hash Key, Hash IV) 及商店代號(Merchant ID) 存好（要先在藍新金流平台建立商店，並已啟用支付工具）

2. 生成請求字串: 就是把所有要出去的params 包成這樣

    MerchantID=MS127874575&RespondType=String&TimeStamp=1695795410&Version=
    2.0&MerchantOrderNo=Vanespl_ec_1695795410&Amt=30&ItemDesc=test&NotifyUR
    L=https%3A%2F%2Fwebhook.site%2Fd4db5ad1-2278-466a-9d66-78585c0dbadb

3. 將請求字串加密以Hash Key& Hash IV 以 AES-256-CBC(PKCS7 Padding) 加密並轉為Hex
e.g.

    f79eac33c4f3245d58f17b544c5d38b09457a6d77e77bae6f10fcc7236fe153ccef1a80
    001c0746afc063a7570f80ad970d8a32c72332c9ec5547410188007876bdca2bafa52d0
    7d31b6b183f2204d6e4feee6d245e286ab198cf95422ad5843c7696fc943cbb65979ad2
    07607d4b5d97dac4a90ccd5e7a37adb7d7062e838be09d94e8c5dfa145c048e17feabe5
    8c2e310792f0f50f5af32961ffb07ff6649ae1021ad558242551de5f09316e3182e1987
    75e5d1ad5b66a70be290004de750fa85d86b0c2f087b40005d89e048be2ab6fd83f1c52
    2494c093426a10a1f73fe4

4. 將 AES 加密字串產生檢查碼
* 於加密字串前加上: HashKey=(the HashKey)&
* 於加密字串後加上: HashIV=(the HashIV)

    再以SHA256加密（加密後須為大寫）

5. 發Request
Params 如api定義,此處的生成AES,SHA256密文分別需以TradeInfo以及TradeSha帶入Request
6. Response會以NotifyURL回傳已加密字串,藍新會員專區可以設定網址，NotifyURL為webhook
* Response e.g.

        Status=SUCCESS&MerchantID=MS127874575&Version=2.0
        &TradeInfo=ee11d1501e6d...f01b4ecae96e81d0389e5f775
        &TradeSha=C80876AEBAC0036268C0E240E5BFF69C0470DE9606EEE083C5C8DD64FDB3347A

7. 解密Response
* 使用商店之 API 串接金鑰(Hash Key, Hash IV)進行 AES256 解密，需要先除去 PKCS7 的Padding 後再進行 AES 解密運算

* Res e.g.

    Status=SUCCESS
    &Message=%E6%8E%88%E6%AC%8A%E6%88%90%E5%8A%9F
    &MerchantID=MS127874575
    &Amt=30
    &TradeNo=23092714215835071
    &MerchantOrderNo=Vanespl_ec_1695795668
    &RespondType=String
    &IP=123.51.237.115
    &EscrowBank=HNCB
    &PaymentType=CREDIT
    &RespondCode=00
    &Auth=115468
    &Card6No=400022
    &Card4No=1111
    &Exp=2609
    &AuthBank=KGI
    &TokenUseStatus=0
    &InstFirst=0
    &InstEach=0
    &Inst=0
    &ECI=
    &PayTime=2023-09-27+14%3A21%3A59
    &PaymentMethod=CREDIT

8. CheckCode(交易)應該是用來驗證資料正確性的？ 還沒看懂能幹嘛
10. CheckValue(查詢):單筆交易查詢(Query)時，需生成一組 CheckValue
1. 將三個請求參數，分別是 Amt(金額)、MerchantID(商店代號)、MerchantOrderNo(商店訂單編號)，且照英文字母 A~Z 排序，若第一字母相同比較第二字母，以此類推，並用&符號串聯起來
2. 將串聯後的字串前加上：IV=(商店專屬加密 HashIV 值)
3. 將串聯後的字串後加上：Key=(與商店專屬加密 HashKey 值)
4. 將串聯後的字串用 SHA256 壓碼後轉大寫
在使用query api 時需帶入
### 交易 ```POST```
* Params

| 參數名稱 | 參數中文名稱 | 必填 | 型態 | 備註 |
| -------- | -------- | -------- | -------- | -------- |
| MerchantID | 商店代號 | ✅ | String(15) | 藍新金流商店代號 |
| TradeInfo | 交易資料AES 加密 | ✅ | 見下方 | 1.將交易資料參數（下方列表中數）透過商店 Key 及 IV 進行 AES 加密 |
| TradeSha | 交易資料SHA256 加密| ✅ | | 1.將交易資料經過上述 AES 加密過的字串，透過商店 Key 及 IV 進行 SHA256 加密 |
| Version | 串接程式版本 | ✅ | String(5) | 2.0 |
| EncryptType | 加密模式 | | Int(1) | 若商店設定加密模式</br>1 = 加密模式 AES/GCM</br> 0 或者未有此參數 =原加密模式 AES/CBC/PKCS7Padding |
* TradeInfo Params
:::info
其中比較重要的有: （✅ = required）
✅ MerchantID 商店代號
✅ RespondType 回傳格式 Json或String
✅ TimeStamp 時間戳記
✅ MerchantOrderNo 商店訂單編號
✅ Amt 訂單金額 NTD
✅ ItemDesc 商品資訊
❌ TradeLimit 交易有效時間 若未帶此參數，或是為 0 時，視作為不啟用交易限制秒數，秒數下限為 60 秒、上限為 900 秒
❌ ReturnURL 支付完成後返回商店網址
❌ Email 付款人電子信箱 於交易完成或付款完成時，通知付款人使用
:::spoiler 有點多 先隱藏起來 大部分都是支援金流選項
:::

* Response
| 參數名稱 | 參數中文名稱| 型態 | 備註 |
| -------- | -------- | -------- | -------- |
| Status | 回傳狀態 | String(10) | |
| MerchantID | 商店代號 | String(20) | 藍新金流商店代號 |
| TradeInfo | 交易資料 AES 加密 | | 將交易資料參數（下方列表中參數）透過商店 Key及 IV 進行 AES 加密。 |
| TradeSha | 交易資料 SHA256 加密 | | 將交易資料經過上述 AES 加密過的字串，透過商店Key 及 IV 再進行 SHA256 加密。 |
| Version | 串接程式版本 | String(5) | 串接程式版本 |
| EncryptType | 加密模式 | Int(1) | 若商店設定加密模式</br>1 = 加密模式 AES/GCM</br> 0 或者未有此參數 =原加密模式 AES/CBC/PKCS7Padding |

* TradeInfo Content
:::info
:::spoiler
:::

### 單筆交易查詢(Query) ```POST```
* Params

| 參數名稱 | 參數中文名稱 | 必填 | 型態 | 備註 |
| -------- | -------- | -------- | -------- | -------- |
| MerchantID | 商店代號 | ✅ | String(15) | 藍新金流商店代號 |
| Version | 串接程式版本 | ✅ | String(5) | 2.0 |
| RespondType | 回傳格式 | ✅ | String(6) | |
| CheckValue | 檢查碼 | ✅ | String(255) | |
| TimeStamp | 時間戳記 | ✅ | String(50) | |
| MerchantOrderNo | 商店訂單編號 | ✅ | String(30) | |
| Amt | 訂單金額 | ✅ | Int(10) | |
| CheckValue | 檢查碼 | ✅ | String(255) | |

* Response
| 參數名稱 | 參數中文名稱| 型態 | 備註 |
| -------- | -------- | -------- | -------- |
| Status | 回傳狀態 | String(10) | |
| Message | 回傳訊息 | String(30) | 文字，敘述此次交易查詢的狀態 |
| Result | 回傳內容 | | 若查詢成功，該筆交易詳細資訊會放到此欄位 |

* Result Content
:::info
其中比較重要的有: （✅ = required）
* MerchantID 商店代號
* Amt 交易金額
* TradeStatus 支付狀態 0=未付款 1=付款成功 2=付款失敗 3=取消付款 6=退款
* PaymentType 支付方式
:::spoiler

:::
### 取消授權(Cancel)
### 請/退款(Close)
### 電子錢包退款(Wallet refund)