Postman 集成

請替換示例憑證

下方代碼示例使用了占位憑證。您必須將它們替換為從商戶後台獲取的實際值：

• PSTG6ELOB2YXKO4ZHRQ6NKTSBY → 您的實際 API Key
• MpkvVlXvYTZVPPJ0LReNA-g_yC7V7foe4UAj7tgWJSM → 您的實際 API Secret
• 1000 → 您的實際 Merchant ID（在 URL 路徑中）

設置步驟

1. 在 Postman 中創建新請求
2. 設置請求方法和 URL
3. 配置請求體（POST 請求）
4. 添加預請求腳本來計算簽名

請求體設置（創建訂單）

在添加預請求腳本之前，您需要在 Postman 中配置請求體：

步驟 1：配置 URL

方法： POSTURL： https://api.paystablecoin.global/api/v1/merchants/{merchantId}/orders

將 {merchantId} 替換為您的實際 Merchant ID（例如：1002）

步驟 2：配置請求體

1. 在 Postman 中，點擊 Body 標籤
2. 選擇 raw 格式
3. 從下拉菜單選擇 JSON
4. 輸入以下示例：

{
  "merchantOrderId": "TEST_ORDER_{{$timestamp}}",
  "orderAmount": {
    "value": "99.99",
    "currency": "USD"
  },
  "expiresAt": "2025-12-31T23:59:59Z",
  "returnUrl": "https://yoursite.com/payment/success",
  "paymentMethod": {
    "supportedCurrencies": ["USDT", "USDC"],
    "preferredChain": "TRON"
  }
}

POSTMAN 變量

您可以在 Postman 中使用 {{$timestamp}} 來自動生成唯一的訂單 ID。Postman 會將其替換為當前的 Unix 時間戳。

必填字段

以下字段是創建訂單的必填項：

• merchantOrderId - 您的唯一訂單號
• orderAmount - 包含 value 和 currency 的金額對象
• expiresAt - 訂單過期時間（UTC，ISO 8601 格式）
• returnUrl - 支付完成後客戶跳轉 URL

可選字段：

• description - 訂單描述
• callbackUrl - 服務端到服務端的 Webhook URL
• customer - 客戶信息
• items - 商品明細
• metadata - 自定義元數據

查看 API 接口 了解所有可用字段。

步驟 3：添加預請求腳本

現在您的請求體已配置完成，添加下方的預請求腳本來自動計算簽名。

POST 請求的預請求腳本 (創建訂單)

// 配置信息
const apiKey = 'PSTG6ELOB2YXKO4ZHRQ6NKTSBY';
const secretKey = 'MpkvVlXvYTZVPPJ0LReNA-g_yC7V7foe4UAj7tgWJSM';

// 生成時間戳 (毫秒)
const timestamp = Date.now().toString();

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

// 獲取請求體並替換 Postman 變量
let body = pm.request.body.raw;

// 在簽名前替換 {{$timestamp}} 為實際值
body = body.replace(/\{\{\$timestamp\}\}/g, timestamp);

// 壓縮 JSON（移除多餘空格）
body = JSON.stringify(JSON.parse(body));

// 更新請求體
pm.request.body.raw = body;

// 計算請求體哈希 (SHA256)
const bodyHash = CryptoJS.SHA256(body).toString(CryptoJS.enc.Base64);

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

console.log('=== 簽名計算 ===');
console.log('時間戳:', timestamp);
console.log('方法:', method);
console.log('路徑:', path);
console.log('請求體哈希:', bodyHash);
console.log('待簽名字符串:', stringToSign.replace(/\n/g, ' | '));

// 計算 HMAC-SHA256 簽名
const signature = CryptoJS.enc.Base64.stringify(CryptoJS.HmacSHA256(stringToSign, secretKey));

console.log('簽名:', signature);

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

查詢訂單設置

查詢訂單的設置較簡單，因為 GET 請求沒有請求體。

步驟 1：配置 URL

方法： GETURL： https://api.paystablecoin.global/api/v1/merchants/{merchantId}/orders/{merchantOrderId}

替換：

• {merchantId} 為您的 Merchant ID（例如：1002）
• {merchantOrderId} 為您要查詢的訂單號（例如：TEST_ORDER_123）

步驟 2：無需請求體

GET 請求不需要請求體。將 Body 標籤留空或選擇 none。

步驟 3：添加預請求腳本

GET 請求的預請求腳本 (查詢訂單)

// 配置信息
const apiKey = 'PSTG6ELOB2YXKO4ZHRQ6NKTSBY';
const secretKey = 'MpkvVlXvYTZVPPJ0LReNA-g_yC7V7foe4UAj7tgWJSM';

// 生成時間戳 (毫秒)
const timestamp = Date.now().toString();

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

// 構建簽名字符串 (GET 請求無請求體)
const signatureParts = [timestamp, method, path];
const stringToSign = signatureParts.join('\n');

console.log('=== 簽名計算 ===');
console.log('時間戳:', timestamp);
console.log('方法:', method);
console.log('路徑:', path);
console.log('待簽名字符串:', stringToSign.replace(/\n/g, ' | '));

// 計算 HMAC-SHA256 簽名
const signature = CryptoJS.enc.Base64.stringify(CryptoJS.HmacSHA256(stringToSign, secretKey));

console.log('簽名:', signature);

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

完整示例：創建您的第一個訂單

按照以下步驟在 Postman 中創建您的第一個訂單：

1. 創建新請求

1. 打開 Postman
2. 點擊 New → HTTP Request
3. 命名為 "Create Order"

2. 配置請求

• 方法： POST
• URL： https://api.paystablecoin.global/api/v1/merchants/1002/orders （將 1002 替換為您的 Merchant ID）

3. 添加請求體

1. 進入 Body 標籤
2. 選擇 raw 和 JSON
3. 粘貼此示例：

{
  "merchantOrderId": "MY_ORDER_{{$timestamp}}",
  "orderAmount": {
    "value": "99.99",
    "currency": "USD"
  },
  "expiresAt": "2025-12-31T23:59:59Z",
  "returnUrl": "https://yoursite.com/payment/success",
  "paymentMethod": {
    "supportedCurrencies": ["USDT", "USDC"],
    "preferredChain": "TRON"
  }
}

4. 添加預請求腳本

1. 進入 Pre-request Script 標籤
2. 粘貼上方的 POST 預請求腳本
3. 將 apiKey 和 secretKey 更新為您的實際憑證

5. 發送請求

點擊 Send。您應該收到如下響應：

{
  "code": "00000",
  "message": "Success",
  "data": {
    "orderId": "20251202000100100000030000000139",
    "merchantId": "1002",
    "merchantOrderId": "MY_ORDER_1764662113279",
    "status": "INIT",
    "checkoutUrl": "https://checkout.paystablecoin.global/...",
    "createdAt": "2025-12-02T15:55:14Z",
    "expiresAt": "2025-12-31T23:59:59Z",
    "orderAmount": {
      "value": "99.99",
      "currency": "USD"
    }
  }
}

成功！

如果您看到 "code": "00000" 和 "status": "INIT"，說明您的訂單創建成功！您可以使用 checkoutUrl 來完成支付。

故障排除

常見錯誤

錯誤："Invalid signature"（無效簽名）

• 檢查您的 apiKey 和 secretKey 是否正確
• 確保 JSON 請求體沒有多餘的空格（Postman 應該自動處理）
• 驗證您的系統時間已同步

錯誤："Invalid or expired timestamp"（時間戳無效或過期）

• 您的電腦時鐘可能未同步
• 時間戳必須在服務器時間的 ±5 分鐘內

錯誤："Missing required field: expiresAt"（缺少必填字段：expiresAt）

• 確保您的請求體包含所有必填字段
• 檢查字段名稱是否有拼寫錯誤

錯誤："Invalid parameter: merchantId"（無效參數：merchantId）

• 驗證您在 URL 中使用的 Merchant ID 是否正確
• 檢查 Merchant ID 是否與您的憑證匹配

相關文檔

• 簽名算法 - 了解簽名計算原理
• 重要注意事項 - 查看 JSON 格式要求