託管支付整合指南

概覽

託管支付 API 是接受加密貨幣付款的最簡單方式。您通過 API 創建訂單，然後將客戶重定向至 PSC 的託管支付頁面。PSC 負責完整的支付體驗——支付方式選擇、身份驗證與確認。

適合以下場景：

希望快速整合、最小化前端工作量的商戶
同時接受交易所付款（Binance Pay、KuCoin Pay）和鏈上轉賬
以法幣（USD）計價，支付時自動轉換為穩定幣

工作原理

商戶服務器                PSC API              客戶瀏覽器
      |                      |                     |
      |--- POST /orders ----->|                     |
      |<-- checkoutUrl -------|                     |
      |                      |                     |
      |----------- 重定向至 checkoutUrl ---------->|
      |                      |<-- 選擇支付方式 -----|
      |                      |<-- 完成支付 ---------|
      |                      |                     |
      |<-- POST webhook ------|                     |
      |--- HTTP 200 --------->|                     |
      |                      |                     |
      |<----------- 重定向至 returnUrl -------------|

第一步：創建支付訂單

調用 POST /api/v1/merchants/{merchantId}/orders，提交訂單信息。

bash

curl -X POST https://api.paystablecoin.global/api/v1/merchants/1000/orders \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Timestamp: 1738112345000" \
  -H "X-Signature: <calculated-signature>" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantOrderId": "ORDER_20260128_001",
    "orderAmount": { "value": "99.99", "currency": "USD" },
    "expiresAt": "2026-01-28T13:00:00Z",
    "returnUrl": "https://your-store.com/order/success",
    "callbackUrl": "https://your-server.com/webhook/payment"
  }'

關鍵參數：

參數	說明
`orderAmount.currency`	`USD` 為法幣計價（支付時自動轉換為 USDT），`USDT` 為直接穩定幣計價
`returnUrl`	客戶完成或取消支付後的跳轉地址
`callbackUrl`	接收異步支付狀態通知的服務端地址
`expiresAt`	建議設置為當前時間後 30 分鐘
`paymentMethodConfig`	可選——限制可用的支付方式（見下文）

響應示例：

json

{
  "code": "00000",
  "data": {
    "orderId": "PSC_ORDER_123",
    "checkoutUrl": "https://pay.paystablecoin.global/checkout/PSC_ORDER_123",
    "status": "PENDING"
  }
}

第二步：重定向客戶

將客戶瀏覽器重定向至響應中的 checkoutUrl。PSC 託管頁面將處理：

支付方式選擇（Binance Pay、KuCoin Pay、鏈上錢包）
交易所身份驗證
支付確認與回執

您無需構建任何支付界面。

第三步：接收 Webhook 通知

訂單狀態變更（已支付、失敗、過期）時，PSC 會向您的 callbackUrl 發送 POST 請求。

請立即返回 HTTP 200。任何其他響應或超時均會觸發重試。

Webhook 載荷結構、簽名驗證及重試策略請參閱 Webhook 通知。

第四步：處理 returnUrl

支付完成後，PSC 將客戶重定向至您的 returnUrl。使用此頁面顯示確認信息。

WARNING

請勿依賴 returnUrl 確認支付結果。客戶可能在重定向完成前關閉瀏覽器。請始終通過 Webhook 或主動查詢訂單狀態來確認支付。

限制支付方式

默認情況下，您帳戶下所有可用的支付方式均會展示給客戶。使用 paymentMethodConfig 進行限制：

僅 Binance Pay：

json

{
  "paymentMethodConfig": {
    "allowedPaymentMethodTypes": ["EXCHANGE_TRANSFER"],
    "allowedPaymentMethods": ["BINANCE"]
  }
}

僅鏈上轉賬：

json

{
  "paymentMethodConfig": {
    "allowedPaymentMethodTypes": ["ON_CHAIN_TRANSFER"]
  }
}

Binance Pay + 鏈上混合：

json

{
  "paymentMethodConfig": {
    "allowedPaymentMethodTypes": ["ON_CHAIN_TRANSFER", "EXCHANGE_TRANSFER"],
    "allowedPaymentMethods": ["BINANCE"]
  }
}

完整的 paymentMethodConfig 說明請參閱 API 端點。

整合清單

[ ] 每筆訂單生成唯一的 merchantOrderId（用於幂等控制）
[ ] 將 expiresAt 設置為當前時間後約 30 分鐘
[ ] 務必提供 callbackUrl——不要依賴 returnUrl 確認支付結果
[ ] 處理業務邏輯前先驗證 Webhook 簽名
[ ] 處理幂等性：相同 merchantOrderId 重複提交將返回已有訂單

託管支付整合指南 ​

概覽 ​

工作原理 ​

第一步：創建支付訂單 ​

第二步：重定向客戶 ​

第三步：接收 Webhook 通知 ​

第四步：處理 returnUrl ​

限制支付方式 ​

整合清單 ​

相關文檔 ​

託管支付整合指南

概覽

工作原理

第一步：創建支付訂單

第二步：重定向客戶

第三步：接收 Webhook 通知

第四步：處理 returnUrl

限制支付方式

整合清單

相關文檔