API Checkout 整合指南

概覽

API Checkout 讓您完全掌控支付界面。您無需將客戶重定向至 PSC 託管頁面，而是自行構建完整的收銀台體驗。PSC 負責鏈上支付基礎設施——生成收款地址、監控區塊鏈確認、並在支付完成後通知您。

適合以下場景：

• 需要完全自定義品牌化收銀台體驗的商戶
• 原生移動端應用或單頁應用（SPA）等不適合瀏覽器跳轉的場景
• 直接接受鏈上穩定幣轉賬（USDC、USDT、USD1）

需要開通權限

API Checkout 為獨立產品，需單獨申請開通。請聯繫技術支持以啟用。未開通時，請求將返回錯誤碼 50010（API_PERMISSION_DISABLED）。

---

工作原理

商戶前端            商戶服務器                PSC API
      |                  |                       |
      |                  |--- 獲取支付方式 ------>|
      |                  |<-- 支付方式列表 --------|
      |<-- 渲染選擇器 ---|                        |
      |-- 用戶選擇 ----->|                        |
      |                  |--- POST /checkout ---->|
      |                  |   /orders              |
      |                  |<-- depositAddress -----|
      |<-- 展示地址 + ---|                        |
      |   金額 + 倒計時  |                        |
      |                  |                        |
      |   （用戶完成鏈上轉賬）                     |
      |                  |                        |
      |                  |<--- POST webhook ------|
      |                  |--- {"code":"00000"} -->|
      |<-- 更新狀態 -----|                        |

---

第一步：獲取可用支付方式

在渲染支付界面之前，先獲取您的商戶帳戶可用的支付方式。必須在運行時調用，禁止硬編碼幣種/網絡組合。

curl -X GET "https://api.paystablecoin.global/api/v1/merchants/MCH_20240101_ABC123/checkout/payment-methods" \
  -H "X-Timestamp: 1640000000000" \
  -H "X-Signature: <calculated-signature>"

響應中的關鍵字段：

字段	用途
cryptoCurrency	展示的幣種（USDC / USDT / USD1）
network	創建訂單時傳入的網絡代碼
networkDisplayName	展示給用戶的網絡名稱（如「TRON Network」）
minAmount / maxAmount	創建訂單前驗證金額是否在範圍內
estimatedConfirmationTimeSec	向客戶展示預計確認時間
displayOrder	按此字段升序排列展示順序

---

第二步：構建支付方式選擇界面

在收銀台 UI 中展示可用選項，至少應包含：

• 加密貨幣幣種（USDC / USDT / USD1）
• 網絡名稱（networkDisplayName）
• 預計確認時間

僅展示獲取支付方式接口返回的組合——可用支付方式取決於商戶配置，可能隨時變更。

---

第三步：創建 Checkout 訂單

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

curl -X POST https://api.paystablecoin.global/api/v1/merchants/MCH_20240101_ABC123/checkout/orders \
  -H "X-Timestamp: 1640000000000" \
  -H "X-Signature: <calculated-signature>" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantOrderId": "ORDER_2024010112345678",
    "orderAmount": { "value": "100.50", "currency": "USDC" },
    "paymentMethodType": "ON_CHAIN_TRANSFER",
    "network": "tron",
    "expiresAt": "2024-01-01T13:00:00Z",
    "callbackUrl": "https://your-server.com/webhook/checkout"
  }'

關鍵參數：

參數	說明
merchantOrderId	商戶維度唯一。相同 ID 重複提交返回已有訂單（幂等）
orderAmount.currency	必須為穩定幣：USDC、USDT 或 USD1——不支持法幣計價
network	必須與客戶選擇的支付方式匹配，且與 orderAmount.currency 形成有效組合
expiresAt	建議設置為當前時間後 30 分鐘，最長不超過 24 小時
callbackUrl	強烈建議填寫——用於接收支付結果的 Webhook 地址

---

第四步：展示收款頁面

使用響應數據構建客戶看到的支付界面：

響應字段	展示方式
data.depositAddress	以文字和二維碼兩種形式展示
data.cryptoPaymentAmount.value	客戶需要支付的精確金額
data.cryptoPaymentAmount.currency	與金額一同展示
data.networkDisplayName	醒目展示——轉入錯誤網絡將導致資產丟失
data.expiresAt	驅動實時倒計時

WARNING

務必展示 cryptoPaymentAmount，而非 orderAmount。兩者可能因手續費存在差異。客戶需支付至少 cryptoPaymentAmount.value 的金額——支付不足將導致訂單失敗。

---

第五步：接收並驗證 Webhook

PSC 檢測到鏈上交易並確認後，將調用您的 callbackUrl。

簽名驗證——在處理任何業務邏輯之前：

1. 從請求頭中獲取 X-Timestamp 和 X-Signature
2. 讀取完整的原始請求體字符串
3. 計算：Base64(HMAC-SHA256(timestamp + "\n" + requestBody, apiSecret))
4. 將計算結果與 X-Signature 對比
5. 驗證 X-Timestamp 在當前時間 5 分鐘內

響應要求——API Checkout 的 Webhook 響應體為必填：

{
  "code": "00000"
}

您的接口必須在 5 秒內返回 HTTP 200 及上述響應體。任何其他響應或超時均會觸發重試。完整重試策略請參閱 API Checkout 參考文檔。

使用 acquiringOrderId 或 merchantOrderId 進行去重——同一事件可能多次推送。

---

第六步：處理訂單過期

若 expiresAt 到達時仍未檢測到支付，訂單狀態將變為 CLOSED。您應當：

• 倒計時歸零時立即停止並更新界面
• 停止展示收款地址
• 允許客戶重新發起新訂單

---

輪詢作為備選方案

若服務端未收到 Webhook（網絡問題、callbackUrl 配置錯誤等），每 5–10 秒輪詢一次訂單狀態：

curl -X GET "https://api.paystablecoin.global/api/v1/merchants/MCH_20240101_ABC123/checkout/orders/ORDER_2024010112345678" \
  -H "X-Timestamp: 1640000000000" \
  -H "X-Signature: <calculated-signature>"

當 status 達到終態（SUCCEEDED、FAILED 或 CLOSED）時停止輪詢。

---

整合清單

• [ ] 運行時調用獲取支付方式接口——禁止硬編碼幣種/網絡組合
• [ ] 向客戶展示 cryptoPaymentAmount（而非 orderAmount）
• [ ] 醒目展示 networkDisplayName，避免用戶轉入錯誤網絡
• [ ] 基於 expiresAt 實現實時倒計時
• [ ] 處理每條 Webhook 前驗證 X-Signature
• [ ] 在 5 秒內響應 HTTP 200 + {"code":"00000"}
• [ ] 使用 acquiringOrderId 或 merchantOrderId 處理重複推送
• [ ] 實現輪詢機制作為 Webhook 未收到時的備選方案

---

相關文檔

• API Checkout 參考文檔 — 完整的接口與字段說明
• 簽名算法 — 請求簽名計算方法
• 認證請求頭 — 請求頭設置說明