Payuni Checkout
Apps & Automationpayuni-checkoutPayuni Checkout is an Agent Skill for apps & automation published in the paid-tw/skills repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Implements PAYUNi UPP checkout integration including AES256 encryption, form submission, and payment callback handling. Use when integrating payment gateway, creating checkout flows, or building 統一金流 payment pages.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/paid-tw/skills/blob/HEAD/plugins/payuni/skills/payuni-checkout/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/payuni-checkout, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
統一金流 UPP 支付串接任務
你的任務是在用戶的專案中實作統一金流 UPP 幕前支付功能。
串接 Checklist
完成以下步驟即可完成串接:
- 環境確認 - 確認框架類型與支付方式需求
- 環境變數 - 設定 PAYUNI_MERCHANT_ID、HASH_KEY、HASH_IV
- 支付模組 - 建立加密解密與訂單建立功能
- 支付表單 - 建立送出至統一金流的 HTML 表單
- 回調處理 - 建立 NotifyURL 與 ReturnURL 端點
- 測試驗證 - 使用測試環境驗證
Step 1: 確認專案環境
詢問用戶:
-
框架類型:你使用什麼框架?
- PHP (Laravel / CodeIgniter / 原生)
- Node.js (Express / Next.js / NestJS)
- Python (Django / Flask / FastAPI)
- 其他
-
支付方式:需要支援哪些支付方式?(可複選)
- 信用卡
- LINE Pay
- Apple Pay / Google Pay
- ATM 轉帳
- 超商代碼/條碼
用戶輸入: $ARGUMENTS
Step 2: 檢查環境變數
搜尋專案中的 .env 或設定檔,確認是否已設定:
PAYUNI_MERCHANT_IDPAYUNI_HASH_KEYPAYUNI_HASH_IV
若未設定,引導用戶設定環境變數。
Step 3: 建立支付模組
根據用戶框架建立支付模組檔案。
建立位置建議:
- Laravel:
app/Services/PayuniService.php - Express:
services/payuni.js或services/payuni.ts - Next.js:
lib/payuni.ts - Django:
payments/services.py
核心功能:
encrypt(data)- AES-256-CBC 加密decrypt(data)- AES-256-CBC 解密generateHashInfo(encryptInfo)- SHA256 雜湊createOrder(orderData)- 建立訂單並回傳表單資料verifyCallback(payload)- 驗證回調通知
Node.js/TypeScript 範例
import crypto from 'crypto';
const config = {
merchantId: process.env.PAYUNI_MERCHANT_ID!,
hashKey: process.env.PAYUNI_HASH_KEY!,
hashIV: process.env.PAYUNI_HASH_IV!,
isTest: process.env.PAYUNI_TEST_MODE === 'true',
};
// AES-256-CBC 加密
function encrypt(data: string): string {
const key = Buffer.from(config.hashKey.padEnd(32, '\0').slice(0, 32), 'utf8');
const iv = Buffer.from(config.hashIV.padEnd(16, '\0').slice(0, 16), 'utf8');
const cipher = crypto.createCipheriv('aes-256-cbc', key, iv);
let encrypted = cipher.update(data, 'utf8', 'hex');
encrypted += cipher.final('hex');
return encrypted;
}
// SHA256 雜湊
function generateHashInfo(encryptInfo: string): string {
return crypto
.createHash('sha256')
.update(encryptInfo)
.digest('hex')
.toUpperCase();
}
// 建立訂單
function createOrder(params: {
orderId: string;
amount: number;
productName: string;
returnUrl: string;
notifyUrl: string;
}) {
const tradeInfo = {
MerID: config.merchantId,
MerTradeNo: params.orderId,
TradeAmt: params.amount,
ProdDesc: params.productName,
ReturnURL: params.returnUrl,
NotifyURL: params.notifyUrl,
};
const queryString = new URLSearchParams(tradeInfo as any).toString();
const encryptInfo = encrypt(queryString);
const hashInfo = generateHashInfo(encryptInfo);
return {
MerID: config.merchantId,
EncryptInfo: encryptInfo,
HashInfo: hashInfo,
};
}
Step 4: 建立支付表單頁面
根據框架建立支付表單,需包含:
<form method="post" action="https://sandbox-api.payuni.com.tw/api/upp">
<input type="hidden" name="MerID" value="{商店代號}">
<input type="hidden" name="EncryptInfo" value="{加密資料}">
<input type="hidden" name="HashInfo" value="{SHA256雜湊}">
<button type="submit">前往付款</button>
</form>
注意: 正式環境請改為 https://api.payuni.com.tw/api/upp
Step 5: 建立回調處理
建立兩個端點:
-
NotifyURL (背景通知):
POST /api/webhooks/payuni- 接收統一金流背景通知
- 驗證簽名 (CheckCode)
- 更新訂單狀態
- 回應
{ success: true }
-
ReturnURL (前台返回):
GET /checkout/result- 用戶支付完成後導向
- 顯示交易結果
簽名驗證邏輯
function verifyCheckCode(params: Record<string, string>): boolean {
const { CheckCode, ...otherParams } = params;
const sortedKeys = Object.keys(otherParams).sort();
const paramStr = sortedKeys.map(k => `${k}=${otherParams[k]}`).join('&');
const signStr = `HashKey=${config.hashKey}&${paramStr}&HashIV=${config.hashIV}`;
const calculated = crypto
.createHash('sha256')
.update(signStr)
.digest('hex')
.toUpperCase();
return calculated === CheckCode;
}
Step 6: 測試驗證
引導用戶進行測試:
- 使用測試環境
https://sandbox-api.payuni.com.tw - 驗證加密解密正確性
- 確認回調可正常接收
- 測試不同支付方式
API 參考
端點
| 環境 | URL |
|---|---|
| 測試 | https://sandbox-api.payuni.com.tw/api/upp |
| 正式 | https://api.payuni.com.tw/api/upp |
TradeInfo 必要參數
| 參數 | 類型 | 說明 |
|---|---|---|
| MerID | String | 商店代號 |
| MerTradeNo | String(30) | 訂單編號(不可重複) |
| TradeAmt | Number | 金額 |
| ProdDesc | String | 商品描述 |
| ReturnURL | String | 前台返回網址 |
| NotifyURL | String | 背景通知網址 |
支付方式參數
| 參數 | 值 | 說明 |
|---|---|---|
| CREDIT | 1 | 信用卡 |
| LINEPAY | 1 | LINE Pay |
| APPLEPAY | 1 | Apple Pay |
| GOOGLEPAY | 1 | Google Pay |
| VACC | 1 | ATM 轉帳 |
| CVS | 1 | 超商代碼 |
| BARCODE | 1 | 超商條碼 |