Postman — 託管支付

請替換示例憑證

在預請求腳本中替換所有佔位符：

• 'your-api-key' → 商戶後台的實際 API Key
• 'your-api-secret' → 商戶後台的實際 API Secret
• URL 中的 1000 → 您的實際商戶號

Postman 如何計算簽名

Postman 內置的 CryptoJS 庫處理所有加密運算。以下預請求腳本會在每次請求前自動計算簽名並設置所需請求頭。

POST 簽名： Base64(HMAC-SHA256(timestamp\nPOST\npath\nBase64(SHA256(body)), apiSecret))

GET 簽名（無查詢字符串）： Base64(HMAC-SHA256(timestamp\nGET\npath, apiSecret))

GET 簽名（有查詢字符串）： Base64(HMAC-SHA256(timestamp\nGET\npath\nBase64(SHA256(queryString)), apiSecret))

---

創建訂單

1. 配置請求

方法： POSTURL： https://api.paystablecoin.global/api/v1/merchants/1000/orders

將 1000 替換為您的商戶號。

2. 設置請求體

在 Postman 中，點擊 Body → 選擇 raw → 選擇 JSON，粘貼以下內容：

{
  "merchantOrderId": "ORDER_{{$timestamp}}",
  "orderAmount": {
    "value": "99.99",
    "currency": "USD"
  },
  "expiresAt": "2026-12-31T23:59:59Z",
  "returnUrl": "https://yoursite.com/payment/success",
  "callbackUrl": "https://yoursite.com/webhook/payment"
}

TIP

是 Postman 內置變量，會自動插入當前 Unix 時間戳，確保每次發送的 merchantOrderId 唯一。

3. 添加預請求腳本

進入 Pre-request Script 標籤頁，粘貼以下腳本：

// ── 配置 ────────────────────────────────────────────────────────────
const apiKey    = 'your-api-key';
const secretKey = 'your-api-secret';

// ── 時間戳 ──────────────────────────────────────────────────────────
const timestamp = Date.now().toString();

// ── 請求詳情 ────────────────────────────────────────────────────────
const method = pm.request.method;                 // "POST"
const urlObj = new URL(pm.request.url.toString());
const path   = urlObj.pathname;

// ── 請求體：替換 Postman 變量並壓縮 ────────────────────────────────
let body = pm.request.body.raw;
body = body.replace(/\{\{\$timestamp\}\}/g, timestamp);
body = JSON.stringify(JSON.parse(body));          // 壓縮
pm.request.body.raw = body;                       // 更新實際請求體

// ── 請求體哈希：SHA256 → Base64 ─────────────────────────────────────
const bodyHash = CryptoJS.SHA256(body).toString(CryptoJS.enc.Base64);

// ── 構建簽名字符串 ──────────────────────────────────────────────────
const stringToSign = [timestamp, method, path, bodyHash].join('\n');

console.log('=== 託管支付 — 創建訂單 ===');
console.log('Timestamp:', timestamp);
console.log('Method:', method);
console.log('Path:', path);
console.log('Body Hash (Base64):', bodyHash);
console.log('String to Sign:', stringToSign.replace(/\n/g, ' | '));

// ── HMAC-SHA256 → Base64 ────────────────────────────────────────────
const signature = CryptoJS.enc.Base64.stringify(
    CryptoJS.HmacSHA256(stringToSign, secretKey)
);
console.log('Signature:', signature);

// ── 設置請求頭 ──────────────────────────────────────────────────────
pm.request.headers.upsert({ key: 'Content-Type', value: 'application/json' });
pm.request.headers.upsert({ key: 'X-Api-Key',    value: apiKey });
pm.request.headers.upsert({ key: 'X-Timestamp',  value: timestamp });
pm.request.headers.upsert({ key: 'X-Signature',  value: signature });

4. 發送並驗證

點擊 Send，成功響應如下：

{
  "code": "00000",
  "message": "Success",
  "data": {
    "orderId": "ord_8fcb2a2e5b",
    "merchantOrderId": "ORDER_1738112345000",
    "status": "INIT",
    "checkoutUrl": "https://checkout.paystablecoin.global/ord_8fcb2a2e5b"
  }
}

將客戶重定向至 checkoutUrl 完成支付。

---

查詢訂單

1. 配置請求

方法： GETURL： https://api.paystablecoin.global/api/v1/merchants/1000/orders/ORDER_1738112345000

將 1000 替換為商戶號，ORDER_1738112345000 替換為要查詢的訂單號。

2. 無需請求體

Body 標籤頁留空或選擇 none。

3. 添加預請求腳本

// ── 配置 ────────────────────────────────────────────────────────────
const apiKey    = 'your-api-key';
const secretKey = 'your-api-secret';

// ── 時間戳 ──────────────────────────────────────────────────────────
const timestamp = Date.now().toString();

// ── 請求詳情 ────────────────────────────────────────────────────────
const method = pm.request.method;                 // "GET"
const urlObj = new URL(pm.request.url.toString());
const path   = urlObj.pathname;

// ── 構建簽名字符串（無請求體，無查詢字符串）────────────────────────
const stringToSign = [timestamp, method, path].join('\n');

console.log('=== 託管支付 — 查詢訂單 ===');
console.log('String to Sign:', stringToSign.replace(/\n/g, ' | '));

// ── HMAC-SHA256 → Base64 ────────────────────────────────────────────
const signature = CryptoJS.enc.Base64.stringify(
    CryptoJS.HmacSHA256(stringToSign, secretKey)
);

// ── 設置請求頭 ──────────────────────────────────────────────────────
pm.request.headers.upsert({ key: 'X-Api-Key',   value: apiKey });
pm.request.headers.upsert({ key: 'X-Timestamp', value: timestamp });
pm.request.headers.upsert({ key: 'X-Signature', value: signature });

---

查詢退款（帶查詢字符串的 GET）

退款查詢時，查詢字符串需作為簽名的第四個組成部分進行哈希。

1. 配置請求

方法： GETURL： https://api.paystablecoin.global/api/v1/merchants/1000/refunds

添加 Query Param：key refundOrderId，value REF_20260128120001。

2. 添加預請求腳本

// ── 配置 ────────────────────────────────────────────────────────────
const apiKey    = 'your-api-key';
const secretKey = 'your-api-secret';

// ── 時間戳 ──────────────────────────────────────────────────────────
const timestamp = Date.now().toString();

// ── 請求詳情 ────────────────────────────────────────────────────────
const method = pm.request.method;                 // "GET"
const urlObj = new URL(pm.request.url.toString());
const path   = urlObj.pathname;
const qs     = urlObj.search.replace(/^\?/, '');  // 如 "refundOrderId=REF_..."

// ── 查詢字符串哈希：SHA256 → Base64 ────────────────────────────────
const qsHash = CryptoJS.SHA256(qs).toString(CryptoJS.enc.Base64);

// ── 構建簽名字符串 ──────────────────────────────────────────────────
const stringToSign = [timestamp, method, path, qsHash].join('\n');

console.log('=== 託管支付 — 查詢退款 ===');
console.log('Query String:', qs);
console.log('QS Hash (Base64):', qsHash);
console.log('String to Sign:', stringToSign.replace(/\n/g, ' | '));

// ── HMAC-SHA256 → Base64 ────────────────────────────────────────────
const signature = CryptoJS.enc.Base64.stringify(
    CryptoJS.HmacSHA256(stringToSign, secretKey)
);

// ── 設置請求頭 ──────────────────────────────────────────────────────
pm.request.headers.upsert({ key: 'X-Api-Key',   value: apiKey });
pm.request.headers.upsert({ key: 'X-Timestamp', value: timestamp });
pm.request.headers.upsert({ key: 'X-Signature', value: signature });

---

常見問題排查

錯誤	可能原因	解決方法
Invalid signature	密鑰錯誤或請求體不匹配	驗證 apiKey/secretKey；在 Console 查看請求體哈希
Invalid or expired timestamp	系統時間不同步	同步系統時間；時間戳必須在 ±5 分鐘以內
Missing required field	請求體字段不完整	檢查所有必填字段是否存在
Invalid parameter: merchantId	URL 中商戶號錯誤	確認商戶號與憑證一致

相關文檔

• 託管支付整合指南 — 分步整合說明
• API 參考 — 完整接口與字段說明
• 簽名算法 — 簽名計算詳解