API 參考

基礎 URL

所有 API 請求應使用以下基礎 URL：

生產環境：

https://api.paystablecoin.global

完整端點示例：

https://api.paystablecoin.global/api/v1/merchants/{merchantId}/orders

API 環境

沙箱環境可用於開發與測試：

https://api.sandbox.paystablecoin.global

準備上線時，請切換至生產環境：

https://api.paystablecoin.global

訂單 API

訂單 API 允許商戶創建和查詢支付訂單。訂單支持法幣（USD）和穩定幣（USDT）計價，並可按交易配置可用的支付方式。

1. 創建訂單

功能描述

為商戶提供創建支付訂單的能力，支持法幣和穩定幣定價。

接口說明

方法： POST
路徑： /api/v1/merchants/{merchantId}/orders
Content-Type： application/json
鑒權： Base64(HMAC-SHA256(timestamp + "\n" + method + "\n" + path + "\n" + SHA256(body), API_SECRET))

請求頭（Headers）

請求頭	類型	必填	說明	示例
`X-Api-Key`	String	是	商戶 API 密鑰	`PSTG6ELOB2YXKO4ZHRQ6NKTSBY`
`X-Timestamp`	Long	是	請求時間戳（毫秒）	`1738112345000`
`X-Signature`	String	是	請求簽名	`base64-hmac-sha256`
`Content-Type`	String	是	固定值	`application/json`

路徑參數

參數	類型	必填	說明	示例
`merchantId`	String	是	商戶號（平台分配）	`1000`

請求體（Body）

必填參數

參數	類型	說明	示例
`merchantOrderId`	String	商戶訂單號（16-64位，字母數字下劃線連字符）	`your-order-123456789`
`orderAmount`	Object	訂單金額（見下方結構 ↓）	`{"value":"99.99","currency":"USD"}`
`expiresAt`	String	訂單過期時間（UTC，ISO 8601）	`2025-10-01T12:00:00Z`
`returnUrl`	String	客戶支付完成後瀏覽器跳轉 URL（最長2048字符）	`https://merchant.com/success`

OrderAmount 對象結構：

字段	類型	必填	說明	示例
`value`	String	是	金額值（支持最多18位小數）	`99.99`
`currency`	String	是	幣種代碼（3-16位大寫字母數字）	`USD` / `USDT`

說明：

法幣定價： {"value": "99.99", "currency": "USD"} - 支付時轉換為等值 USDT
穩定幣定價： {"value": "100.00", "currency": "USDT"} - 直接使用 USDT 支付

可選參數 - 支付配置

參數	類型	說明	示例
`paymentMethodConfig`	Object	支付方式配置（見下方結構 ↓）	見下方
`callbackUrl`	String	服務端到服務端的訂單狀態更新 Webhook URL（HTTPS，最長2048字符）	`https://merchant.com/webhook`

PaymentMethodConfig 對象結構：

字段	類型	必填	說明	示例
`allowedPaymentMethodTypes`	Array	否	允許的支付類型：`ON_CHAIN_TRANSFER`（鏈上錢包）、`EXCHANGE_TRANSFER`（交易所）。空/null = 不限制	`["EXCHANGE_TRANSFER"]`
`allowedPaymentMethods`	Array	否	具體支付方式（僅對 `EXCHANGE_TRANSFER` 有效）：`BINANCE`、`KUCOIN`。空/null = 不限制	`["BINANCE", "KUCOIN"]`

配置優先級：

如果指定了 allowedPaymentMethods，則只顯示這些支付方式
如果指定了 allowedPaymentMethodTypes，則只顯示這些類型
如果都未指定（null 或空），顯示所有可用支付方式

重要提示

如果您指定了 allowedPaymentMethods（例如 ["BINANCE"]），則必須同時指定包含 EXCHANGE_TRANSFER 的 allowedPaymentMethodTypes。否則，收銀台可能會顯示您不希望出現的支付方式。

建議： 限制特定交易所時，請始終同時指定這兩個字段。

配置示例

示例1：只允許幣安支付

json

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

示例2：只允許鏈上支付

json

{
  "allowedPaymentMethodTypes": ["ON_CHAIN_TRANSFER"]
}

示例3：幣安 + Kucoin

json

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

示例4：不限制（默認）

json

{
  "paymentMethodConfig": null
}

或完全省略此字段。

示例5：混合場景 - 幣安 + 鏈上支付

json

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

此配置允許所有鏈上支付方式 + 幣安支付。

理解 callbackUrl 與 returnUrl 的區別：

這兩個 URL 參數在支付流程中扮演不同的角色：

callbackUrl（服務端 Webhook）
- 用途：接收來自 PayStablecoin 服務器的實時支付狀態通知
- 觸發時機：當訂單狀態變更時自動調用
- 使用場景：您的後端服務器處理這些通知，更新數據庫中的訂單狀態
- 可選但建議使用，確保可靠的支付確認
returnUrl（瀏覽器重定向）
- 用途：將客戶的瀏覽器重定向回您的網站
- 觸發時機：客戶在支付頁面完成或取消支付後
- 使用場景：向客戶顯示訂單確認或感謝頁面
- 必填，提供良好的用戶體驗

最佳實踐

建議同時使用兩個 URL：

callbackUrl 用於可靠的後端訂單處理（即使用戶關閉瀏覽器也能收到通知）
returnUrl 用於流暢的用戶體驗（客戶看到確認頁面）

可選參數 - 客戶信息

參數	類型	說明	示例
`customer`	Object	買家信息（用於風控，見下方結構 ↓）	見下方
`customerIp`	String	客戶端 IP（IPv4/IPv6）	`203.0.113.10`
`userAgent`	String	客戶端 User-Agent（0-512字符）	`Mozilla/5.0...`

Customer 對象結構：

字段	類型	必填	說明	示例
`customerId`	String	否	買家 ID（商戶系統）	`u1001`
`email`	String	否	郵箱地址（用於通知）	`user@example.com`
`name`	String	否	買家姓名	`John Doe`
`phone`	String	否	手機號	`1234567890`

可選參數 - 訂單詳情

參數	類型	說明	示例
`description`	String	訂單描述（0-512字符）	`月度會員充值`
`items`	Array	商品明細列表（見下方結構 ↓）	見下方
`metadata`	String	商戶自定義元數據（JSON格式，最長4096字符）	`{"customerId":"u1001"}`

LineItem 對象結構：

字段	類型	必填	說明	示例
`name`	String	是	商品名稱	`鑽石包 x10`
`quantity`	Integer	是	數量（必須 > 0）	`1`
`amount`	Object	是	單價（同 OrderAmount 結構）	`{"value":"99.99","currency":"USD"}`
`description`	String	否	商品描述	`遊戲內虛擬貨幣`
`imageUrl`	String	否	商品圖片 URL	`https://example.com/img.jpg`

可選參數 - 僅限平台商戶

參數	類型	說明	示例
`subMerchants`	Array	子商戶信息列表（見下方結構 ↓）	見下方

SubMerchant 對象結構：

字段	類型	必填	說明	示例
`subMerchantId`	String	是	子商戶 ID（1-32位）	`SUB_001`
`name`	String	是	子商戶名稱（1-256字符）	`Apple Store`
`amount`	String	是	分賬金額（必須 > 0.01）	`500.00`
`mcc`	String	否	行業碼（4位數字，ISO 18245）	`5732`
`settlementRatio`	String	否	結算比例（0-1之間，如0.95代表95%）	`0.95`

重要說明

所有子商戶的 amount 總和必須等於訂單總金額。

完整請求示例

CURL 示例：

bash

curl -X POST https://api.paystablecoin.global/api/v1/merchants/1000/orders \
  -H "X-Api-Key: PSTG6ELOB2YXKO4ZHRQ6NKTSBY" \
  -H "X-Timestamp: 1738112345000" \
  -H "X-Signature: <base64-hmac-sha256>" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantOrderId": "your-order-123456789",
    "orderAmount": {
      "value": "99.99",
      "currency": "USD"
    },
    "expiresAt": "2025-10-01T12:00:00Z",
    "paymentMethodConfig": {
      "allowedPaymentMethodTypes": ["ON_CHAIN_TRANSFER", "EXCHANGE_TRANSFER"],
      "allowedPaymentMethods": ["BINANCE"]
    },
    "description": "月度會員充值",
    "customer": {
      "customerId": "u1001",
      "email": "user@example.com",
      "name": "John Doe"
    },
    "items": [
      {
        "name": "鑽石包 x10",
        "quantity": 1,
        "amount": {
          "value": "99.99",
          "currency": "USD"
        },
        "description": "遊戲內虛擬貨幣"
      }
    ],
    "customerIp": "203.0.113.10",
    "userAgent": "Mozilla/5.0...",
    "callbackUrl": "https://merchant.com/webhook",
    "returnUrl": "https://merchant.com/success",
    "metadata": "{\"customerId\":\"u1001\",\"source\":\"web\"}"
  }'

響應

所有響應的 HTTP Code 統一為 200，以 status + code + message 表達業務結果。

響應字段說明

AcquiringOrderView（訂單視圖）

字段	類型	說明	示例
`orderId`	String	平台訂單號	`ord_8fcb2a2e5b`
`merchantId`	String	商戶號	`M0001`
`merchantOrderId`	String	商戶訂單號	`your-order-123456789`
`status`	String	訂單狀態	`INIT` / `PROCESSING` / `SUCCEEDED` / `FAILED` / `CLOSED`
`checkoutUrl`	String	收銀台 URL	`https://checkout.paystablecoin.global/...`
`createdAt`	String	創建時間（UTC，ISO 8601）	`2025-09-28T12:00:00Z`
`expiresAt`	String	過期時間（UTC）	`2025-10-01T12:00:00Z`
`paidAt`	String	支付時間（UTC，僅支付成功後返回）	`2025-09-29T10:30:00Z`
`orderAmount`	Object	訂單金額	見 `OrderAmount` 定義
`cryptoPaidAmount`	Object	實際支付的穩定幣金額	見 `OrderAmount` 定義
`cryptoPaymentDetail`	Object	加密貨幣支付詳情	見 `CryptoPaymentDetail` 定義
`standardResponseCode`	String	標準返回碼	`00000`
`standardResponseMessage`	String	返回碼描述	`Success`

CryptoPaymentDetail（加密貨幣支付詳情 - 僅支付成功後返回）

字段	類型	說明	示例
`txHash`	String	交易哈希	`0x1234...abcd`
`network`	String	區塊鏈網絡	`TRON` / `ETHEREUM`
`fromAddress`	String	付款地址	`TXYz...4567`
`toAddress`	String	收款地址	`TQRs...8901`
`confirmations`	Integer	確認數	`21`
`blockNumber`	Long	區塊高度	`12345678`

響應示例

成功響應（status=INIT）：

json

{
  "code": "00000",
  "message": "Success",
  "data": {
    "orderId": "ord_8fcb2a2e5b",
    "merchantId": "M0001",
    "merchantOrderId": "your-order-123456789",
    "status": "INIT",
    "checkoutUrl": "https://checkout.paystablecoin.global/ord_8fcb2a2e5b",
    "createdAt": "2025-09-28T12:00:00Z",
    "expiresAt": "2025-10-01T12:00:00Z",
    "orderAmount": {
      "value": "99.99",
      "currency": "USD"
    },
    "cryptoPaidAmount": null,
    "cryptoPaymentDetail": null,
    "standardResponseCode": "00000",
    "standardResponseMessage": "Success"
  }
}

失敗響應（status=FAILED）：

json

{
  "code": "10001",
  "message": "Invalid parameter: orderAmount.currency must be ISO 4217",
  "data": {
    "orderId": null,
    "merchantId": "M0001",
    "merchantOrderId": "your-order-123456789",
    "status": "FAILED",
    "standardResponseCode": "10001",
    "standardResponseMessage": "Invalid parameter"
  }
}

2. 查詢訂單

功能描述

為商戶提供查詢單個訂單詳細信息的能力，支持通過商戶訂單號或平台訂單號查詢。

接口說明

方法： GET
路徑： /api/v1/merchants/{merchantId}/orders/{merchantOrderId}
簽名說明： GET 請求沒有 Body，簽名內容為 timestamp + "\n" + method + "\n" + path
鑒權： 同創建訂單接口

請求頭（Headers）

請求頭	類型	必填	說明	示例
`X-Api-Key`	String	是	商戶 API 密鑰	`PSTG6ELOB2YXKO4ZHRQ6NKTSBY`
`X-Timestamp`	Long	是	請求時間戳（毫秒）	`1738112345000`
`X-Signature`	String	是	請求簽名（無Body，簽名path即可）	`base64-hmac-sha256`
`Content-Type`	String	是	固定值	`application/json`

路徑參數

參數	類型	必填	說明	示例
`merchantId`	String	是	商戶號	`M0001`
`merchantOrderId`	String	是	商戶訂單號	`your-order-123456789`

請求示例：

bash

curl -X GET "https://api.paystablecoin.global/api/v1/merchants/1000/orders/your-order-123456789" \
  -H "X-Api-Key: PSTG6ELOB2YXKO4ZHRQ6NKTSBY" \
  -H "X-Timestamp: 1738112345000" \
  -H "X-Signature: <base64-hmac-sha256>" \
  -H "Content-Type: application/json"

簽名字符串： 1738112345000\nGET\n/api/v1/merchants/1000/orders/your-order-123456789

響應

所有響應的 HTTP Code 統一為 200，以 status + code + message 表達業務結果。

響應字段詳細說明

AcquiringOrderView（訂單詳細信息）

字段	類型	說明	示例
`orderId`	String	平台訂單號	`ord_8fcb2a2e5b`
`merchantId`	String	商戶號	`M0001`
`merchantOrderId`	String	商戶訂單號	`your-order-123456789`
`status`	String	訂單狀態（見狀態說明）	`INIT` / `SUCCEEDED` / `FAILED` / `CLOSED`
`checkoutUrl`	String	收銀台 URL	`https://checkout.paystablecoin.global/...`
`createdAt`	String	訂單創建時間（UTC，ISO 8601）	`2025-09-28T12:00:00Z`
`expiresAt`	String	訂單過期時間（UTC）	`2025-10-01T12:00:00Z`
`paidAt`	String	支付成功時間（UTC，僅支付成功時返回）	`2025-09-28T12:05:10Z`
`orderAmount`	Object	訂單金額（商戶定價）	見 `OrderAmount` 定義
`cryptoPaidAmount`	Object	實際支付金額（加密貨幣）	見 `OrderAmount` 定義
`cryptoPaymentDetail`	Object	鏈上支付詳情（僅支付成功時返回）	見 `CryptoPaymentDetail` 定義
`standardResponseCode`	String	標準返回碼	`00000`
`standardResponseMessage`	String	返回碼描述	`Success`

CryptoPaymentDetail（鏈上支付詳情 - 僅支付成功時返回）

字段	類型	說明	示例
`txHash`	String	交易哈希（區塊鏈瀏覽器可查）	`0xabcf2a2e5b8fcb...`
`network`	String	區塊鏈網絡	`TRON` / `ETHEREUM` / `BSC`
`fromAddress`	String	付款地址（買家錢包地址）	`TKeoD2qV8HR4sfm4b9a3e2g1jCD7fDCZuv`
`toAddress`	String	收款地址（平台收款地址）	`TPoD2qV8HR4sfm4b9a3e2g1jCD7fDAZaa`
`confirmations`	Integer	區塊確認數	`25`
`blockNumber`	Long	交易所在區塊高度	`45678901`

訂單狀態說明

狀態	說明	是否終態	後續可能狀態
`INIT`	訂單已創建，等待支付	否	`PROCESSING` / `CLOSED`
`PROCESSING`	支付處理中（已檢測到鏈上交易）	否	`SUCCEEDED` / `FAILED`
`SUCCEEDED`	支付成功（已到賬且確認數足夠）	是	-
`FAILED`	支付失敗（金額不足/超時/異常）	是	-
`CLOSED`	訂單已關閉（商戶取消/自動過期）	是	-

狀態流轉圖：

INIT ──┬──> PROCESSING ──┬──> SUCCEEDED（終態）
       │                 └──> FAILED（終態）
       └──> CLOSED（終態，取消或過期）

響應示例

查詢成功 - 已支付訂單

json

{
  "code": "00000",
  "message": "Success",
  "data": {
    "orderId": "ord_8fcb2a2e5b",
    "merchantId": "M0001",
    "merchantOrderId": "your-order-123456789",
    "status": "SUCCEEDED",
    "checkoutUrl": "https://checkout.paystablecoin.global/ord_8fcb2a2e5b",
    "createdAt": "2025-09-28T12:00:00Z",
    "expiresAt": "2025-10-01T12:00:00Z",
    "paidAt": "2025-09-28T12:05:10Z",
    "orderAmount": {
      "value": "99.99",
      "currency": "USD"
    },
    "cryptoPaidAmount": {
      "value": "100.02",
      "currency": "USDT"
    },
    "cryptoPaymentDetail": {
      "txHash": "0xabcf2a2e5b8fcb2a2e5b8fcb2a2e5b8fcb2a2e5b8fcb2a2e5b8fcb2a2e5b8f",
      "network": "TRON",
      "fromAddress": "TKeoD2qV8HR4sfm4b9a3e2g1jCD7fDCZuv",
      "toAddress": "TPoD2qV8HR4sfm4b9a3e2g1jCD7fDAZaa",
      "confirmations": 25,
      "blockNumber": 45678901
    },
    "standardResponseCode": "00000",
    "standardResponseMessage": "Success"
  }
}

查詢成功 - 待支付訂單

當訂單等待支付時，paidAt、cryptoPaidAmount 和 cryptoPaymentDetail 將為 null：

json

{
  "code": "00000",
  "message": "Success",
  "data": {
    "orderId": "ord_9def3c5e7d",
    "merchantId": "M0001",
    "merchantOrderId": "pending-order-456",
    "status": "INIT",
    "checkoutUrl": "https://checkout.paystablecoin.global/ord_9def3c5e7d",
    "createdAt": "2025-09-29T10:00:00Z",
    "expiresAt": "2025-10-02T10:00:00Z",
    "paidAt": null,
    "orderAmount": {
      "value": "199.99",
      "currency": "USD"
    },
    "cryptoPaidAmount": null,
    "cryptoPaymentDetail": null,
    "standardResponseCode": "00000",
    "standardResponseMessage": "Success"
  }
}

查詢失敗 - 訂單不存在

json

{
  "code": "40001",
  "message": "Order not found",
  "data": {
    "orderId": null,
    "merchantId": "M0001",
    "merchantOrderId": "your-order-not-exist",
    "status": "FAILED",
    "standardResponseCode": "40001",
    "standardResponseMessage": "Order not found"
  }
}

重要說明

字段存在性：
- paidAt：僅在訂單支付成功（status=SUCCEEDED）時返回
- cryptoPaidAmount：僅在訂單支付成功時返回
- cryptoPaymentDetail：僅在訂單支付成功時返回，包含鏈上交易詳情
金額差異：
- orderAmount：商戶創建訂單時的定價金額（可能是法幣或穩定幣）
- cryptoPaidAmount：買家實際支付的加密貨幣金額（匯率轉換後可能略有差異）
- 示例： 訂單金額 99.99 USD，實際支付 100.02 USDT（因匯率波動）
確認數說明：
- confirmations：區塊鏈確認數，值越大越安全
- 不同網絡的確認數要求：
  - TRON： 通常需要19個確認
  - ETHEREUM： 通常需要12個確認
  - BSC： 通常需要15個確認
查詢頻率建議：
- 訂單創建後，建議每5-10秒查詢一次狀態
- 訂單支付成功後，無需繼續查詢
- 使用 Webhook 回調可減少主動查詢次數，提升效率

退款 API

退款 API 允許商戶針對已完成的付款發起退款。退款金額為原始訂單的全額。退款申請提交後，將依序經過即時校驗、資金凍結、非同步處理及結果通知等流程。

3. 創建退款

接口說明

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

請求頭（Headers）

請求頭	類型	必填	說明	示例
`X-Api-Key`	String	是	商戶 API 密鑰	`PSTG6ELOB2YXKO4ZHRQ6NKTSBY`
`X-Timestamp`	Long	是	請求時間戳（毫秒，13位）	`1738112345000`
`X-Signature`	String	是	請求簽名（Base64編碼）。算法：`Base64(HMAC-SHA256(timestamp\nMETHOD\npath\nBase64(SHA256(body)), apiSecret))`	`base64-hmac-sha256`
`Content-Type`	String	是	固定值	`application/json`

路徑參數

參數	類型	必填	說明	示例
`merchantId`	String	是	商戶號（平台分配）	`1000`

請求體（Body）

字段	類型	必填	說明	示例
`merchantRefundOrderId`	String	是	商戶退款單號（全局唯一，用於幂等控制）	`REFUND_20260128_001`
`acquiringOrderId`	String	是	原支付單號（要退款的 PSC 訂單號）	`ORDER_20260128_001`
`refundReason`	String	是	退款原因（英文，便於審核和追溯）	`Customer request full refund`
`notifyUrl`	String	否	退款結果通知地址。留空則使用商戶默認配置	`https://merchant.example.com/webhook/refund`
`extraData`	String	否	擴展數據（JSON 格式），原樣返回	`{"orderId":"MERCHANT_ORDER_123"}`

請求示例

bash

curl -X POST https://api.paystablecoin.global/api/v1/merchants/1000/refunds \
  -H "X-Api-Key: PSTG6ELOB2YXKO4ZHRQ6NKTSBY" \
  -H "X-Timestamp: 1738112345000" \
  -H "X-Signature: <base64-hmac-sha256>" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantRefundOrderId": "REFUND_20260128_001",
    "acquiringOrderId": "ORDER_20260128_001",
    "refundReason": "Customer request full refund",
    "notifyUrl": "https://merchant.example.com/webhook/refund",
    "extraData": "{\"orderId\":\"MERCHANT_ORDER_123\",\"userId\":\"USER_456\"}"
  }'

響應字段

字段	類型	說明	示例
`code`	String	響應碼。`00000` 表示退款申請已受理	`00000`
`message`	String	響應消息	`Refund application accepted`
`data`	Object	退款單數據（見下方 `RefundOrderData`）	-
`requestId`	String	請求 ID，用於追蹤	`req_abc123xyz`
`timestamp`	Long	響應時間戳（毫秒）	`1706428800000`

RefundOrderData

字段	類型	說明	示例
`refundOrderId`	String	PSC 退款單號（全局唯一）	`REF_20260128120001`
`merchantRefundOrderId`	String	商戶退款單號	`REFUND_20260128_001`
`acquiringOrderId`	String	原支付單號	`ORDER_20260128_001`
`merchantOrderId`	String	商戶原始訂單號	`MERCHANT_ORDER_123`
`status`	String	退款狀態（見下方狀態說明）	`PENDING`
`refundAmount`	String	退款金額（用戶實際支付金額）	`100.50`
`refundCurrency`	String	退款幣種	`USDT`
`merchantDeductAmount`	String	商戶扣款金額（淨結算金額）	`100.1985`
`paymentMethod`	String	原支付方式	`BINANCE_PAY`
`createdTime`	String（ISO 8601）	創建時間	`2026-01-28T12:00:00Z`
`estimatedCompletionTime`	String（ISO 8601）	預計完成時間	`2026-01-28T12:15:00Z`
`completedTime`	String（ISO 8601）	完成時間（僅 SUCCEEDED 時返回）	`2026-01-28T12:05:30Z`
`failedTime`	String（ISO 8601）	失敗時間（僅 FAILED 時返回）	`2026-01-28T12:03:15Z`
`closedTime`	String（ISO 8601）	關閉時間（僅 CLOSED 時返回）	`2026-01-28T14:30:00Z`
`errorCode`	String	錯誤碼（僅 FAILED 時返回）	`EXCHANGE_BALANCE_INSUFFICIENT`
`errorMessage`	String	錯誤消息（僅 FAILED 時返回）	`Insufficient funds in Binance funding wallet`
`extraData`	String	擴展數據，原樣返回	`{"orderId":"MERCHANT_ORDER_123"}`

退款狀態說明

狀態	說明	是否終態
`INIT`	退款記錄已創建	否
`PENDING`	申請已受理，等待處理	否
`PROCESSING`	處理中	否
`SUCCEEDED`	退款成功	是
`FAILED`	退款失敗	是
`CLOSED`	退款已關閉	是

響應示例

成功——退款申請已受理：

json

{
  "code": "00000",
  "message": "Refund application accepted",
  "data": {
    "refundOrderId": "REF_20260128120001",
    "merchantRefundOrderId": "REFUND_20260128_001",
    "acquiringOrderId": "ORDER_20260128_001",
    "merchantOrderId": "MERCHANT_ORDER_123",
    "status": "PENDING",
    "refundAmount": "100.50",
    "refundCurrency": "USDT",
    "merchantDeductAmount": "100.1985",
    "paymentMethod": "BINANCE_PAY",
    "createdTime": "2026-01-28T12:00:00Z",
    "estimatedCompletionTime": "2026-01-28T12:15:00Z"
  },
  "requestId": "req_abc123xyz",
  "timestamp": 1706428800000
}

錯誤——餘額不足：

json

{
  "code": "INSUFFICIENT_BALANCE",
  "message": "Merchant balance insufficient for refund",
  "details": "Required: 100.00 USDT, Available: 50.00 USDT",
  "requestId": "req_abc123xyz",
  "timestamp": 1706428800000
}

錯誤——退款時效已過：

json

{
  "code": "REFUND_PERIOD_EXPIRED",
  "message": "Order refund period has expired",
  "details": "Order paid at: 2025-12-15T10:00:00Z, Refund deadline: 2026-01-14T10:00:00Z (30 days)",
  "requestId": "req_abc123xyz",
  "timestamp": 1706428800000
}

HTTP 狀態碼

HTTP 狀態碼	含義	說明
`200`	OK	退款申請已受理
`400`	Bad Request	請求參數錯誤或業務校驗失敗
`401`	Unauthorized	簽名驗證失敗
`404`	Not Found	訂單不存在
`429`	Too Many Requests	請求頻率超限

4. 查詢退款

接口說明

方法： GET
路徑： /api/v1/merchants/{merchantId}/refunds
鑒權： 是
簽名說明： GET 請求無 Body，查詢參數單獨哈希作為第四個組成部分。算法：Base64(HMAC-SHA256(timestamp\nMETHOD\npath\nBase64(SHA256(queryString)), apiSecret))

TIP

至少需要提供以下其中一個查詢參數：refundOrderId、merchantRefundOrderId 或 acquiringOrderId。

請求頭（Headers）

請求頭	類型	必填	說明	示例
`X-Api-Key`	String	是	商戶 API 密鑰	`PSTG6ELOB2YXKO4ZHRQ6NKTSBY`
`X-Timestamp`	Long	是	請求時間戳（毫秒）	`1738112345000`
`X-Signature`	String	是	請求簽名（無 Body）	`base64-hmac-sha256`

路徑參數

參數	類型	必填	說明	示例
`merchantId`	String	是	商戶號	`1000`

查詢參數

參數	類型	必填	說明	示例
`refundOrderId`	String	否	PSC 退款單號（優先級最高）	`REF_20260128120001`
`merchantRefundOrderId`	String	否	商戶退款單號	`REFUND_20260128_001`
`acquiringOrderId`	String	否	原支付單號（返回該訂單的第一筆退款）	`ORDER_20260128_001`

請求示例

bash

curl -X GET "https://api.paystablecoin.global/api/v1/merchants/1000/refunds?refundOrderId=REF_20260128120001" \
  -H "X-Api-Key: PSTG6ELOB2YXKO4ZHRQ6NKTSBY" \
  -H "X-Timestamp: 1738112345000" \
  -H "X-Signature: <base64-hmac-sha256>"

簽名字符串： 1738112345000\nGET\n/api/v1/merchants/1000/refunds\nBase64(SHA256("refundOrderId=REF_20260128120001"))

響應

返回與創建退款相同的響應結構，data 為單個 RefundOrderData 對象（見上方 RefundOrderData）。

響應示例

退款成功：

json

{
  "code": "00000",
  "message": "Query successful",
  "data": {
    "refundOrderId": "REF_20260128120001",
    "merchantRefundOrderId": "REFUND_20260128_001",
    "acquiringOrderId": "ORDER_20260128_001",
    "merchantOrderId": "MERCHANT_ORDER_123",
    "status": "SUCCEEDED",
    "refundAmount": "100.50",
    "refundCurrency": "USDT",
    "merchantDeductAmount": "100.1985",
    "paymentMethod": "BINANCE_PAY",
    "createdTime": "2026-01-28T12:00:00Z",
    "completedTime": "2026-01-28T12:05:30Z",
    "extraData": "{\"orderId\":\"MERCHANT_ORDER_123\"}"
  },
  "requestId": "req_xyz789abc",
  "timestamp": 1706428835000
}

退款失敗：

json

{
  "code": "00000",
  "message": "Query successful",
  "data": {
    "refundOrderId": "REF_20260128120003",
    "merchantRefundOrderId": "REFUND_20260128_003",
    "acquiringOrderId": "ORDER_20260128_003",
    "status": "FAILED",
    "refundAmount": "75.00",
    "refundCurrency": "USDT",
    "paymentMethod": "BINANCE_PAY",
    "createdTime": "2026-01-28T12:02:00Z",
    "failedTime": "2026-01-28T12:03:15Z",
    "errorCode": "EXCHANGE_BALANCE_INSUFFICIENT",
    "errorMessage": "Insufficient funds in Binance funding wallet"
  },
  "requestId": "req_xyz789abc",
  "timestamp": 1706428835000
}

退款單不存在：

json

{
  "code": "REFUND_NOT_FOUND",
  "message": "Refund order not found",
  "details": "merchantRefundOrderId: REFUND_NONEXISTENT",
  "requestId": "req_notfound123",
  "timestamp": 1706428900000
}

HTTP 狀態碼

HTTP 狀態碼	含義	說明
`200`	OK	查詢成功
`404`	Not Found	退款單不存在

5. 批量查詢退款

接口說明

方法： POST
路徑： /api/v1/merchants/{merchantId}/refunds/batch-query
Content-Type： application/json
鑒權： 是

適用於批量對賬、報表生成、狀態同步等場景。單次最多查詢 100 個退款單。

請求頭（Headers）

同創建退款。

路徑參數

參數	類型	必填	說明	示例
`merchantId`	String	是	商戶號	`1000`

請求體（Body）

字段	類型	必填	說明	示例
`merchantRefundOrderIds`	Array<String>	是	商戶退款單號列表（最多 100 個）	`["REFUND_001", "REFUND_002"]`

請求示例

bash

curl -X POST https://api.paystablecoin.global/api/v1/merchants/1000/refunds/batch-query \
  -H "X-Api-Key: PSTG6ELOB2YXKO4ZHRQ6NKTSBY" \
  -H "X-Timestamp: 1738112345000" \
  -H "X-Signature: <base64-hmac-sha256>" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantRefundOrderIds": [
      "REFUND_20260128_001",
      "REFUND_20260128_002",
      "REFUND_20260128_003"
    ]
  }'

響應字段

字段	類型	說明
`code`	String	`00000` 表示成功
`message`	String	響應消息
`data`	Array	`RefundOrderData` 對象列表（結構同單條查詢）
`requestId`	String	請求 ID
`timestamp`	Long	響應時間戳（毫秒）

響應示例

json

{
  "code": "00000",
  "message": "Batch query successful",
  "data": [
    {
      "refundOrderId": "REF_20260128120001",
      "merchantRefundOrderId": "REFUND_20260128_001",
      "status": "SUCCEEDED",
      "refundAmount": "100.50",
      "refundCurrency": "USDT"
    },
    {
      "refundOrderId": "REF_20260128120002",
      "merchantRefundOrderId": "REFUND_20260128_002",
      "status": "PROCESSING",
      "refundAmount": "50.00",
      "refundCurrency": "USDC"
    },
    {
      "refundOrderId": "REF_20260128120003",
      "merchantRefundOrderId": "REFUND_20260128_003",
      "status": "FAILED",
      "refundAmount": "75.00",
      "refundCurrency": "USDT",
      "errorCode": "EXCHANGE_BALANCE_INSUFFICIENT"
    }
  ],
  "requestId": "req_batch123",
  "timestamp": 1706428900000
}

退款 Webhook

退款 Webhook 通知文檔請參閱 Webhook 通知頁面。

API 參考 ​

基礎 URL ​

訂單 API ​

1. 創建訂單 ​

功能描述 ​

接口說明 ​

請求頭（Headers） ​

路徑參數 ​

請求體（Body） ​

必填參數 ​

可選參數 - 支付配置 ​

可選參數 - 客戶信息 ​

可選參數 - 訂單詳情 ​

可選參數 - 僅限平台商戶 ​

完整請求示例 ​

響應 ​

響應字段說明 ​

AcquiringOrderView（訂單視圖） ​

CryptoPaymentDetail（加密貨幣支付詳情 - 僅支付成功後返回） ​

響應示例 ​

2. 查詢訂單 ​

功能描述 ​

接口說明 ​

請求頭（Headers） ​

路徑參數 ​

響應 ​

響應字段詳細說明 ​

AcquiringOrderView（訂單詳細信息） ​

CryptoPaymentDetail（鏈上支付詳情 - 僅支付成功時返回） ​

訂單狀態說明 ​

響應示例 ​

查詢成功 - 已支付訂單 ​

查詢成功 - 待支付訂單 ​

查詢失敗 - 訂單不存在 ​

重要說明 ​

退款 API ​

3. 創建退款 ​

接口說明 ​

請求頭（Headers） ​

路徑參數 ​

請求體（Body） ​

請求示例 ​

響應字段 ​

RefundOrderData ​

退款狀態說明 ​

響應示例 ​

HTTP 狀態碼 ​

4. 查詢退款 ​

接口說明 ​

請求頭（Headers） ​

路徑參數 ​

查詢參數 ​

請求示例 ​

響應 ​

響應示例 ​

HTTP 狀態碼 ​

5. 批量查詢退款 ​

接口說明 ​

請求頭（Headers） ​

路徑參數 ​

請求體（Body） ​

請求示例 ​

響應字段 ​

響應示例 ​

相關文檔 ​

API 參考

基礎 URL

訂單 API

1. 創建訂單

功能描述

接口說明

請求頭（Headers）

路徑參數

請求體（Body）

必填參數

可選參數 - 支付配置

可選參數 - 客戶信息

可選參數 - 訂單詳情

可選參數 - 僅限平台商戶

完整請求示例

響應

響應字段說明

AcquiringOrderView（訂單視圖）

CryptoPaymentDetail（加密貨幣支付詳情 - 僅支付成功後返回）

響應示例

2. 查詢訂單

功能描述

接口說明

請求頭（Headers）

路徑參數

響應

響應字段詳細說明

AcquiringOrderView（訂單詳細信息）

CryptoPaymentDetail（鏈上支付詳情 - 僅支付成功時返回）

訂單狀態說明

響應示例

查詢成功 - 已支付訂單

查詢成功 - 待支付訂單

查詢失敗 - 訂單不存在

重要說明

退款 API

3. 創建退款

接口說明

請求頭（Headers）

路徑參數

請求體（Body）

請求示例

響應字段

RefundOrderData

退款狀態說明

響應示例

HTTP 狀態碼

4. 查詢退款

接口說明

請求頭（Headers）

路徑參數

查詢參數

請求示例

響應

響應示例

HTTP 狀態碼

5. 批量查詢退款

接口說明

請求頭（Headers）

路徑參數

請求體（Body）

請求示例

響應字段

響應示例

相關文檔