Postman — API Checkout

請替換示例憑證

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

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

API Checkout 不使用 X-Api-Key，只設置 X-Timestamp 和 X-Signature。

需要開通權限

API Checkout 為獨立產品，需單獨申請開通。請聯繫技術支持啟用。

簽名說明

API Checkout 使用與託管支付相同的簽名算法，但不包含 X-Api-Key。

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

GET 簽名： Base64(HMAC-SHA256(timestamp\nGET\npath, apiSecret))

---

獲取支付方式

渲染支付界面前，必須在運行時調用此接口，禁止硬編碼幣種/網絡組合。

1. 配置請求

方法： GETURL： https://api.paystablecoin.global/api/v1/merchants/MCH_20240101_ABC123/checkout/payment-methods

將 MCH_20240101_ABC123 替換為您的商戶號。

2. 添加預請求腳本

// ── 配置 ────────────────────────────────────────────────────────────
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('=== API Checkout — 獲取支付方式 ===');
console.log('String to Sign:', stringToSign.replace(/\n/g, ' | '));

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

// ── 設置請求頭（API Checkout 不使用 X-Api-Key）──────────────────────
pm.request.headers.upsert({ key: 'X-Timestamp', value: timestamp });
pm.request.headers.upsert({ key: 'X-Signature', value: signature });

響應包含可用的支付方式列表。按 displayOrder 升序排列後展示給用戶。

---

創建 Checkout 訂單

客戶選擇幣種和網絡後，立即創建訂單。

1. 配置請求

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

2. 設置請求體

進入 Body → raw → JSON：

{
  "merchantOrderId": "ORDER_{{$timestamp}}",
  "orderAmount": {
    "value": "100.50",
    "currency": "USDC"
  },
  "paymentMethodType": "ON_CHAIN_TRANSFER",
  "network": "tron",
  "expiresAt": "2026-12-31T23:59:59Z",
  "callbackUrl": "https://yoursite.com/webhook/checkout"
}

WARNING

orderAmount.currency 必須為穩定幣：USDC、USDT 或 USD1。API Checkout 不支持法幣計價。

3. 添加預請求腳本

// ── 配置 ────────────────────────────────────────────────────────────
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('=== API Checkout — 創建訂單 ===');
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);

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

4. 發送並驗證

成功響應包含展示給客戶的收款信息：

{
  "code": "00000",
  "data": {
    "depositAddress": "TXyz...1234",
    "cryptoPaymentAmount": { "value": "100.50", "currency": "USDC" },
    "networkDisplayName": "TRON Network",
    "expiresAt": "2026-12-31T23:59:59Z"
  }
}

WARNING

向客戶展示 cryptoPaymentAmount，而非 orderAmount。兩者可能因手續費存在差異。

---

查詢 Checkout 訂單

當 Webhook 未收到時作為備選方案。

1. 配置請求

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

將末尾的訂單號替換為實際的 merchantOrderId。

2. 添加預請求腳本

// ── 配置 ────────────────────────────────────────────────────────────
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');

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

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

每 5-10 秒輪詢一次，直到 status 達到終態：SUCCEEDED、FAILED 或 CLOSED。

---

常見問題排查

錯誤	可能原因	解決方法
Invalid signature	密鑰錯誤或請求體不匹配	在 Console 查看請求體哈希；驗證 secretKey
API_PERMISSION_DISABLED (50010)	Checkout 未開通	聯繫技術支持啟用 API Checkout
Invalid or expired timestamp	系統時間不同步	同步系統時間；時間戳必須在 ±5 分鐘以內
穩定幣幣種錯誤	使用了法幣	orderAmount.currency 請使用 USDC、USDT 或 USD1

相關文檔

• API Checkout 整合指南 — 分步整合說明
• API Checkout 參考文檔 — 完整接口與字段說明
• 簽名算法 — 簽名計算詳解