taiwan-payment-skill 1.0.2 → 1.0.3

package/assets/taiwan-payment/references/payuni-payment-api.md

@@ -1,997 +1,997 @@
-# PayUni Payment API Reference
-
-統一金流 (PAYUNi) 金流 API 完整參考文件。
-
----
-
-## 目錄
-
-1. [API 端點總覽](#api-端點總覽)
-2. [測試環境](#測試環境)
-3. [加密機制](#加密機制)
-4. [通用參數](#通用參數)
-5. [整合式支付頁 (UPP)](#整合式支付頁-upp)
-6. [信用卡幕後](#信用卡幕後)
-7. [ATM 虛擬帳號](#atm-虛擬帳號)
-8. [超商代碼](#超商代碼)
-9. [LINE Pay](#line-pay)
-10. [AFTEE 先享後付](#aftee-先享後付)
-11. [Apple Pay / Google Pay / Samsung Pay](#apple-pay--google-pay--samsung-pay)
-12. [愛金卡 iCash](#愛金卡-icash)
-13. [交易查詢](#交易查詢)
-14. [交易請退款](#交易請退款)
-15. [交易取消授權](#交易取消授權)
-16. [信用卡約定 (Token)](#信用卡約定-token)
-17. [付款結果通知](#付款結果通知)
-18. [錯誤碼對照表](#錯誤碼對照表)
-19. [常見問題排解](#常見問題排解)
-
----
-
-## API 端點總覽
-
-### 基礎 API 路徑
-
-| 環境 | 基礎路徑 |
-|------|----------|
-| **測試環境** | `https://sandbox-api.payuni.com.tw/api/` |
-| **正式環境** | `https://api.payuni.com.tw/api/` |
-
-### 支付相關端點
-
-| 功能 | 端點路徑 | 說明 |
-|------|----------|------|
-| 整合式支付頁 | `/upp` | 導向 PayUni 支付頁面 |
-| ATM 虛擬帳號 | `/atm` | 幕後取得虛擬帳號 |
-| 超商代碼 | `/cvs` | 幕後取得繳費代碼 |
-| 信用卡幕後 | `/credit` | 信用卡直接扣款 |
-| LINE Pay | `/linepay` | LINE Pay 支付 |
-| AFTEE 先享後付 | `/aftee_direct` | AFTEE 支付 |
-
-### 交易管理端點
-
-| 功能 | 端點路徑 | 說明 |
-|------|----------|------|
-| 交易查詢 | `/trade_query` | 查詢交易狀態 |
-| 請退款 | `/trade_close` | 信用卡請款/退款 |
-| 取消授權 | `/trade_cancel` | 取消信用卡授權 |
-| CVS 取消 | `/cancel_cvs` | 取消超商代碼 |
-
-### 信用卡約定 (Token) 端點
-
-| 功能 | 端點路徑 | 說明 |
-|------|----------|------|
-| Token 查詢 | `/credit_bind_query` | 查詢約定信用卡 |
-| Token 取消 | `/credit_bind_cancel` | 取消約定信用卡 |
-
-### 特殊退款端點
-
-| 功能 | 端點路徑 | 說明 |
-|------|----------|------|
-| 愛金卡退款 | `/trade_refund_icash` | iCash 退款 |
-| AFTEE 退款 | `/trade_refund_aftee` | AFTEE 退款 |
-| AFTEE 確認 | `/trade_confirm_aftee` | AFTEE 確認交易 |
-| LINE Pay 退款 | `/trade_refund_linepay` | LINE Pay 退款 |
-
----
-
-## 測試環境
-
-### 測試帳號
-
-測試帳號請至 PayUni 後台申請：
-
-```
-後台網址: https://www.payuni.com.tw/
-路徑: 會員 > 商店清單 > 指定商店名稱 > 串接設定
-```
-
-取得以下資訊：
-- **商店代號 (MerID)**
-- **Hash Key**
-- **Hash IV**
-
-### 測試信用卡
-
-| 卡號 | 說明 |
-|------|------|
-| `4000-2211-1111-1111` | 測試用信用卡 |
-
-- **有效期限**: 任意未過期日期
-- **CVV/CVC**: 任意 3 碼
-
-### 測試環境端點
-
-```
-https://sandbox-api.payuni.com.tw/api/{endpoint}
-```
-
----
-
-## 加密機制
-
-PayUni 採用 **AES-256-GCM** 加密與 **SHA256 HMAC** 驗證。
-
-### 加密流程
-
-1. **準備參數** - 組合所有請求參數
-2. **URL Encode** - 將參數轉為 Query String
-3. **AES-256-GCM 加密** - 使用 Hash Key 和 Hash IV 加密
-4. **產生 HashInfo** - 使用 SHA256 計算驗證碼
-5. **發送請求** - 將加密資料 POST 至 API
-
-### PHP 加密範例
-
-```php
-<?php
-
-class PayuniEncryption
-{
-    private string $merKey;
-    private string $merIV;
-
-    public function __construct(string $merKey, string $merIV)
-    {
-        $this->merKey = $merKey;
-        $this->merIV = $merIV;
-    }
-
-    /**
-     * AES-256-GCM 加密
-     */
-    public function encrypt(array $params): string
-    {
-        // 1. 組合 Query String
-        $queryString = http_build_query($params);
-
-        // 2. AES-256-GCM 加密
-        $tag = '';
-        $encrypted = openssl_encrypt(
-            $queryString,
-            'aes-256-gcm',
-            $this->merKey,
-            OPENSSL_RAW_DATA,
-            $this->merIV,
-            $tag,
-            '',
-            16
-        );
-
-        // 3. 組合加密結果 (加密資料 + tag)
-        $encryptInfo = bin2hex($encrypted . $tag);
-
-        return $encryptInfo;
-    }
-
-    /**
-     * AES-256-GCM 解密
-     */
-    public function decrypt(string $encryptInfo): array
-    {
-        // 1. Hex 轉 Binary
-        $data = hex2bin($encryptInfo);
-
-        // 2. 分離加密資料和 tag
-        $encrypted = substr($data, 0, -16);
-        $tag = substr($data, -16);
-
-        // 3. AES-256-GCM 解密
-        $decrypted = openssl_decrypt(
-            $encrypted,
-            'aes-256-gcm',
-            $this->merKey,
-            OPENSSL_RAW_DATA,
-            $this->merIV,
-            $tag
-        );
-
-        // 4. 解析 Query String
-        parse_str($decrypted, $result);
-
-        return $result;
-    }
-
-    /**
-     * 產生 HashInfo (SHA256)
-     */
-    public function hashInfo(string $encryptInfo): string
-    {
-        $raw = $encryptInfo . $this->merKey . $this->merIV;
-        return strtoupper(hash('sha256', $raw));
-    }
-}
-```
-
-### Python 加密範例
-
-```python
-"""PayUni AES-256-GCM 加密"""
-
-from Crypto.Cipher import AES
-from urllib.parse import urlencode, parse_qs
-import hashlib
-
-
-class PayuniEncryption:
-    def __init__(self, mer_key: str, mer_iv: str):
-        self.mer_key = mer_key.encode('utf-8')
-        self.mer_iv = mer_iv.encode('utf-8')
-
-    def encrypt(self, params: dict) -> str:
-        """AES-256-GCM 加密"""
-        # 1. 組合 Query String
-        query_string = urlencode(params)
-
-        # 2. AES-256-GCM 加密
-        cipher = AES.new(self.mer_key, AES.MODE_GCM, nonce=self.mer_iv)
-        encrypted, tag = cipher.encrypt_and_digest(query_string.encode('utf-8'))
-
-        # 3. 組合加密結果
-        encrypt_info = (encrypted + tag).hex()
-
-        return encrypt_info
-
-    def decrypt(self, encrypt_info: str) -> dict:
-        """AES-256-GCM 解密"""
-        # 1. Hex 轉 Binary
-        data = bytes.fromhex(encrypt_info)
-
-        # 2. 分離加密資料和 tag
-        encrypted = data[:-16]
-        tag = data[-16:]
-
-        # 3. AES-256-GCM 解密
-        cipher = AES.new(self.mer_key, AES.MODE_GCM, nonce=self.mer_iv)
-        decrypted = cipher.decrypt_and_verify(encrypted, tag)
-
-        # 4. 解析 Query String
-        result = dict(parse_qs(decrypted.decode('utf-8')))
-        return {k: v[0] for k, v in result.items()}
-
-    def hash_info(self, encrypt_info: str) -> str:
-        """產生 HashInfo (SHA256)"""
-        raw = encrypt_info + self.mer_key.decode() + self.mer_iv.decode()
-        return hashlib.sha256(raw.encode('utf-8')).hexdigest().upper()
-```
-
----
-
-## 通用參數
-
-### 請求參數
-
-所有 API 請求都需要以下參數：
-
-| 參數 | 類型 | 必填 | 說明 |
-|------|------|------|------|
-| `MerID` | String | ✓ | 商店代號 |
-| `Version` | String | 否 | API 版本，預設 `1.0` (LINE Pay 預設 `1.1`) |
-| `EncryptInfo` | String | ✓ | AES-256-GCM 加密後的參數 |
-| `HashInfo` | String | ✓ | SHA256 驗證碼 |
-
-### EncryptInfo 內容參數
-
-以下參數需加密放入 `EncryptInfo`：
-
-| 參數 | 類型 | 長度 | 必填 | 說明 |
-|------|------|------|------|------|
-| `MerID` | String | 20 | ✓ | 商店代號 |
-| `MerTradeNo` | String | 50 | ✓ | 商店訂單編號，需唯一 |
-| `TradeAmt` | Integer | - | ✓ | 交易金額 (整數) |
-| `Timestamp` | Integer | - | ✓ | Unix 時間戳 |
-| `ProdDesc` | String | 100 | 否 | 商品描述 |
-| `UsrMail` | String | 100 | 否 | 消費者 Email |
-| `ReturnURL` | String | 500 | 否 | 前台返回網址 |
-| `NotifyURL` | String | 500 | 否 | 背景通知網址 |
-| `Lang` | String | 5 | 否 | 語系 `zh-tw` / `en` |
-
-### API 回應格式
-
-```json
-{
-  "Status": "SUCCESS",
-  "Message": "成功",
-  "EncryptInfo": "加密後的回應資料",
-  "HashInfo": "SHA256 驗證碼"
-}
-```
-
-### Status 狀態碼
-
-| 狀態 | 說明 |
-|------|------|
-| `SUCCESS` | 成功 |
-| `ERROR` | 失敗 |
-
----
-
-## 整合式支付頁 (UPP)
-
-導向 PayUni 整合式支付頁面，消費者可選擇付款方式。
-
-### 端點
-
-```
-POST /api/upp
-```
-
-### EncryptInfo 參數
-
-| 參數 | 類型 | 必填 | 說明 |
-|------|------|------|------|
-| `MerID` | String | ✓ | 商店代號 |
-| `MerTradeNo` | String | ✓ | 訂單編號 |
-| `TradeAmt` | Integer | ✓ | 交易金額 |
-| `Timestamp` | Integer | ✓ | Unix 時間戳 |
-| `ExpireDate` | Integer | 否 | 繳費期限 (天)，`1`~`180`，預設 `7` |
-| `ProdDesc` | String | 否 | 商品描述 |
-| `UsrMail` | String | 否 | 消費者 Email |
-| `ReturnURL` | String | 否 | 前台返回網址 |
-| `NotifyURL` | String | 否 | 背景通知網址 |
-| `Lang` | String | 否 | 語系 `zh-tw` / `en` |
-
-### 支援的付款方式
-
-整合式支付頁可顯示以下付款方式 (依商店設定)：
-
-- 信用卡 (一次付清、分期、紅利折抵)
-- ATM 虛擬帳號
-- 超商代碼
-- Apple Pay
-- Google Pay
-- Samsung Pay
-- LINE Pay
-- AFTEE 先享後付
-- 愛金卡 iCash
-
-### PHP 範例
-
-```php
-<?php
-
-$encryption = new PayuniEncryption($merKey, $merIV);
-
-$params = [
-    'MerID' => 'YOUR_MER_ID',
-    'MerTradeNo' => 'ORDER' . time(),
-    'TradeAmt' => 1000,
-    'Timestamp' => time(),
-    'ProdDesc' => '測試商品',
-    'ReturnURL' => 'https://your-site.com/return',
-    'NotifyURL' => 'https://your-site.com/notify',
-];
-
-$encryptInfo = $encryption->encrypt($params);
-$hashInfo = $encryption->hashInfo($encryptInfo);
-
-// 產生表單
-$html = <<<HTML
-<form method="post" action="https://api.payuni.com.tw/api/upp">
-    <input type="hidden" name="MerID" value="{$params['MerID']}">
-    <input type="hidden" name="Version" value="1.0">
-    <input type="hidden" name="EncryptInfo" value="{$encryptInfo}">
-    <input type="hidden" name="HashInfo" value="{$hashInfo}">
-    <button type="submit">前往付款</button>
-</form>
-HTML;
-
-echo $html;
-```
-
----
-
-## 信用卡幕後
-
-直接在商店頁面完成信用卡扣款，不需導向 PayUni。
-
-### 端點
-
-```
-POST /api/credit
-```
-
-### EncryptInfo 參數
-
-| 參數 | 類型 | 必填 | 說明 |
-|------|------|------|------|
-| `MerID` | String | ✓ | 商店代號 |
-| `MerTradeNo` | String | ✓ | 訂單編號 |
-| `TradeAmt` | Integer | ✓ | 交易金額 |
-| `Timestamp` | Integer | ✓ | Unix 時間戳 |
-| `CardNo` | String | ✓ | 信用卡號 (16 碼) |
-| `CardExpiry` | String | ✓ | 有效期限 `MMYY` |
-| `CardCVC` | String | ✓ | 安全碼 (3 碼) |
-| `ProdDesc` | String | 否 | 商品描述 |
-| `UsrMail` | String | 否 | 消費者 Email |
-| `NotifyURL` | String | 否 | 背景通知網址 |
-
-### 分期付款參數
-
-| 參數 | 類型 | 說明 |
-|------|------|------|
-| `Inst` | Integer | 分期期數 `3`, `6`, `12`, `18`, `24`, `30` |
-
-### 紅利折抵參數
-
-| 參數 | 類型 | 說明 |
-|------|------|------|
-| `Red` | String | 啟用紅利折抵 `Y` |
-
-### 銀聯卡參數
-
-| 參數 | 類型 | 說明 |
-|------|------|------|
-| `UnionPay` | Integer | `1`:使用銀聯 |
-
-### 信用卡約定 (Token) 參數
-
-| 參數 | 類型 | 說明 |
-|------|------|------|
-| `UseTokenType` | Integer | `1`:建立 Token `2`:使用既有 Token |
-| `BindVal` | String | Token 代碼 (UseTokenType=2 時必填) |
-
----
-
-## ATM 虛擬帳號
-
-取得 ATM 繳費虛擬帳號。
-
-### 端點
-
-```
-POST /api/atm
-```
-
-### EncryptInfo 參數
-
-| 參數 | 類型 | 必填 | 說明 |
-|------|------|------|------|
-| `MerID` | String | ✓ | 商店代號 |
-| `MerTradeNo` | String | ✓ | 訂單編號 |
-| `TradeAmt` | Integer | ✓ | 交易金額 |
-| `Timestamp` | Integer | ✓ | Unix 時間戳 |
-| `ExpireDate` | Integer | 否 | 繳費期限 (天)，`1`~`60`，預設 `3` |
-| `BankType` | String | 否 | 指定銀行 (參見下表) |
-| `NotifyURL` | String | 否 | 背景通知網址 |
-
-### BankType 銀行代碼
-
-| 代碼 | 銀行 |
-|------|------|
-| `FIRST` | 第一銀行 |
-| `ESUN` | 玉山銀行 |
-| `TAISHIN` | 台新銀行 |
-| `CATHAY` | 國泰世華 |
-| `CHINATRUST` | 中國信託 |
-
-### 回應參數 (解密後)
-
-| 參數 | 說明 |
-|------|------|
-| `TradeNo` | PayUni 交易編號 |
-| `BankCode` | 銀行代碼 (3 碼) |
-| `vAccount` | 虛擬帳號 (14~16 碼) |
-| `ExpireDate` | 繳費期限 `yyyy/MM/dd` |
-
----
-
-## 超商代碼
-
-取得超商繳費代碼。
-
-### 端點
-
-```
-POST /api/cvs
-```
-
-### EncryptInfo 參數
-
-| 參數 | 類型 | 必填 | 說明 |
-|------|------|------|------|
-| `MerID` | String | ✓ | 商店代號 |
-| `MerTradeNo` | String | ✓ | 訂單編號 |
-| `TradeAmt` | Integer | ✓ | 交易金額 (`30`~`20000`) |
-| `Timestamp` | Integer | ✓ | Unix 時間戳 |
-| `ExpireDate` | Integer | 否 | 繳費期限 (天)，預設 `7` |
-| `NotifyURL` | String | 否 | 背景通知網址 |
-
-### 金額限制
-
-| 項目 | 限制 |
-|------|------|
-| 最低金額 | 30 元 |
-| 最高金額 | 20,000 元 |
-
-### 回應參數 (解密後)
-
-| 參數 | 說明 |
-|------|------|
-| `TradeNo` | PayUni 交易編號 |
-| `PayNo` | 繳費代碼 |
-| `ExpireDate` | 繳費期限 |
-
----
-
-## LINE Pay
-
-LINE Pay 支付整合。
-
-### 端點
-
-```
-POST /api/linepay
-```
-
-### 版本
-
-```
-Version: 1.1
-```
-
-### EncryptInfo 參數
-
-| 參數 | 類型 | 必填 | 說明 |
-|------|------|------|------|
-| `MerID` | String | ✓ | 商店代號 |
-| `MerTradeNo` | String | ✓ | 訂單編號 |
-| `TradeAmt` | Integer | ✓ | 交易金額 |
-| `Timestamp` | Integer | ✓ | Unix 時間戳 |
-| `ProdDesc` | String | ✓ | 商品描述 |
-| `ReturnURL` | String | ✓ | 付款完成返回網址 |
-| `NotifyURL` | String | 否 | 背景通知網址 |
-
-### LINE Pay 退款
-
-#### 端點
-
-```
-POST /api/trade_refund_linepay
-```
-
-#### EncryptInfo 參數
-
-| 參數 | 類型 | 必填 | 說明 |
-|------|------|------|------|
-| `MerID` | String | ✓ | 商店代號 |
-| `TradeNo` | String | ✓ | PayUni 交易編號 |
-| `TradeAmt` | Integer | ✓ | 退款金額 |
-| `Timestamp` | Integer | ✓ | Unix 時間戳 |
-
----
-
-## AFTEE 先享後付
-
-AFTEE 後支付整合。
-
-### 端點
-
-```
-POST /api/aftee_direct
-```
-
-### EncryptInfo 參數
-
-| 參數 | 類型 | 必填 | 說明 |
-|------|------|------|------|
-| `MerID` | String | ✓ | 商店代號 |
-| `MerTradeNo` | String | ✓ | 訂單編號 |
-| `TradeAmt` | Integer | ✓ | 交易金額 |
-| `Timestamp` | Integer | ✓ | Unix 時間戳 |
-| `ProdDesc` | String | ✓ | 商品描述 |
-| `UsrMail` | String | ✓ | 消費者 Email |
-| `UsrName` | String | ✓ | 消費者姓名 |
-| `UsrPhone` | String | ✓ | 消費者手機 |
-| `ReturnURL` | String | ✓ | 付款完成返回網址 |
-| `NotifyURL` | String | 否 | 背景通知網址 |
-
-### AFTEE 確認交易
-
-當 AFTEE 交易需要確認時：
-
-```
-POST /api/trade_confirm_aftee
-```
-
-### AFTEE 退款
-
-```
-POST /api/trade_refund_aftee
-```
-
----
-
-## Apple Pay / Google Pay / Samsung Pay
-
-行動支付整合 (需透過整合式支付頁或前端 SDK)。
-
-### 支援說明
-
-| 支付方式 | 說明 |
-|----------|------|
-| Apple Pay | Safari 瀏覽器、iOS/macOS 裝置 |
-| Google Pay | Chrome 瀏覽器、Android 裝置 |
-| Samsung Pay | Samsung 裝置 |
-
-### 使用方式
-
-透過整合式支付頁 (UPP) 使用，商店需向 PayUni 申請開通。
-
----
-
-## 愛金卡 iCash
-
-愛金卡 (iCash) 支付。
-
-### 退款端點
-
-```
-POST /api/trade_refund_icash
-```
-
-### EncryptInfo 參數
-
-| 參數 | 類型 | 必填 | 說明 |
-|------|------|------|------|
-| `MerID` | String | ✓ | 商店代號 |
-| `TradeNo` | String | ✓ | PayUni 交易編號 |
-| `TradeAmt` | Integer | ✓ | 退款金額 |
-| `Timestamp` | Integer | ✓ | Unix 時間戳 |
-
----
-
-## 交易查詢
-
-查詢交易狀態。
-
-### 端點
-
-```
-POST /api/trade_query
-```
-
-### EncryptInfo 參數
-
-| 參數 | 類型 | 必填 | 說明 |
-|------|------|------|------|
-| `MerID` | String | ✓ | 商店代號 |
-| `MerTradeNo` | String | ✓ | 商店訂單編號 |
-| `Timestamp` | Integer | ✓ | Unix 時間戳 |
-
-### 回應參數 (解密後)
-
-| 參數 | 說明 |
-|------|------|
-| `TradeNo` | PayUni 交易編號 |
-| `MerTradeNo` | 商店訂單編號 |
-| `TradeAmt` | 交易金額 |
-| `TradeStatus` | 交易狀態 |
-| `PaymentType` | 付款方式 |
-| `CreateTime` | 訂單建立時間 |
-| `PayTime` | 付款時間 |
-
-### TradeStatus 交易狀態
-
-| 狀態 | 說明 |
-|------|------|
-| `0` | 未付款 / 處理中 |
-| `1` | 已付款 |
-| `2` | 付款失敗 |
-| `3` | 已退款 |
-
-### PHP 範例
-
-```php
-<?php
-
-$encryption = new PayuniEncryption($merKey, $merIV);
-
-$params = [
-    'MerID' => 'YOUR_MER_ID',
-    'MerTradeNo' => 'ORDER1234567890',
-    'Timestamp' => time(),
-];
-
-$encryptInfo = $encryption->encrypt($params);
-$hashInfo = $encryption->hashInfo($encryptInfo);
-
-$response = file_get_contents('https://api.payuni.com.tw/api/trade_query', false, stream_context_create([
-    'http' => [
-        'method' => 'POST',
-        'header' => 'Content-Type: application/x-www-form-urlencoded',
-        'content' => http_build_query([
-            'MerID' => $params['MerID'],
-            'Version' => '1.0',
-            'EncryptInfo' => $encryptInfo,
-            'HashInfo' => $hashInfo,
-        ]),
-    ],
-]));
-
-$result = json_decode($response, true);
-
-if ($result['Status'] === 'SUCCESS') {
-    $data = $encryption->decrypt($result['EncryptInfo']);
-    print_r($data);
-}
-```
-
----
-
-## 交易請退款
-
-信用卡請款或退款。
-
-### 端點
-
-```
-POST /api/trade_close
-```
-
-### EncryptInfo 參數
-
-| 參數 | 類型 | 必填 | 說明 |
-|------|------|------|------|
-| `MerID` | String | ✓ | 商店代號 |
-| `TradeNo` | String | ✓ | PayUni 交易編號 |
-| `CloseType` | Integer | ✓ | 操作類型 |
-| `CloseAmt` | Integer | 否 | 請退款金額 (部分退款時使用) |
-| `Timestamp` | Integer | ✓ | Unix 時間戳 |
-
-### CloseType 操作類型
-
-| 代碼 | 說明 |
-|------|------|
-| `1` | 請款 (Capture) |
-| `2` | 退款 (Refund) |
-
-### 退款限制
-
-- 支援部分退款
-- 退款金額需小於等於原交易金額
-- 信用卡退款期限：請款後 1 年內
-
----
-
-## 交易取消授權
-
-取消信用卡授權 (尚未請款)。
-
-### 端點
-
-```
-POST /api/trade_cancel
-```
-
-### EncryptInfo 參數
-
-| 參數 | 類型 | 必填 | 說明 |
-|------|------|------|------|
-| `MerID` | String | ✓ | 商店代號 |
-| `TradeNo` | String | ✓ | PayUni 交易編號 |
-| `Timestamp` | Integer | ✓ | Unix 時間戳 |
-
----
-
-## 信用卡約定 (Token)
-
-### 查詢約定信用卡
-
-#### 端點
-
-```
-POST /api/credit_bind_query
-```
-
-#### EncryptInfo 參數
-
-| 參數 | 類型 | 必填 | 說明 |
-|------|------|------|------|
-| `MerID` | String | ✓ | 商店代號 |
-| `BindVal` | String | ✓ | Token 代碼 |
-| `Timestamp` | Integer | ✓ | Unix 時間戳 |
-
-### 取消約定信用卡
-
-#### 端點
-
-```
-POST /api/credit_bind_cancel
-```
-
-#### EncryptInfo 參數
-
-| 參數 | 類型 | 必填 | 說明 |
-|------|------|------|------|
-| `MerID` | String | ✓ | 商店代號 |
-| `BindVal` | String | ✓ | Token 代碼 |
-| `Timestamp` | Integer | ✓ | Unix 時間戳 |
-
----
-
-## 付款結果通知
-
-### 通知流程
-
-```
-┌─────────────┐     ┌─────────────┐     ┌─────────────┐
-│   消費者    │────▶│   PayUni    │────▶│    商店     │
-│   付款     │     │    處理     │     │ NotifyURL  │
-└─────────────┘     └─────────────┘     └─────────────┘
-                          │
-                          │ POST (加密資料)
-                          ▼
-                    ┌─────────────┐
-                    │    商店     │
-                    │  解密處理   │
-                    └─────────────┘
-                          │
-                          │ 回應 "SUCCESS"
-                          ▼
-                    ┌─────────────┐
-                    │   PayUni    │
-                    │  確認收到   │
-                    └─────────────┘
-```
-
-### 通知參數
-
-PayUni 會 POST 加密資料到 `NotifyURL`：
-
-| 參數 | 說明 |
-|------|------|
-| `MerID` | 商店代號 |
-| `EncryptInfo` | 加密的交易結果 |
-| `HashInfo` | SHA256 驗證碼 |
-
-### 解密後的通知內容
-
-| 參數 | 說明 |
-|------|------|
-| `MerID` | 商店代號 |
-| `MerTradeNo` | 商店訂單編號 |
-| `TradeNo` | PayUni 交易編號 |
-| `TradeAmt` | 交易金額 |
-| `TradeStatus` | 交易狀態 (`0`:處理中 `1`:成功) |
-| `PaymentType` | 付款方式 |
-| `CreateTime` | 訂單建立時間 |
-| `PayTime` | 付款時間 |
-| `Message` | 交易訊息 |
-| `Card4No` | 信用卡末四碼 (信用卡交易) |
-| `AuthCode` | 銀行授權碼 (信用卡交易) |
-
-### 處理範例
-
-```php
-<?php
-
-// 接收通知
-$encryptInfo = $_POST['EncryptInfo'] ?? '';
-$hashInfo = $_POST['HashInfo'] ?? '';
-$merID = $_POST['MerID'] ?? '';
-
-// 驗證 HashInfo
-$encryption = new PayuniEncryption($merKey, $merIV);
-$calculatedHash = $encryption->hashInfo($encryptInfo);
-
-if ($hashInfo !== $calculatedHash) {
-    echo 'HashInfo Error';
-    exit;
-}
-
-// 解密
-$data = $encryption->decrypt($encryptInfo);
-
-// 檢查交易狀態
-if ($data['TradeStatus'] === '1') {
-    // 交易成功，更新訂單狀態
-    updateOrderStatus($data['MerTradeNo'], 'paid', $data);
-}
-
-// 回應 SUCCESS
-echo 'SUCCESS';
-```
-
----
-
-## 錯誤碼對照表
-
-### 交易狀態 (TradeStatus)
-
-| 狀態 | 說明 |
-|------|------|
-| `0` | 未付款 / 處理中 |
-| `1` | 已付款 / 成功 |
-| `2` | 付款失敗 |
-| `3` | 已退款 |
-
-### 常見錯誤訊息
-
-| 錯誤碼 | 說明 | 處理方式 |
-|--------|------|----------|
-| `參數錯誤` | 必填參數缺失或格式錯誤 | 檢查參數格式 |
-| `商店代號錯誤` | MerID 不存在 | 確認商店代號 |
-| `訂單編號重複` | MerTradeNo 已使用 | 使用新的訂單編號 |
-| `HashInfo 驗證失敗` | 加密資料不正確 | 重新計算 HashInfo |
-| `交易金額錯誤` | 金額超出範圍 | 確認金額限制 |
-| `卡片授權失敗` | 信用卡交易被拒 | 請客戶聯繫發卡銀行 |
-| `餘額不足` | 信用卡額度不足 | 請客戶確認額度 |
-| `卡片過期` | 信用卡已過期 | 請客戶使用有效卡片 |
-
----
-
-## 常見問題排解
-
-### HashInfo 驗證失敗
-
-**問題**: 收到 `HashInfo 驗證失敗`
-
-**檢查項目**:
-1. Hash Key 和 Hash IV 是否正確
-2. AES-256-GCM 加密是否正確實作
-3. SHA256 計算是否正確
-4. 測試/正式環境金鑰是否混用
-
-### 訂單編號重複
-
-**問題**: 收到 `訂單編號重複`
-
-**解決**:
-```python
-import time
-import random
-order_id = f"ORD{int(time.time())}{random.randint(100, 999)}"
-```
-
-### 付款通知未收到
-
-**問題**: 付款成功但沒收到 NotifyURL 通知
-
-**檢查項目**:
-1. NotifyURL 是否為 HTTPS
-2. 伺服器是否能被外網存取
-3. 是否正確回應 `SUCCESS`
-4. 防火牆是否阻擋 PayUni IP
-
-### 加密/解密問題
-
-**問題**: 加密資料無法解密
-
-**檢查項目**:
-1. AES-256-GCM 參數是否正確 (Key 32 bytes, IV 16 bytes)
-2. Tag 長度是否為 16 bytes
-3. Hex 編碼/解碼是否正確
-
----
-
-## SDK 資源
-
-### 官方 SDK
-
-| 語言 | GitHub |
-|------|--------|
-| PHP | https://github.com/payuni/PHP_SDK |
-| .NET | https://github.com/payuni/NET_SDK |
-
-### 安裝方式
-
-#### PHP (Composer)
-
-```bash
-composer require payuni/sdk
-```
-
-#### .NET (NuGet)
-
-需要安裝以下套件：
-- Newtonsoft.Json (13.0.1+)
-- Portable.BouncyCastle (1.9.0+)
-
----
-
-## 官方資源
-
-- **官方網站**: https://www.payuni.com.tw/
-- **API 文件**: https://www.payuni.com.tw/docs/web/
-- **GitHub**: https://github.com/payuni
-- **WooCommerce 外掛**: https://github.com/payuni/PAYUNi_for_WooCommerce
+# PayUni Payment API Reference
+
+統一金流 (PAYUNi) 金流 API 完整參考文件。
+
+---
+
+## 目錄
+
+1. [API 端點總覽](#api-端點總覽)
+2. [測試環境](#測試環境)
+3. [加密機制](#加密機制)
+4. [通用參數](#通用參數)
+5. [整合式支付頁 (UPP)](#整合式支付頁-upp)
+6. [信用卡幕後](#信用卡幕後)
+7. [ATM 虛擬帳號](#atm-虛擬帳號)
+8. [超商代碼](#超商代碼)
+9. [LINE Pay](#line-pay)
+10. [AFTEE 先享後付](#aftee-先享後付)
+11. [Apple Pay / Google Pay / Samsung Pay](#apple-pay--google-pay--samsung-pay)
+12. [愛金卡 iCash](#愛金卡-icash)
+13. [交易查詢](#交易查詢)
+14. [交易請退款](#交易請退款)
+15. [交易取消授權](#交易取消授權)
+16. [信用卡約定 (Token)](#信用卡約定-token)
+17. [付款結果通知](#付款結果通知)
+18. [錯誤碼對照表](#錯誤碼對照表)
+19. [常見問題排解](#常見問題排解)
+
+---
+
+## API 端點總覽
+
+### 基礎 API 路徑
+
+| 環境 | 基礎路徑 |
+|------|----------|
+| **測試環境** | `https://sandbox-api.payuni.com.tw/api/` |
+| **正式環境** | `https://api.payuni.com.tw/api/` |
+
+### 支付相關端點
+
+| 功能 | 端點路徑 | 說明 |
+|------|----------|------|
+| 整合式支付頁 | `/upp` | 導向 PayUni 支付頁面 |
+| ATM 虛擬帳號 | `/atm` | 幕後取得虛擬帳號 |
+| 超商代碼 | `/cvs` | 幕後取得繳費代碼 |
+| 信用卡幕後 | `/credit` | 信用卡直接扣款 |
+| LINE Pay | `/linepay` | LINE Pay 支付 |
+| AFTEE 先享後付 | `/aftee_direct` | AFTEE 支付 |
+
+### 交易管理端點
+
+| 功能 | 端點路徑 | 說明 |
+|------|----------|------|
+| 交易查詢 | `/trade_query` | 查詢交易狀態 |
+| 請退款 | `/trade_close` | 信用卡請款/退款 |
+| 取消授權 | `/trade_cancel` | 取消信用卡授權 |
+| CVS 取消 | `/cancel_cvs` | 取消超商代碼 |
+
+### 信用卡約定 (Token) 端點
+
+| 功能 | 端點路徑 | 說明 |
+|------|----------|------|
+| Token 查詢 | `/credit_bind_query` | 查詢約定信用卡 |
+| Token 取消 | `/credit_bind_cancel` | 取消約定信用卡 |
+
+### 特殊退款端點
+
+| 功能 | 端點路徑 | 說明 |
+|------|----------|------|
+| 愛金卡退款 | `/trade_refund_icash` | iCash 退款 |
+| AFTEE 退款 | `/trade_refund_aftee` | AFTEE 退款 |
+| AFTEE 確認 | `/trade_confirm_aftee` | AFTEE 確認交易 |
+| LINE Pay 退款 | `/trade_refund_linepay` | LINE Pay 退款 |
+
+---
+
+## 測試環境
+
+### 測試帳號
+
+測試帳號請至 PayUni 後台申請：
+
+```
+後台網址: https://www.payuni.com.tw/
+路徑: 會員 > 商店清單 > 指定商店名稱 > 串接設定
+```
+
+取得以下資訊：
+- **商店代號 (MerID)**
+- **Hash Key**
+- **Hash IV**
+
+### 測試信用卡
+
+| 卡號 | 說明 |
+|------|------|
+| `4000-2211-1111-1111` | 測試用信用卡 |
+
+- **有效期限**: 任意未過期日期
+- **CVV/CVC**: 任意 3 碼
+
+### 測試環境端點
+
+```
+https://sandbox-api.payuni.com.tw/api/{endpoint}
+```
+
+---
+
+## 加密機制
+
+PayUni 採用 **AES-256-GCM** 加密與 **SHA256 HMAC** 驗證。
+
+### 加密流程
+
+1. **準備參數** - 組合所有請求參數
+2. **URL Encode** - 將參數轉為 Query String
+3. **AES-256-GCM 加密** - 使用 Hash Key 和 Hash IV 加密
+4. **產生 HashInfo** - 使用 SHA256 計算驗證碼
+5. **發送請求** - 將加密資料 POST 至 API
+
+### PHP 加密範例
+
+```php
+<?php
+
+class PayuniEncryption
+{
+    private string $merKey;
+    private string $merIV;
+
+    public function __construct(string $merKey, string $merIV)
+    {
+        $this->merKey = $merKey;
+        $this->merIV = $merIV;
+    }
+
+    /**
+     * AES-256-GCM 加密
+     */
+    public function encrypt(array $params): string
+    {
+        // 1. 組合 Query String
+        $queryString = http_build_query($params);
+
+        // 2. AES-256-GCM 加密
+        $tag = '';
+        $encrypted = openssl_encrypt(
+            $queryString,
+            'aes-256-gcm',
+            $this->merKey,
+            OPENSSL_RAW_DATA,
+            $this->merIV,
+            $tag,
+            '',
+            16
+        );
+
+        // 3. 組合加密結果 (加密資料 + tag)
+        $encryptInfo = bin2hex($encrypted . $tag);
+
+        return $encryptInfo;
+    }
+
+    /**
+     * AES-256-GCM 解密
+     */
+    public function decrypt(string $encryptInfo): array
+    {
+        // 1. Hex 轉 Binary
+        $data = hex2bin($encryptInfo);
+
+        // 2. 分離加密資料和 tag
+        $encrypted = substr($data, 0, -16);
+        $tag = substr($data, -16);
+
+        // 3. AES-256-GCM 解密
+        $decrypted = openssl_decrypt(
+            $encrypted,
+            'aes-256-gcm',
+            $this->merKey,
+            OPENSSL_RAW_DATA,
+            $this->merIV,
+            $tag
+        );
+
+        // 4. 解析 Query String
+        parse_str($decrypted, $result);
+
+        return $result;
+    }
+
+    /**
+     * 產生 HashInfo (SHA256)
+     */
+    public function hashInfo(string $encryptInfo): string
+    {
+        $raw = $encryptInfo . $this->merKey . $this->merIV;
+        return strtoupper(hash('sha256', $raw));
+    }
+}
+```
+
+### Python 加密範例
+
+```python
+"""PayUni AES-256-GCM 加密"""
+
+from Crypto.Cipher import AES
+from urllib.parse import urlencode, parse_qs
+import hashlib
+
+
+class PayuniEncryption:
+    def __init__(self, mer_key: str, mer_iv: str):
+        self.mer_key = mer_key.encode('utf-8')
+        self.mer_iv = mer_iv.encode('utf-8')
+
+    def encrypt(self, params: dict) -> str:
+        """AES-256-GCM 加密"""
+        # 1. 組合 Query String
+        query_string = urlencode(params)
+
+        # 2. AES-256-GCM 加密
+        cipher = AES.new(self.mer_key, AES.MODE_GCM, nonce=self.mer_iv)
+        encrypted, tag = cipher.encrypt_and_digest(query_string.encode('utf-8'))
+
+        # 3. 組合加密結果
+        encrypt_info = (encrypted + tag).hex()
+
+        return encrypt_info
+
+    def decrypt(self, encrypt_info: str) -> dict:
+        """AES-256-GCM 解密"""
+        # 1. Hex 轉 Binary
+        data = bytes.fromhex(encrypt_info)
+
+        # 2. 分離加密資料和 tag
+        encrypted = data[:-16]
+        tag = data[-16:]
+
+        # 3. AES-256-GCM 解密
+        cipher = AES.new(self.mer_key, AES.MODE_GCM, nonce=self.mer_iv)
+        decrypted = cipher.decrypt_and_verify(encrypted, tag)
+
+        # 4. 解析 Query String
+        result = dict(parse_qs(decrypted.decode('utf-8')))
+        return {k: v[0] for k, v in result.items()}
+
+    def hash_info(self, encrypt_info: str) -> str:
+        """產生 HashInfo (SHA256)"""
+        raw = encrypt_info + self.mer_key.decode() + self.mer_iv.decode()
+        return hashlib.sha256(raw.encode('utf-8')).hexdigest().upper()
+```
+
+---
+
+## 通用參數
+
+### 請求參數
+
+所有 API 請求都需要以下參數：
+
+| 參數 | 類型 | 必填 | 說明 |
+|------|------|------|------|
+| `MerID` | String | ● | 商店代號 |
+| `Version` | String | 否 | API 版本，預設 `1.0` (LINE Pay 預設 `1.1`) |
+| `EncryptInfo` | String | ● | AES-256-GCM 加密後的參數 |
+| `HashInfo` | String | ● | SHA256 驗證碼 |
+
+### EncryptInfo 內容參數
+
+以下參數需加密放入 `EncryptInfo`：
+
+| 參數 | 類型 | 長度 | 必填 | 說明 |
+|------|------|------|------|------|
+| `MerID` | String | 20 | ● | 商店代號 |
+| `MerTradeNo` | String | 50 | ● | 商店訂單編號，需唯一 |
+| `TradeAmt` | Integer | - | ● | 交易金額 (整數) |
+| `Timestamp` | Integer | - | ● | Unix 時間戳 |
+| `ProdDesc` | String | 100 | 否 | 商品描述 |
+| `UsrMail` | String | 100 | 否 | 消費者 Email |
+| `ReturnURL` | String | 500 | 否 | 前台返回網址 |
+| `NotifyURL` | String | 500 | 否 | 背景通知網址 |
+| `Lang` | String | 5 | 否 | 語系 `zh-tw` / `en` |
+
+### API 回應格式
+
+```json
+{
+  "Status": "SUCCESS",
+  "Message": "成功",
+  "EncryptInfo": "加密後的回應資料",
+  "HashInfo": "SHA256 驗證碼"
+}
+```
+
+### Status 狀態碼
+
+| 狀態 | 說明 |
+|------|------|
+| `SUCCESS` | 成功 |
+| `ERROR` | 失敗 |
+
+---
+
+## 整合式支付頁 (UPP)
+
+導向 PayUni 整合式支付頁面，消費者可選擇付款方式。
+
+### 端點
+
+```
+POST /api/upp
+```
+
+### EncryptInfo 參數
+
+| 參數 | 類型 | 必填 | 說明 |
+|------|------|------|------|
+| `MerID` | String | ● | 商店代號 |
+| `MerTradeNo` | String | ● | 訂單編號 |
+| `TradeAmt` | Integer | ● | 交易金額 |
+| `Timestamp` | Integer | ● | Unix 時間戳 |
+| `ExpireDate` | Integer | 否 | 繳費期限 (天)，`1`~`180`，預設 `7` |
+| `ProdDesc` | String | 否 | 商品描述 |
+| `UsrMail` | String | 否 | 消費者 Email |
+| `ReturnURL` | String | 否 | 前台返回網址 |
+| `NotifyURL` | String | 否 | 背景通知網址 |
+| `Lang` | String | 否 | 語系 `zh-tw` / `en` |
+
+### 支援的付款方式
+
+整合式支付頁可顯示以下付款方式 (依商店設定)：
+
+- 信用卡 (一次付清、分期、紅利折抵)
+- ATM 虛擬帳號
+- 超商代碼
+- Apple Pay
+- Google Pay
+- Samsung Pay
+- LINE Pay
+- AFTEE 先享後付
+- 愛金卡 iCash
+
+### PHP 範例
+
+```php
+<?php
+
+$encryption = new PayuniEncryption($merKey, $merIV);
+
+$params = [
+    'MerID' => 'YOUR_MER_ID',
+    'MerTradeNo' => 'ORDER' . time(),
+    'TradeAmt' => 1000,
+    'Timestamp' => time(),
+    'ProdDesc' => '測試商品',
+    'ReturnURL' => 'https://your-site.com/return',
+    'NotifyURL' => 'https://your-site.com/notify',
+];
+
+$encryptInfo = $encryption->encrypt($params);
+$hashInfo = $encryption->hashInfo($encryptInfo);
+
+// 產生表單
+$html = <<<HTML
+<form method="post" action="https://api.payuni.com.tw/api/upp">
+    <input type="hidden" name="MerID" value="{$params['MerID']}">
+    <input type="hidden" name="Version" value="1.0">
+    <input type="hidden" name="EncryptInfo" value="{$encryptInfo}">
+    <input type="hidden" name="HashInfo" value="{$hashInfo}">
+    <button type="submit">前往付款</button>
+</form>
+HTML;
+
+echo $html;
+```
+
+---
+
+## 信用卡幕後
+
+直接在商店頁面完成信用卡扣款，不需導向 PayUni。
+
+### 端點
+
+```
+POST /api/credit
+```
+
+### EncryptInfo 參數
+
+| 參數 | 類型 | 必填 | 說明 |
+|------|------|------|------|
+| `MerID` | String | ● | 商店代號 |
+| `MerTradeNo` | String | ● | 訂單編號 |
+| `TradeAmt` | Integer | ● | 交易金額 |
+| `Timestamp` | Integer | ● | Unix 時間戳 |
+| `CardNo` | String | ● | 信用卡號 (16 碼) |
+| `CardExpiry` | String | ● | 有效期限 `MMYY` |
+| `CardCVC` | String | ● | 安全碼 (3 碼) |
+| `ProdDesc` | String | 否 | 商品描述 |
+| `UsrMail` | String | 否 | 消費者 Email |
+| `NotifyURL` | String | 否 | 背景通知網址 |
+
+### 分期付款參數
+
+| 參數 | 類型 | 說明 |
+|------|------|------|
+| `Inst` | Integer | 分期期數 `3`, `6`, `12`, `18`, `24`, `30` |
+
+### 紅利折抵參數
+
+| 參數 | 類型 | 說明 |
+|------|------|------|
+| `Red` | String | 啟用紅利折抵 `Y` |
+
+### 銀聯卡參數
+
+| 參數 | 類型 | 說明 |
+|------|------|------|
+| `UnionPay` | Integer | `1`:使用銀聯 |
+
+### 信用卡約定 (Token) 參數
+
+| 參數 | 類型 | 說明 |
+|------|------|------|
+| `UseTokenType` | Integer | `1`:建立 Token `2`:使用既有 Token |
+| `BindVal` | String | Token 代碼 (UseTokenType=2 時必填) |
+
+---
+
+## ATM 虛擬帳號
+
+取得 ATM 繳費虛擬帳號。
+
+### 端點
+
+```
+POST /api/atm
+```
+
+### EncryptInfo 參數
+
+| 參數 | 類型 | 必填 | 說明 |
+|------|------|------|------|
+| `MerID` | String | ● | 商店代號 |
+| `MerTradeNo` | String | ● | 訂單編號 |
+| `TradeAmt` | Integer | ● | 交易金額 |
+| `Timestamp` | Integer | ● | Unix 時間戳 |
+| `ExpireDate` | Integer | 否 | 繳費期限 (天)，`1`~`60`，預設 `3` |
+| `BankType` | String | 否 | 指定銀行 (參見下表) |
+| `NotifyURL` | String | 否 | 背景通知網址 |
+
+### BankType 銀行代碼
+
+| 代碼 | 銀行 |
+|------|------|
+| `FIRST` | 第一銀行 |
+| `ESUN` | 玉山銀行 |
+| `TAISHIN` | 台新銀行 |
+| `CATHAY` | 國泰世華 |
+| `CHINATRUST` | 中國信託 |
+
+### 回應參數 (解密後)
+
+| 參數 | 說明 |
+|------|------|
+| `TradeNo` | PayUni 交易編號 |
+| `BankCode` | 銀行代碼 (3 碼) |
+| `vAccount` | 虛擬帳號 (14~16 碼) |
+| `ExpireDate` | 繳費期限 `yyyy/MM/dd` |
+
+---
+
+## 超商代碼
+
+取得超商繳費代碼。
+
+### 端點
+
+```
+POST /api/cvs
+```
+
+### EncryptInfo 參數
+
+| 參數 | 類型 | 必填 | 說明 |
+|------|------|------|------|
+| `MerID` | String | ● | 商店代號 |
+| `MerTradeNo` | String | ● | 訂單編號 |
+| `TradeAmt` | Integer | ● | 交易金額 (`30`~`20000`) |
+| `Timestamp` | Integer | ● | Unix 時間戳 |
+| `ExpireDate` | Integer | 否 | 繳費期限 (天)，預設 `7` |
+| `NotifyURL` | String | 否 | 背景通知網址 |
+
+### 金額限制
+
+| 項目 | 限制 |
+|------|------|
+| 最低金額 | 30 元 |
+| 最高金額 | 20,000 元 |
+
+### 回應參數 (解密後)
+
+| 參數 | 說明 |
+|------|------|
+| `TradeNo` | PayUni 交易編號 |
+| `PayNo` | 繳費代碼 |
+| `ExpireDate` | 繳費期限 |
+
+---
+
+## LINE Pay
+
+LINE Pay 支付整合。
+
+### 端點
+
+```
+POST /api/linepay
+```
+
+### 版本
+
+```
+Version: 1.1
+```
+
+### EncryptInfo 參數
+
+| 參數 | 類型 | 必填 | 說明 |
+|------|------|------|------|
+| `MerID` | String | ● | 商店代號 |
+| `MerTradeNo` | String | ● | 訂單編號 |
+| `TradeAmt` | Integer | ● | 交易金額 |
+| `Timestamp` | Integer | ● | Unix 時間戳 |
+| `ProdDesc` | String | ● | 商品描述 |
+| `ReturnURL` | String | ● | 付款完成返回網址 |
+| `NotifyURL` | String | 否 | 背景通知網址 |
+
+### LINE Pay 退款
+
+#### 端點
+
+```
+POST /api/trade_refund_linepay
+```
+
+#### EncryptInfo 參數
+
+| 參數 | 類型 | 必填 | 說明 |
+|------|------|------|------|
+| `MerID` | String | ● | 商店代號 |
+| `TradeNo` | String | ● | PayUni 交易編號 |
+| `TradeAmt` | Integer | ● | 退款金額 |
+| `Timestamp` | Integer | ● | Unix 時間戳 |
+
+---
+
+## AFTEE 先享後付
+
+AFTEE 後支付整合。
+
+### 端點
+
+```
+POST /api/aftee_direct
+```
+
+### EncryptInfo 參數
+
+| 參數 | 類型 | 必填 | 說明 |
+|------|------|------|------|
+| `MerID` | String | ● | 商店代號 |
+| `MerTradeNo` | String | ● | 訂單編號 |
+| `TradeAmt` | Integer | ● | 交易金額 |
+| `Timestamp` | Integer | ● | Unix 時間戳 |
+| `ProdDesc` | String | ● | 商品描述 |
+| `UsrMail` | String | ● | 消費者 Email |
+| `UsrName` | String | ● | 消費者姓名 |
+| `UsrPhone` | String | ● | 消費者手機 |
+| `ReturnURL` | String | ● | 付款完成返回網址 |
+| `NotifyURL` | String | 否 | 背景通知網址 |
+
+### AFTEE 確認交易
+
+當 AFTEE 交易需要確認時：
+
+```
+POST /api/trade_confirm_aftee
+```
+
+### AFTEE 退款
+
+```
+POST /api/trade_refund_aftee
+```
+
+---
+
+## Apple Pay / Google Pay / Samsung Pay
+
+行動支付整合 (需透過整合式支付頁或前端 SDK)。
+
+### 支援說明
+
+| 支付方式 | 說明 |
+|----------|------|
+| Apple Pay | Safari 瀏覽器、iOS/macOS 裝置 |
+| Google Pay | Chrome 瀏覽器、Android 裝置 |
+| Samsung Pay | Samsung 裝置 |
+
+### 使用方式
+
+透過整合式支付頁 (UPP) 使用，商店需向 PayUni 申請開通。
+
+---
+
+## 愛金卡 iCash
+
+愛金卡 (iCash) 支付。
+
+### 退款端點
+
+```
+POST /api/trade_refund_icash
+```
+
+### EncryptInfo 參數
+
+| 參數 | 類型 | 必填 | 說明 |
+|------|------|------|------|
+| `MerID` | String | ● | 商店代號 |
+| `TradeNo` | String | ● | PayUni 交易編號 |
+| `TradeAmt` | Integer | ● | 退款金額 |
+| `Timestamp` | Integer | ● | Unix 時間戳 |
+
+---
+
+## 交易查詢
+
+查詢交易狀態。
+
+### 端點
+
+```
+POST /api/trade_query
+```
+
+### EncryptInfo 參數
+
+| 參數 | 類型 | 必填 | 說明 |
+|------|------|------|------|
+| `MerID` | String | ● | 商店代號 |
+| `MerTradeNo` | String | ● | 商店訂單編號 |
+| `Timestamp` | Integer | ● | Unix 時間戳 |
+
+### 回應參數 (解密後)
+
+| 參數 | 說明 |
+|------|------|
+| `TradeNo` | PayUni 交易編號 |
+| `MerTradeNo` | 商店訂單編號 |
+| `TradeAmt` | 交易金額 |
+| `TradeStatus` | 交易狀態 |
+| `PaymentType` | 付款方式 |
+| `CreateTime` | 訂單建立時間 |
+| `PayTime` | 付款時間 |
+
+### TradeStatus 交易狀態
+
+| 狀態 | 說明 |
+|------|------|
+| `0` | 未付款 / 處理中 |
+| `1` | 已付款 |
+| `2` | 付款失敗 |
+| `3` | 已退款 |
+
+### PHP 範例
+
+```php
+<?php
+
+$encryption = new PayuniEncryption($merKey, $merIV);
+
+$params = [
+    'MerID' => 'YOUR_MER_ID',
+    'MerTradeNo' => 'ORDER1234567890',
+    'Timestamp' => time(),
+];
+
+$encryptInfo = $encryption->encrypt($params);
+$hashInfo = $encryption->hashInfo($encryptInfo);
+
+$response = file_get_contents('https://api.payuni.com.tw/api/trade_query', false, stream_context_create([
+    'http' => [
+        'method' => 'POST',
+        'header' => 'Content-Type: application/x-www-form-urlencoded',
+        'content' => http_build_query([
+            'MerID' => $params['MerID'],
+            'Version' => '1.0',
+            'EncryptInfo' => $encryptInfo,
+            'HashInfo' => $hashInfo,
+        ]),
+    ],
+]));
+
+$result = json_decode($response, true);
+
+if ($result['Status'] === 'SUCCESS') {
+    $data = $encryption->decrypt($result['EncryptInfo']);
+    print_r($data);
+}
+```
+
+---
+
+## 交易請退款
+
+信用卡請款或退款。
+
+### 端點
+
+```
+POST /api/trade_close
+```
+
+### EncryptInfo 參數
+
+| 參數 | 類型 | 必填 | 說明 |
+|------|------|------|------|
+| `MerID` | String | ● | 商店代號 |
+| `TradeNo` | String | ● | PayUni 交易編號 |
+| `CloseType` | Integer | ● | 操作類型 |
+| `CloseAmt` | Integer | 否 | 請退款金額 (部分退款時使用) |
+| `Timestamp` | Integer | ● | Unix 時間戳 |
+
+### CloseType 操作類型
+
+| 代碼 | 說明 |
+|------|------|
+| `1` | 請款 (Capture) |
+| `2` | 退款 (Refund) |
+
+### 退款限制
+
+- 支援部分退款
+- 退款金額需小於等於原交易金額
+- 信用卡退款期限：請款後 1 年內
+
+---
+
+## 交易取消授權
+
+取消信用卡授權 (尚未請款)。
+
+### 端點
+
+```
+POST /api/trade_cancel
+```
+
+### EncryptInfo 參數
+
+| 參數 | 類型 | 必填 | 說明 |
+|------|------|------|------|
+| `MerID` | String | ● | 商店代號 |
+| `TradeNo` | String | ● | PayUni 交易編號 |
+| `Timestamp` | Integer | ● | Unix 時間戳 |
+
+---
+
+## 信用卡約定 (Token)
+
+### 查詢約定信用卡
+
+#### 端點
+
+```
+POST /api/credit_bind_query
+```
+
+#### EncryptInfo 參數
+
+| 參數 | 類型 | 必填 | 說明 |
+|------|------|------|------|
+| `MerID` | String | ● | 商店代號 |
+| `BindVal` | String | ● | Token 代碼 |
+| `Timestamp` | Integer | ● | Unix 時間戳 |
+
+### 取消約定信用卡
+
+#### 端點
+
+```
+POST /api/credit_bind_cancel
+```
+
+#### EncryptInfo 參數
+
+| 參數 | 類型 | 必填 | 說明 |
+|------|------|------|------|
+| `MerID` | String | ● | 商店代號 |
+| `BindVal` | String | ● | Token 代碼 |
+| `Timestamp` | Integer | ● | Unix 時間戳 |
+
+---
+
+## 付款結果通知
+
+### 通知流程
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│   消費者    │────▶│   PayUni    │────▶│    商店     │
+│   付款     │     │    處理     │     │ NotifyURL  │
+└─────────────┘     └─────────────┘     └─────────────┘
+                          │
+                          │ POST (加密資料)
+                          ▼
+                    ┌─────────────┐
+                    │    商店     │
+                    │  解密處理   │
+                    └─────────────┘
+                          │
+                          │ 回應 "SUCCESS"
+                          ▼
+                    ┌─────────────┐
+                    │   PayUni    │
+                    │  確認收到   │
+                    └─────────────┘
+```
+
+### 通知參數
+
+PayUni 會 POST 加密資料到 `NotifyURL`：
+
+| 參數 | 說明 |
+|------|------|
+| `MerID` | 商店代號 |
+| `EncryptInfo` | 加密的交易結果 |
+| `HashInfo` | SHA256 驗證碼 |
+
+### 解密後的通知內容
+
+| 參數 | 說明 |
+|------|------|
+| `MerID` | 商店代號 |
+| `MerTradeNo` | 商店訂單編號 |
+| `TradeNo` | PayUni 交易編號 |
+| `TradeAmt` | 交易金額 |
+| `TradeStatus` | 交易狀態 (`0`:處理中 `1`:成功) |
+| `PaymentType` | 付款方式 |
+| `CreateTime` | 訂單建立時間 |
+| `PayTime` | 付款時間 |
+| `Message` | 交易訊息 |
+| `Card4No` | 信用卡末四碼 (信用卡交易) |
+| `AuthCode` | 銀行授權碼 (信用卡交易) |
+
+### 處理範例
+
+```php
+<?php
+
+// 接收通知
+$encryptInfo = $_POST['EncryptInfo'] ?? '';
+$hashInfo = $_POST['HashInfo'] ?? '';
+$merID = $_POST['MerID'] ?? '';
+
+// 驗證 HashInfo
+$encryption = new PayuniEncryption($merKey, $merIV);
+$calculatedHash = $encryption->hashInfo($encryptInfo);
+
+if ($hashInfo !== $calculatedHash) {
+    echo 'HashInfo Error';
+    exit;
+}
+
+// 解密
+$data = $encryption->decrypt($encryptInfo);
+
+// 檢查交易狀態
+if ($data['TradeStatus'] === '1') {
+    // 交易成功，更新訂單狀態
+    updateOrderStatus($data['MerTradeNo'], 'paid', $data);
+}
+
+// 回應 SUCCESS
+echo 'SUCCESS';
+```
+
+---
+
+## 錯誤碼對照表
+
+### 交易狀態 (TradeStatus)
+
+| 狀態 | 說明 |
+|------|------|
+| `0` | 未付款 / 處理中 |
+| `1` | 已付款 / 成功 |
+| `2` | 付款失敗 |
+| `3` | 已退款 |
+
+### 常見錯誤訊息
+
+| 錯誤碼 | 說明 | 處理方式 |
+|--------|------|----------|
+| `參數錯誤` | 必填參數缺失或格式錯誤 | 檢查參數格式 |
+| `商店代號錯誤` | MerID 不存在 | 確認商店代號 |
+| `訂單編號重複` | MerTradeNo 已使用 | 使用新的訂單編號 |
+| `HashInfo 驗證失敗` | 加密資料不正確 | 重新計算 HashInfo |
+| `交易金額錯誤` | 金額超出範圍 | 確認金額限制 |
+| `卡片授權失敗` | 信用卡交易被拒 | 請客戶聯繫發卡銀行 |
+| `餘額不足` | 信用卡額度不足 | 請客戶確認額度 |
+| `卡片過期` | 信用卡已過期 | 請客戶使用有效卡片 |
+
+---
+
+## 常見問題排解
+
+### HashInfo 驗證失敗
+
+**問題**: 收到 `HashInfo 驗證失敗`
+
+**檢查項目**:
+1. Hash Key 和 Hash IV 是否正確
+2. AES-256-GCM 加密是否正確實作
+3. SHA256 計算是否正確
+4. 測試/正式環境金鑰是否混用
+
+### 訂單編號重複
+
+**問題**: 收到 `訂單編號重複`
+
+**解決**:
+```python
+import time
+import random
+order_id = f"ORD{int(time.time())}{random.randint(100, 999)}"
+```
+
+### 付款通知未收到
+
+**問題**: 付款成功但沒收到 NotifyURL 通知
+
+**檢查項目**:
+1. NotifyURL 是否為 HTTPS
+2. 伺服器是否能被外網存取
+3. 是否正確回應 `SUCCESS`
+4. 防火牆是否阻擋 PayUni IP
+
+### 加密/解密問題
+
+**問題**: 加密資料無法解密
+
+**檢查項目**:
+1. AES-256-GCM 參數是否正確 (Key 32 bytes, IV 16 bytes)
+2. Tag 長度是否為 16 bytes
+3. Hex 編碼/解碼是否正確
+
+---
+
+## SDK 資源
+
+### 官方 SDK
+
+| 語言 | GitHub |
+|------|--------|
+| PHP | https://github.com/payuni/PHP_SDK |
+| .NET | https://github.com/payuni/NET_SDK |
+
+### 安裝方式
+
+#### PHP (Composer)
+
+```bash
+composer require payuni/sdk
+```
+
+#### .NET (NuGet)
+
+需要安裝以下套件：
+- Newtonsoft.Json (13.0.1+)
+- Portable.BouncyCastle (1.9.0+)
+
+---
+
+## 官方資源
+
+- **官方網站**: https://www.payuni.com.tw/
+- **API 文件**: https://www.payuni.com.tw/docs/web/
+- **GitHub**: https://github.com/payuni
+- **WooCommerce 外掛**: https://github.com/payuni/PAYUNi_for_WooCommerce