PayStablecoin API

繁体中文

English

繁体中文

English

Appearance

API Checkout ​

概覽 ​

API Checkout 為希望構建自定義收銀台 UI 的商戶提供簡潔的一步支付流程。商戶完全控制用戶界面，平台處理所有鏈上支付能力。

核心特性：

  • 自定義收銀台 UI： 商戶完全控制收銀台用戶體驗
  • 一步流程： 直接創建訂單，無需預先報價
  • 鏈上轉賬支付： 支持 TRON、ETH、BSC 等多種區塊鏈網絡
  • 僅限穩定幣： 支持 USDC、USDT 和 USD1

需要開通權限

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

身份認證 ​

所有 API 請求使用與主 API 相同的 HMAC-SHA256 簽名方案。每次請求需包含以下請求頭：

請求頭類型必填說明示例
X-TimestampLong是請求時間戳（毫秒，13位）1640000000000
X-SignatureString是請求簽名（Base64編碼）calculated-signature

簽名算法：

signaturePayload = timestamp + "\n" + METHOD + "\n" + path + "\n" + SHA256(body)
X-Signature = Base64(HMAC-SHA256(signaturePayload, apiSecret))
  • SHA256(body) 為請求體的 Base64 編碼哈希值
  • GET 請求無查詢參數時，省略第四個組成部分：timestamp + "\n" + METHOD + "\n" + path
  • GET 請求有查詢參數時，queryString 單獨哈希作為第四個組成部分；path 不包含查詢參數
  • HTTP 方法必須大寫

詳細說明及代碼示例請參閱簽名算法。

環境 ​

環境基礎 URL
生產環境https://api.paystablecoin.global
沙盒環境https://api.sandbox.paystablecoin.global

1. 獲取支付方式 ​

在創建訂單前，獲取商戶可用的支付方式列表。使用此接口在收銀台 UI 展示可用幣種/網絡，並在創建訂單前驗證組合是否有效。

接口說明 ​

  • 方法： GET
  • 路徑： /api/v1/merchants/{merchantId}/checkout/payment-methods
  • 鑒權： 是

路徑參數 ​

參數類型必填說明示例
merchantIdString是商戶號MCH_20240101_ABC123

請求示例 ​

bash
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>"

響應字段 ​

字段類型說明示例
codeString響應碼。00000 表示成功00000
messageString響應消息Success
dataObject響應數據-
data.merchantIdString商戶號MCH_20240101_ABC123
data.paymentMethodsArray支付方式列表-
data.paymentMethods[].paymentMethodTypeString支付方式類型ON_CHAIN_TRANSFER
data.paymentMethods[].cryptoCurrencyString加密貨幣幣種（USDC / USDT / USD1）USDC
data.paymentMethods[].networkString區塊鏈網絡代碼tron
data.paymentMethods[].networkDisplayNameString網絡展示名稱TRON Network
data.paymentMethods[].minAmountNumber最小支付金額0.1
data.paymentMethods[].maxAmountNumber最大支付金額999999999
data.paymentMethods[].estimatedConfirmationTimeSecInteger預計確認時間（秒）60
data.paymentMethods[].displayOrderInteger顯示順序（數字越小越靠前）1

響應示例 ​

json
{
  "code": "00000",
  "message": "Success",
  "data": {
    "merchantId": "MCH_20240101_ABC123",
    "paymentMethods": [
      {
        "paymentMethodType": "ON_CHAIN_TRANSFER",
        "cryptoCurrency": "USDC",
        "network": "tron",
        "networkDisplayName": "TRON Network",
        "minAmount": 0.10,
        "maxAmount": 999999999.00,
        "estimatedConfirmationTimeSec": 60,
        "displayOrder": 1
      },
      {
        "paymentMethodType": "ON_CHAIN_TRANSFER",
        "cryptoCurrency": "USDC",
        "network": "eth",
        "networkDisplayName": "Ethereum(ERC20)",
        "minAmount": 10.00,
        "maxAmount": 999999999.00,
        "estimatedConfirmationTimeSec": 900,
        "displayOrder": 2
      },
      {
        "paymentMethodType": "ON_CHAIN_TRANSFER",
        "cryptoCurrency": "USDT",
        "network": "tron",
        "networkDisplayName": "TRON Network",
        "minAmount": 0.10,
        "maxAmount": 999999999.00,
        "estimatedConfirmationTimeSec": 60,
        "displayOrder": 3
      }
    ]
  }
}

2. 創建 Checkout 訂單 ​

用戶在商戶自建收銀台選擇支付方式後，調用此接口創建訂單。平台返回訂單信息，商戶在收銀台展示收款地址和應付金額供用戶完成支付。

接口說明 ​

  • 方法： POST
  • 路徑： /api/v1/merchants/{merchantId}/checkout/orders
  • Content-Type： application/json
  • 鑒權： 是

路徑參數 ​

參數類型必填說明示例
merchantIdString是商戶號MCH_20240101_ABC123

請求體——必填字段 ​

字段類型必填說明示例
merchantOrderIdString是商戶訂單號（商戶維度唯一，16-64位，僅支持字母、數字、_、-，用於幂等性控制）ORDER_2024010112345678
orderAmountObject是訂單金額。僅支持 USDC、USDT、USD1{"value": "100.50", "currency": "USDC"}
orderAmount.valueString是穩定幣金額100.50
orderAmount.currencyString是穩定幣代碼：USDC / USDT / USD1USDC
paymentMethodTypeString是支付方式類型。固定值：ON_CHAIN_TRANSFERON_CHAIN_TRANSFER
networkString是區塊鏈網絡代碼（如 tron、eth、bsc），必須與 orderAmount.currency 為有效組合tron
expiresAtString是訂單過期時間（UTC，ISO 8601 格式），最長支持創建後 24 小時2024-01-01T13:00:00Z

請求體——選填字段 ​

字段類型必填說明示例
customerObject否買家信息（用於風控）-
customer.emailString否買家郵箱user@example.com
customer.nameString否買家姓名John Doe
customer.customerIdString否買家 ID（商戶系統的用戶 ID）USR_12345
descriptionString否訂單描述（最長 512 字符）Purchase of 2 items
itemsArray否商品明細列表-
items[].nameString否商品名稱iPhone 15 Pro
items[].quantityInteger否商品數量1
items[].priceString否商品單價999.00
items[].currencyString否商品幣種USDC
customerIpString否客戶端 IP 地址（用於風控，最長 64 字符）192.168.1.100
userAgentString否客戶端 User-Agent（用於設備識別，最長 512 字符）Mozilla/5.0...
callbackUrlString否Webhook 回調地址（支付狀態變更時異步通知，最長 2048 字符）https://api.merchant.com/webhooks/payment
metadataString否商戶自定義元數據（平台原樣返回，最長 4096 字符，建議 JSON 格式）{"orderId":"12345","source":"web"}

重要說明

  1. merchantOrderId 在商戶維度必須唯一。相同 merchantOrderId 的重複請求將返回已有訂單，不會重複創建。
  2. orderAmount.currency 與 network 的組合必須出現在獲取支付方式的結果中。請先調用該接口確認可用組合。
  3. expiresAt 建議設置為創建時間後 30 分鐘。

請求示例 ​

示例 1：USDC / TRON

bash
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",
    "description": "Purchase of 2 items",
    "callbackUrl": "https://api.merchant.com/webhooks/payment"
  }'

示例 2：USDC / ETH（附帶買家信息）

bash
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_2024010112345679",
    "orderAmount": {
      "value": "200.00",
      "currency": "USDC"
    },
    "paymentMethodType": "ON_CHAIN_TRANSFER",
    "network": "eth",
    "expiresAt": "2024-01-01T13:00:00Z",
    "customer": {
      "email": "user@example.com",
      "name": "John Doe",
      "customerId": "USR_12345"
    },
    "items": [
      {
        "name": "iPhone 15 Pro",
        "quantity": 1,
        "price": "999.00",
        "currency": "USDC"
      }
    ],
    "customerIp": "192.168.1.100",
    "callbackUrl": "https://api.merchant.com/webhooks/payment"
  }'

響應字段 ​

字段類型說明示例
codeString響應碼。00000 表示成功00000
messageString響應消息Success
data.orderIdString平台訂單號ORD_20240101_1234567890ABCDEF
data.merchantIdString商戶號MCH_20240101_ABC123
data.merchantOrderIdString商戶訂單號ORDER_2024010112345678
data.statusString訂單狀態：INIT / PROCESSING / SUCCEEDED / FAILED / CLOSEDINIT
data.orderAmountObject訂單金額{"value": "100.50", "currency": "USDC"}
data.cryptoPaymentAmountObject用戶應付金額（含手續費等）{"value": "101.00", "currency": "USDC"}
data.depositAddressString收款地址（用戶需要轉賬到此地址）TYdRLmP9kN4oY3hZ8xT6wQ2vS5uW7aV1b
data.networkString區塊鏈網絡代碼tron
data.networkDisplayNameString網絡展示名稱TRON Network
data.createdAtString（ISO 8601）訂單創建時間（UTC）2024-01-01T12:00:00Z
data.expiresAtString（ISO 8601）訂單過期時間（UTC）2024-01-01T13:00:00Z

收銀台展示說明

訂單創建成功後，請立即在收銀台展示以下信息：

  • depositAddress — 用戶需要轉賬的錢包地址
  • cryptoPaymentAmount — 用戶需要支付的確切金額（非 orderAmount）
  • networkDisplayName — 必須在此網絡上完成轉賬
  • 基於 expiresAt 的倒計時

用戶需要支付至少 cryptoPaymentAmount.value 的金額。支付多於此金額可接受；支付不足則訂單失敗。

響應示例 ​

成功：

json
{
  "code": "00000",
  "message": "Success",
  "data": {
    "orderId": "ORD_20240101_1234567890ABCDEF",
    "merchantId": "MCH_20240101_ABC123",
    "merchantOrderId": "ORDER_2024010112345678",
    "status": "INIT",
    "orderAmount": {
      "value": "100.50",
      "currency": "USDC"
    },
    "cryptoPaymentAmount": {
      "value": "101.00",
      "currency": "USDC"
    },
    "depositAddress": "TYdRLmP9kN4oY3hZ8xT6wQ2vS5uW7aV1b",
    "network": "tron",
    "networkDisplayName": "TRON Network",
    "createdAt": "2024-01-01T12:00:00Z",
    "expiresAt": "2024-01-01T13:00:00Z"
  }
}

錯誤——參數無效：

json
{
  "code": "10001",
  "message": "Invalid parameter: orderAmount.currency must be one of: USDC, USDT, USD1",
  "data": null
}

3. 查詢 Checkout 訂單 ​

查詢 Checkout 訂單的最新狀態和詳情。

接口說明 ​

  • 方法： GET
  • 路徑： /api/v1/merchants/{merchantId}/checkout/orders/{merchantOrderId}
  • 鑒權： 是
  • 簽名說明： GET 請求無 Body 或查詢參數。算法：Base64(HMAC-SHA256(timestamp\nMETHOD\npath, apiSecret))

路徑參數 ​

參數類型必填說明示例
merchantIdString是商戶號MCH_20240101_ABC123
merchantOrderIdString是商戶訂單號ORDER_2024010112345678

請求示例 ​

bash
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>"

簽名字符串： 1640000000000\nGET\n/api/v1/merchants/MCH_20240101_ABC123/checkout/orders/ORDER_2024010112345678

響應字段 ​

字段類型說明示例
codeString響應碼。00000 表示成功00000
messageString響應消息Success
data.orderIdString平台訂單號ORD_20240101_1234567890ABCDEF
data.merchantIdString商戶號MCH_20240101_ABC123
data.merchantOrderIdString商戶訂單號ORDER_2024010112345678
data.statusString訂單狀態（見下方狀態說明）SUCCEEDED
data.orderAmountObject訂單金額{"value": "100.50", "currency": "USDC"}
data.cryptoPaymentAmountObject用戶應付加密金額（含手續費等）{"value": "101.00", "currency": "USDC"}
data.cryptoPaidAmountObject用戶實際支付金額（僅支付成功後有值）{"value": "101.00", "currency": "USDC"}
data.depositAddressString收款地址TYdRLmP9kN4oY3hZ8xT6wQ2vS5uW7aV1b
data.networkString區塊鏈網絡代碼tron
data.networkDisplayNameString網絡展示名稱TRON Network
data.cryptoPaymentDetailObject鏈上支付詳情（僅鏈上支付成功後有值）見下方
data.cryptoPaymentDetail.networkString區塊鏈網絡tron
data.cryptoPaymentDetail.cryptoCurrencyString加密貨幣USDC
data.cryptoPaymentDetail.transactionHashString交易哈希0x1234567890abcdef...
data.cryptoPaymentDetail.fromAddressString發送地址TXdQKjYz8f9vN3kYh2xL6mP8sR5wT7uV2a
data.cryptoPaymentDetail.toAddressString收款地址TYdRLmP9kN4oY3hZ8xT6wQ2vS5uW7aV1b
data.cryptoPaymentDetail.amountString交易金額101.00
data.cryptoPaymentDetail.confirmationsInteger當前確認數21
data.cryptoPaymentDetail.requiredConfirmationsInteger需要的確認數21
data.createdAtString（ISO 8601）訂單創建時間（UTC）2024-01-01T12:00:00Z
data.expiresAtString（ISO 8601）訂單過期時間（UTC）2024-01-01T13:00:00Z
data.paidAtString（ISO 8601）訂單支付時間（UTC，僅支付成功後有值）2024-01-01T12:15:30Z

訂單狀態說明 ​

狀態說明是否終態
INIT訂單已創建，等待支付否
PROCESSING已檢測到鏈上交易，確認中否
SUCCEEDED支付已確認並完成是
FAILED支付失敗（金額不足、超時或異常）是
CLOSED訂單已關閉（過期或取消）是

響應示例 ​

支付成功的訂單：

json
{
  "code": "00000",
  "message": "Success",
  "data": {
    "orderId": "ORD_20240101_1234567890ABCDEF",
    "merchantId": "MCH_20240101_ABC123",
    "merchantOrderId": "ORDER_2024010112345678",
    "status": "SUCCEEDED",
    "orderAmount": {
      "value": "100.50",
      "currency": "USDC"
    },
    "cryptoPaymentAmount": {
      "value": "101.00",
      "currency": "USDC"
    },
    "cryptoPaidAmount": {
      "value": "101.00",
      "currency": "USDC"
    },
    "depositAddress": "TYdRLmP9kN4oY3hZ8xT6wQ2vS5uW7aV1b",
    "network": "tron",
    "networkDisplayName": "TRON Network",
    "cryptoPaymentDetail": {
      "network": "tron",
      "cryptoCurrency": "USDC",
      "transactionHash": "0x1234567890abcdef1234567890abcdef",
      "fromAddress": "TXdQKjYz8f9vN3kYh2xL6mP8sR5wT7uV2a",
      "toAddress": "TYdRLmP9kN4oY3hZ8xT6wQ2vS5uW7aV1b",
      "amount": "101.00",
      "confirmations": 21,
      "requiredConfirmations": 21
    },
    "createdAt": "2024-01-01T12:00:00Z",
    "expiresAt": "2024-01-01T13:00:00Z",
    "paidAt": "2024-01-01T12:15:30Z"
  }
}

Webhook 通知

API Checkout Webhook 通知文檔請參閱 Webhook 通知 頁面。

錯誤碼 ​

錯誤碼代碼值說明解決方案
INVALID_PARAMETER10001請求參數無效根據接口規範檢查所有請求參數
INVALID_AMOUNT10004訂單金額必須大於 0提供有效的正數金額
INVALID_EXPIRES_AT10005過期時間早於當前時間將 expiresAt 設置為未來時間
INVALID_MERCHANT10007商戶號無效驗證您的商戶號是否正確
UNCONFIGURED_PAYMENT_METHOD10011幣種/網絡組合不支持，或商戶未配置此支付方式調用獲取支付方式確認可用組合
ORDER_ALREADY_EXISTS20001merchantOrderId 已存在更換訂單號，或檢查是否重複提交
ORDER_NOT_FOUND40001訂單不存在驗證訂單號是否正確
API_PERMISSION_DISABLED50010商戶未開通 API Checkout 權限聯繫技術支持開通 API Checkout
SYSTEM_ERROR99999系統內部錯誤稍後重試，或聯繫技術支持

附錄：支持的網絡與幣種 ​

以下為平台支持的幣種/網絡組合。商戶實際可用的支付方式由平台配置決定——請始終通過獲取支付方式確認。

幣種 / 網絡組合 ​

幣種網絡代碼網絡展示名稱
USD1ethEthereum(ERC20)
USD1bscBNB Smart Chain(BEP20)
USDCethEthereum(ERC20)
USDCpolygonPolygon
USDCoptimismOptimism
USDCarbitrumArbitrum One
USDCbscBNB Smart Chain(BEP20)
USDCbaseBase
USDCsolanaSolana
USDTbscBNB Smart Chain(BEP20)
USDTethEthereum(ERC20)
USDTpolygonPolygon
USDTarbitrumArbitrum One
USDToptimismOptimism
USDTsolanaSolana
USDTtronTron(TRC20)

網絡說明 ​

網絡代碼全稱說明
tronTron波場網絡，TRC20 標準。速度快、費用低，推薦用於 USDT
ethEthereum以太坊主網，ERC20 標準。手續費較高，確認時間約 15 分鐘
bscBNB Smart Chain幣安智能鏈，BEP20 標準。手續費低
polygonPolygonPolygon 網絡（原 Matic），以太坊側鏈
arbitrumArbitrum OneArbitrum Layer 2 擴容方案
optimismOptimismOptimism Layer 2 擴容方案
baseBaseCoinbase 推出的 Layer 2 網絡
solanaSolanaSolana 高性能公鏈

最佳實踐 ​

  1. 先獲取支付方式： 創建訂單前，始終調用獲取支付方式接口，避免 UNCONFIGURED_PAYMENT_METHOD 錯誤，同時獲取準確的 UI 展示數據。
  2. 幂等性處理： 每次結賬使用穩定且唯一的 merchantOrderId。用戶重試時複用相同 ID，避免重複創建訂單。
  3. 設置 30 分鐘過期時間： 建議將 expiresAt 設置為創建後 30 分鐘，避免時間過短或過長。
  4. 展示 cryptoPaymentAmount 而非 orderAmount： 用戶需要支付 cryptoPaymentAmount 的金額，可能因手續費與 orderAmount 有所不同。
  5. 配置 callbackUrl： 強烈建議配置，否則需要主動輪詢才能檢測到支付完成。
  6. 輪詢作為備選： 如未收到 Webhook，每 5–10 秒輪詢一次查詢 Checkout 訂單。
  7. 幂等處理 Webhook： 使用 acquiringOrderId 或 merchantOrderId 去重，同一事件可能多次推送。

相關文檔 ​

Released under the MIT License.

Copyright © 2025 PayStablecoin