payuni-query

name	payuni-query
description	Implements PAYUNi transaction query functionality using Query API. Use when building order status checking, transaction verification, or payment confirmation features for 統一金流.
argument-hint	[查詢情境: 單筆查詢/批次對帳/狀態確認]
context	fork
agent	general-purpose
disable-model-invocation	true
allowed-tools	["Read","Write","Edit","Bash","Grep","Glob"]
user-invocable	true

統一金流交易查詢任務

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

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');
  
   cipher = crypto.(, key, iv);
   encrypted = cipher.(data, , );
  encrypted += cipher.();
   encrypted;
}

 ():  {
   crypto
    .()
    .(encryptInfo)
    .()
    .();
}

  (): <{
  : ;
  ?: ;
  ?: ;
}> {
   {
     queryData = {
      : config.,
      : orderNo,
    };
    
     queryString =  (queryData).();
     encryptInfo = (queryString);
     hashInfo = (encryptInfo);
    
     response =  ((), {
      : ,
      : { :  },
      :  ({
        : config.,
        : encryptInfo,
        : hashInfo,
      }),
    });
    
     result =  response.();
    
     {
      : result. === ,
      : result,
    };
  }  (error) {
     {
      : ,
      : error   ? error. : ,
    };
  }
}


 result =  ();
 (result.) {
  .(, result..);
}

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

請求參數

參數	類型	必填	說明
MerID	String	✓	商店代號
EncryptInfo	String	✓	加密後的查詢參數
HashInfo	String	✓	SHA256 雜湊值

EncryptInfo 內容

參數	類型	必填	說明
MerID	String	✓	商店代號
MerTradeNo	String	✓	商店訂單編號

交易狀態 (TradeStatus)

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

---

詳細參考文件

• 程式碼範例 (PHP/Node.js)

---

常見錯誤

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