Agent skill

payuni-query

Implements PAYUNi transaction query functionality using Query API. Use when building order status checking, transaction verification, or payment confirmation features for 統一金流.

Stars 236
Forks 18

Install this agent skill to your Project

npx add-skill https://github.com/paid-tw/skills/tree/main/plugins/payuni/skills/payuni-query

SKILL.md

統一金流交易查詢任務

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

Step 1: 確認需求

用戶輸入: $ARGUMENTS

詢問用戶:

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

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

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

Step 2: 建立查詢功能

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

核心功能:

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

Step 3: 實作程式碼

Node.js/TypeScript 範例

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

請求參數

參數 類型 必填 說明
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 正確

Expand your agent's capabilities with these related and highly-rated skills.

paid-tw/skills

kryptogo-pay-webhook

Implements KryptoGO Payment webhook/callback handling for receiving payment status notifications. Use when building webhook endpoints, handling payment callbacks, or implementing 支付狀態通知 for KryptoGO Payment.

236 18
Explore
paid-tw/skills

kryptogo-pay

Provides KryptoGO Payment integration overview and guides users to the appropriate skill. Use when starting KryptoGO crypto payment integration, setting up environment, or needing general guidance about KryptoGO 穩定幣支付.

236 18
Explore
paid-tw/skills

kryptogo-pay-query

Implements KryptoGO Payment query functionality for checking payment intent status and listing payment intents. Use when building order status checking, transaction verification, or payment confirmation features for KryptoGO 穩定幣支付.

236 18
Explore
paid-tw/skills

kryptogo-pay-transfer

Implements KryptoGO Payment token transfer/withdrawal functionality using the Asset Pro Transfer API. Use when building withdrawal features, sending tokens to users, or implementing 穩定幣提領轉帳 for KryptoGO Payment.

236 18
Explore
paid-tw/skills

kryptogo-pay-checkout

Implements KryptoGO Payment checkout integration including Payment Intent creation, React SDK usePayment hook, and Direct API integration. Use when integrating crypto payment, creating checkout flows, or building KryptoGO 穩定幣收款頁面.

236 18
Explore
paid-tw/skills

payuni-webhook

Implements PAYUNi webhook handling including signature verification, replay attack prevention, and payment status updates. Use when building payment notification endpoints for 統一金流.

236 18
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results