payuni-uni-embed-v3

name: payuni-uni-embed-v3 description: > PAYUNi UNi Embed (免跳轉支付元件 / 內嵌式金流) API Ver 3.0 + JS SDK Ver 2.0 完整技術參考。 iframe 嵌入式信用卡收單，站內付不跳轉，後端 token_get 取 SDK_TOKEN，前端 uniPayment.js 收集卡片資訊取得綁定結果，後端再呼叫 merchant_trade 完成幕後授權。 當程式碼涉及 PAYUNi、統一金流、payuni-uni、UNi Embed、內嵌金流、站內付、tokenization、 iframe 信用卡收單、SDK 整合、uni-payment.js、createSession、getTradeResult、 iframe/token_get、iframe/merchant_trade、IFrameDomain、SDK_TOKEN 時使用。 與 payuni-upp-v3（導轉式整合支付頁）平行；加密規則（AES-256-GCM + SHA256 HashInfo） 與 UPP 完全一致，請參考 payuni-upp-v3 該段。本 SKILL 為 V3 (2025/09 釋出)， 若程式碼出現 V2 或 V1 路徑，請勿混用——V3 token_get 階段不送訂單資料。

PAYUNi UNi Embed V3

版本: API Ver 3.0 / JS SDK Ver 2.0 | 支付工具: 信用卡（含 Visa/MasterCard/JCB/銀聯）| 來源: https://docs.payuni.com.tw/web/#/29/383 | 更新: 2026-05-04

PAYUNi 免跳轉支付元件——商店頁面以 iframe 內嵌支付欄位（信用卡號、有效期限、CVC），消費者不離開商店網站完成付款。後端先呼叫 token_get 取 SDK_TOKEN（10 分鐘有效），前端用 SDK 蒐集卡片並取得綁定 TOKEN 結果，後端再以原 SDK_TOKEN 呼叫 merchant_trade 進行幕後授權。

目前僅支援信用卡（一次付清、分期、約定信用卡、強制約定、記憶卡號）。ATM/CVS/LINE Pay/街口/Apple Pay 等請改用 UPP（導轉式）— 見 payuni-upp-v3。

與 UPP 的關鍵差異

加密實作完全相同——本 SKILL 不重複；請直接讀 payuni-upp-v3/SKILL.md 的「加解密」段或本專案 apps/api-gateway/src/commerce/payments/payuni/payuni-crypto.ts。

V3 vs V2 vs V1 版本差異

⚠️ V3 的核心改變：token_get 階段只在驗證 IFrameDomain，不綁訂單；訂單金額與 MerTradeNo 在後續 merchant_trade 才送，前端不再經手敏感金額/訂單編號。商店端可在 SDK 綁卡完成後重新檢視購物車金額（避免使用者在 SDK 等候期間竄改）。

串接前置作業

1. 註冊 PAYUNi 平台會員並建立收款商店，取得 MerID
   • 測試: https://sandbox.payuni.com.tw
   • 正式: https://www.payuni.com.tw
2. 聯繫 PAYUNi 客服提出免跳轉元件申請，並設定限定後端來源 IP（必要）
3. 自後台「商店清單 > 串接設定」取得 HashKey（32 字元）、HashIV（16 字元）
4. 代理商：另需簽訂代理商合作契約，於「代理商專區 > 合約及基本資料」取得代理商金鑰，串接時於外層額外帶入 IsPlatForm=1

端點

上述「固定」皆為官方文件原文措辭（token_get 頁、merchant_trade 頁）。 注意 merchant_trade 請求送 1.0、回傳 1.2，是 PAYUNi 設計，不是 bug。

SDK CDN（前端）：

CSP 必須允許：

script-src https://vendor.payuni.com.tw;
frame-src  https://vendor.payuni.com.tw https://sandbox-vendor.payuni.com.tw;

TLS v1.2+；User-Agent 官方原文「建議內容為 payuni」（非強制；若不帶仍可送單，但 PAYUNi 端 log 識別會比較難）。

完整流程

3D 交易（強制 / 由銀行決定）

[商店頁面] ─POST─> [後端] ─POST iframe/token_get─> [PAYUNi] ─SDK_TOKEN─> [後端] ─SDK_TOKEN─> [前端]
[前端] uniPayment.createSession(SDK_TOKEN) → start() → onUpdate（卡號驗證）→ getTradeResult()
[前端] ─綁定 TOKEN 結果─> [後端] ─POST iframe/merchant_trade (帶原 SDK_TOKEN + 訂單)─> [PAYUNi]
[PAYUNi] 回傳 3D 導頁 URL → 商店導向 3D 頁面 → 銀行驗證 → NotifyURL（Form POST）回打
[商店] 在 NotifyURL 收到並驗證 HashInfo → 解密 EncryptInfo → 寫入訂單狀態

非 3D 交易

[同上至 merchant_trade]
[PAYUNi] 直接回 Status=SUCCESS + 加密的授權結果（同步回應，無 3D 跳轉）
[ReturnURL] 若有設定，PAYUNi 也會 Form POST 同樣結果（前景）

交易結果以 NotifyURL 為準——ReturnURL 可能因使用者關掉瀏覽器而漏收。

API 1：取得 SDK_TOKEN — /api/iframe/token_get

外層（HTTP Body, application/x-www-form-urlencoded）

EncryptInfo 內層

基本參數（一律必填）：

⚠️ 注意 V3 比 V2 少了 MerTradeNo、TradeAmt、ReturnURL、NotifyURL、ProdDesc 等所有訂單欄位——這些在 merchant_trade 階段才送。

首次信用卡 Token 交易參數（記憶卡號 / 約定 / 強制約定）：

回傳

外層 JSON（官方明文「Version 固定 3.0」——回傳值與請求值相同）：

{
  "Status": "SUCCESS",
  "MerID": "...",
  "Version": "3.0",
  "EncryptInfo": "...(hex)...",
  "HashInfo": "...(SHA256)..."
}

EncryptInfo 解密後：

外層 Status=ERROR 時無 EncryptInfo。

API 2：幕後授權交易 — /api/iframe/merchant_trade

在前端 getTradeResult() 回傳成功（拿到綁定 TOKEN 結果）後，後端用原 SDK_TOKEN 呼叫此 API 進行授權。

外層

EncryptInfo 內層

回傳（非 3D 直接授權成功）

外層 JSON 結構同 token_get（5 欄：Status / MerID / Version / EncryptInfo / HashInfo）。 注意：merchant_trade 回傳的 Version 官方原文為「固定 1.2」——與請求送出的 1.0 不同（也與 token_get 的 3.0 不同）。 這是 PAYUNi 設計，不論是否帶發票/載具參數，回傳 Version 一律 1.2，無條件分支。

EncryptInfo 解密後：

回傳（API3D=1，強制 3D）

NotifyURL 回打格式（3D 完成後）

PAYUNi 以 Form POST 將授權結果送至 NotifyURL，欄位與「非 3D 直接授權成功」回傳完全一致（外層 + EncryptInfo 內層）。商店必須：

1. 驗證外層 HashInfo = SHA256(HashKey + EncryptInfo + HashIV).toUpperCase()
2. 解密 EncryptInfo
3. 比對 MerTradeNo 與本地訂單
4. 比對 TradeAmt 與本地訂單金額（防止竄改）
5. 依 Status / TradeStatus 更新訂單

NotifyURL 必須回應 200 OK；PAYUNi 不會用 retry，逾時建議 30 分鐘後主動以 /api/trade/query 查詢一次（與 UPP 共用，請參考 payuni-upp-v3）。

SDK 整合（前端核心）

Next.js / React 完整實作見 references/frontend-example.md。本段為純 SDK API 參考。

引入 SDK（禁止下載託管）

<script src="https://vendor.payuni.com.tw/sdk/uni-payment.js"></script>

HTML 容器（必要 IDs）

<div id="put_card_no"></div>        <!-- 卡號 iframe 容器 -->
<div id="put_card_exp"></div>       <!-- 到期日 iframe 容器 -->
<div id="put_card_cvc"></div>       <!-- CVC iframe 容器 -->
<!-- 約定 / 記憶卡號時才需要： -->
<div id="put_token_type"></div>     <!-- checkbox 容器 -->

createSession options

const sdk = UniPayment.createSession(SDK_TOKEN, {
  env: "P",          // 必填：P=正式 / S=測試
  useInst: false,    // 啟用分期才設 true
  elements: {        // 必填：與 HTML id 對應
    CardNo: "put_card_no",
    CardExp: "put_card_exp",
    CardCvc: "put_card_cvc",
    CardTokenType: "put_token_type",  // 僅約定/記憶卡號需要
  },
  style: {           // 選填：input 預設樣式
    color: "#000000",
    errorColor: "#FF0000",
    fontSize: "14px",
    fontWeight: "400",
    lineHeight: "24px",
  },
});

onUpdate 事件

sdk.onUpdate((update) => {
  const { status, event, data } = update;
  // status = { CardNo, CardExp, CardCvc }，每個欄位值為下表
  if (event === "useTokenType") { /* 顯示 checkbox + tokenTypeText */ }
});

update.status.{CardNo|CardExp|CardCvc} 值：

update.event === "useTokenType" 時 update.data：

來源驗證機制

iframe 自動比對 window.location.origin 與 token_get 階段傳入的 IFrameDomain：

• 不一致 → 拋 Code 1007，元件不載入
• 取不到 origin（Safari 私密瀏覽等） → 不中斷流程，僅在卡號框下方顯示警語

getTradeResult(config) 參數

await sdk.getTradeResult({ cardInst: 3, useDefault: true });

⚠️ V3 vs V2 行為差異（極易混淆，務必注意）

• 官方 API 表格描述 getTradeResult = 「進行交易並取得加密的交易結果」，這個措辭沿用自 V2。
• 但根據官方版本差異頁原文（https://docs.payuni.com.tw/web/#/29/384）：
  • V3：「SDK 僅負責蒐集信用卡資訊並進行 SDK Token 綁定。商戶前端取得綁定結果後，需自行呼叫另一支 API 進行交易授權，並在取得交易結果後自行核對訂單金額及資訊」
  • V2：「SDK 蒐集完信用卡資訊後，系統會直接執行交易授權」
• V3 的 getTradeResult 實際語義是「取得卡號綁定 TOKEN 結果」，不執行授權。
• 官方 V3 主文件範例的程式碼註解也明確寫：「取得信用卡號綁定 TOKEN 結果」+「取得成功後再將原始的 TOKEN 進行幕後交易授權」+ catch 註解「信用卡號綁定 TOKEN 失敗」。
• 後續授權必須由後端再呼叫 merchant_trade（同一個 SDK_TOKEN）。
• 所以：若你看到舊文件 / 第三方教學寫「getTradeResult 完成就有授權結果」——那是 V2 的行為，V3 不適用。

自訂 focus 樣式

input 處於 focus 時 SDK 自動加上 form-input-focus class，可自訂 CSS：

.form-input-focus { box-shadow: 0 0 4px 0.1rem #0485ff73; }

SDK API 完整索引

UniPayment.createSession(token, initOption)

回傳：SDK 實例。

SDK 實例方法

信用卡 Token（記憶卡號 / 約定信用卡）

三種模式

CreditToken（付款人識別）

CreditTokenType（紀錄範圍）

後續幕後扣款（續期）

首次交易完成後，回傳會帶 CreditHash（Token Hash）+ CreditLife（有效日期 MMYY）。

後續扣款使用 PAYUNi UPP 體系的「續期收款 API」（/api/credit mode）——與 UPP 共用，詳見 payuni-upp-v3/references/api-reference.md 的「續期收款 API」段。UNi Embed 本身不負責續期扣款，僅負責首次綁卡。

訂單金額限制（信用卡）

ATM/CVS/LINE Pay 等其他工具上限見 payuni-upp-v3 內 references/api-reference.md，本 SKILL 不適用。

信用卡支援卡別與分期

各銀行支援期數見 https://www.payuni.com.tw/bank-info-inst

Sandbox 測試資源

測試卡號

⚠️ PAYUNi sandbox 只接受上表卡號——別把其他金流的測試卡塞進來。 常見踩坑：用了 NewebPay 的 4000-2211-1111-1111 → PAYUNi 直接授權失敗。 ECPay 測試卡見 ECPay-API-Skill、NewebPay 見 newebpay-mpg。

Sandbox 端點

詳細 sandbox 後台驗證流程（playwright-cli 自動登入查訂單）請見 payuni-upp-v3/SKILL.md「後台驗證訂單」段——同一帳號通用。

注意事項

1. 加密規則 100% 同 UPP：AES-256-GCM、SHA256 HashInfo、hex(base64(cipher) + ":::" + base64(tag))，不重複定義；本專案實作見 apps/api-gateway/src/commerce/payments/payuni/payuni-crypto.ts。
2. V3 token_get 不要送 MerTradeNo / TradeAmt / NotifyURL — 這是 V3 與 V2 最容易踩雷的差異；送了會被忽略或回 TOKEN02xxx 錯誤。
3. 同一個 SDK_TOKEN 走完全程：token_get → 前端 getTradeResult → 後端 merchant_trade 都用同一個 SDK_TOKEN。10 分鐘逾期 → IFTRADE04001。
4. MerTradeNo 在 merchant_trade 才送，10 分鐘內不可重複。
5. NotifyURL 僅 80/443 port，否則 PAYUNi 不送回呼。
6. CSP 必須允許 https://vendor.payuni.com.tw（script-src + frame-src）；測試環境若同時啟用 sandbox-vendor.payuni.com.tw。
7. 禁止下載 uni-payment.js 至商店主機託管 — PAYUNi 安全規範要求始終由 vendor.payuni.com.tw 載入。
8. IFrameDomain 必含 https://，僅允許中文 / a-z / 0-9 / -，不可開頭結尾為 -。
9. 限定 IP 必須事先設定，否則 token_get 回 TOKEN03005 / TOKEN03006。
10. 3D 交易結果以 NotifyURL 為準，ReturnURL 可能漏收。
11. UNKNOWN 狀態：60 秒無銀行回應，後續以 NotifyURL 通知；建議 15 分鐘後以 /api/trade/query（同 UPP）查詢確認。
12. 訂單金額在 merchant_trade 時必須與商店本地金額一致——前端 SDK 回傳後務必後端比對，避免 SDK 等候期間竄改。
13. 代理商串接 需在外層額外帶 IsPlatForm=1，與 MerID/Version/EncryptInfo/HashInfo 同層（不在 EncryptInfo 內）。
14. User-Agent header 官方原文「建議內容為 payuni」——非強制；不帶仍可送單，但 PAYUNi 端 log 識別會比較難。
15. 回傳 Version 欄位語意（容易誤抄）：
    • token_get 請求送 3.0、回傳也固定 3.0
    • merchant_trade 請求送 1.0、回傳固定 1.2（不論是否帶發票，回傳一律 1.2，無條件分支）
16. getTradeResult 在 V3 是「綁定」不是「授權」——詳見「SDK 整合 / getTradeResult(config) 參數」段的 V3 vs V2 差異說明。

與本專案的整合

官方資源