OpenParable
Skip to content
← Back to skills

Payuni Query

Apps & Automation
payuni-query

Payuni Query 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 transaction query functionality using Query API. Use when building order status checking, transaction verification, or payment confirmation features for 統一金流.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/paid-tw/skills/blob/HEAD/plugins/payuni/skills/payuni-query/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/payuni-query, 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.

統一金流交易查詢任務

你的任務是在用戶的專案中實作統一金流交易查詢功能。

Step 1: 確認需求

用戶輸入: $ARGUMENTS

詢問用戶:

  1. 查詢情境:需要什麼查詢功能?

    • 單筆訂單查詢(客戶查詢、客服查詢)
    • 批次對帳(每日/定時對帳)
    • 支付狀態確認(NotifyURL 備援)
  2. 專案框架:你使用什麼框架?

    • 確認是否已有 PAYUNi 環境設定

Step 2: 建立查詢功能

在現有的支付模組中加入查詢方法,或建立新模組。

核心功能:

  1. generateQueryParams(orderNo) - 產生查詢參數
  2. queryTrade(orderNo) - 查詢單筆交易

Step 3: 實作程式碼

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',
};

function getQueryEndpoint(): string {
  return config.isTest
    ? 'https://sandbox-api.payuni.com.tw/api/query'
    : 'https://api.payuni.com.tw/api/query';
}

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;
}

function generateHashInfo(encryptInfo: string): string {
  return crypto
    .createHash('sha256')
    .update(encryptInfo)
    .digest('hex')
    .toUpperCase();
}

async function queryTrade(orderNo: string): Promise<{
  success: boolean;
  data?: any;
  error?: string;
}> {
  try {
    const queryData = {
      MerID: config.merchantId,
      MerTradeNo: orderNo,
    };
    
    const queryString = new URLSearchParams(queryData).toString();
    const encryptInfo = encrypt(queryString);
    const hashInfo = generateHashInfo(encryptInfo);
    
    const response = await fetch(getQueryEndpoint(), {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: new URLSearchParams({
        MerID: config.merchantId,
        EncryptInfo: encryptInfo,
        HashInfo: hashInfo,
      }),
    });
    
    const result = await response.json();
    
    return {
      success: result.Status === 'SUCCESS',
      data: result,
    };
  } catch (error) {
    return {
      success: false,
      error: error instanceof Error ? error.message : 'Query failed',
    };
  }
}

// 使用範例
const result = await queryTrade('ORDER-123');
if (result.success) {
  console.log('交易狀態:', result.data.TradeStatus);
}

Step 4: 整合到應用

建議整合方式:

  • API 端點: GET /api/orders/:orderNo/status
  • 管理後台: 訂單詳情頁顯示即時狀態
  • 定時任務: 對帳排程

API 參考

端點

環境URL
測試https://sandbox-api.payuni.com.tw/api/query
正式https://api.payuni.com.tw/api/query

請求參數

參數類型必填說明
MerIDString✓商店代號
EncryptInfoString✓加密後的查詢參數
HashInfoString✓SHA256 雜湊值

EncryptInfo 內容

參數類型必填說明
MerIDString✓商店代號
MerTradeNoString✓商店訂單編號

交易狀態 (TradeStatus)

值說明
0未付款
1已付款
2付款失敗
3已取消
6已退款

詳細參考文件


常見錯誤

代碼說明解決方式
TRA10001查無此筆交易確認訂單編號正確
TRA10002驗證錯誤確認加密參數正確
TRA10003商店代號錯誤確認 MerchantID 正確