取得儲值訂單詳情 | ToAPIs Documentation

GET

/api/v1/account/billing/topups/%7Btrade_no%7D

中國大陸用戶請注意: 中國大陸用戶請使用 https://toapis.cn 作為接口地址 (Base URL). 文檔示例中的 https://toapis.com 請替換為 https://toapis.cn.

驗證, 分頁及錯誤處理請參閱接入說明.

使用說明

僅主帳戶可查詢自身帳單. 子帳戶存取時回傳 HTTP 403, 主帳戶也不能查詢成員帳單.

預設最近 31 天, 最長 366 天, 依建立時間與訂單 ID 倒序. recorded_payment_amount/payment_currency 保留原付款幣別, 不用來推算 credits. planned_credits 為計畫入帳, credited_credits 為確認入帳, refunded_credits 獨立記錄退款, 不扣減原入帳. 非成功訂單 credited_credits="0"; 歷史金額不明時為 null, 原因位於 meta. 不含人工贈送及獨立線下退款. refund=null 不保證沒有其他退款, 本地快照不證明銀行卡已入帳. GET 不向付款平台查單或補單.

驗證

Authorizationstring請求頭必填

使用系統存取權杖, 格式為 Bearer YOUR_SYSTEM_ACCESS_TOKEN. 此介面不接受模型 API Key, 不需要 X-User-Id.

請求參數

trade_nostring路徑必填

平台儲值訂單編號, 不接受外部付款平台訂單 ID 代替.

限制: minLength=1; maxLength=255.

請求示例

curl --request GET \
  --url 'https://toapis.com/api/v1/account/billing/topups/trade_example_01' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'

import requests

response = requests.get(
    "https://toapis.com/api/v1/account/billing/topups/trade_example_01",
    headers={"Authorization": "Bearer YOUR_SYSTEM_ACCESS_TOKEN"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

const url = new URL("https://toapis.com/api/v1/account/billing/topups/trade_example_01");

const response = await fetch(url, {
  headers: { Authorization: "Bearer YOUR_SYSTEM_ACCESS_TOKEN" },
  signal: AbortSignal.timeout(30_000),
});

if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
console.log(await response.json());

回應欄位

範例使用虛構資料, 並假設 credits_per_usd="100". 實際換算請以回應為準.

codeinteger

業務狀態碼, 成功時為 0.

messagestring

回應訊息, 成功時為空字串. 錯誤訊息依請求語言回傳.

dataobject

本次查詢的結果物件.

data.idstring

儲值訂單的內部 ID. 查詢詳情時使用 trade_no. 以十進位 ID 字串回傳.

data.trade_nostring

平台儲值訂單編號, 用於詳情查詢, 並非外部付款訂單 ID.

data.providerstring

付款服務提供方.

data.statusstring

儲值訂單狀態. 僅成功訂單的確認入帳額度表示已入帳.

data.trigger_typestring | null

儲值觸發方式, 如手動或自動. 歷史記錄可能為 null.

data.created_atstring | null

建立時間. 時間格式為含時區的 RFC 3339. 無法確認或不適用時為 null.

data.completed_atstring | null

訂單完成時間. 時間格式為含時區的 RFC 3339. 無法確認或不適用時為 null.

data.recorded_payment_amountstring | null

本地訂單記錄的原幣付款金額, 幣別見 payment_currency, 不用來推算 credits. 以十進位字串回傳以保留精度. 無法確認或不適用時為 null.

data.payment_currencystring | null

訂單記錄的付款原幣別. 無法確認或不適用時為 null.

data.planned_creditsstring | null

計畫入帳的 credits, 不等同於確認入帳額度. 以十進位字串回傳以保留精度. 無法確認或不適用時為 null.

data.credited_creditsstring | null

確認入帳的 credits. 非成功訂單為 "0", 歷史無法確認時為 null. 以十進位字串回傳以保留精度.

data.refunded_creditsstring | null

訂單記錄的退款 credits, 獨立顯示, 不扣減原確認入帳額度. 以十進位字串回傳以保留精度. 無法確認或不適用時為 null.

data.refundobject | null

訂單的本地退款快照. null 不保證沒有獨立線下退款, 也不代表銀行卡入帳狀態.

data.refund.statusstring

訂單記錄的退款狀態.

data.refund.recorded_amountstring | null

本地退款記錄的原幣金額, 幣別見 currency. 以十進位字串回傳以保留精度. 無法確認或不適用時為 null.

data.refund.currencystring | null

金額採用的原幣別. 無法確認或不適用時為 null.

data.refund.recorded_atstring | null

本地退款記錄時間. 時間格式為含時區的 RFC 3339. 無法確認或不適用時為 null.

data.metaobject

資料來源, 查詢範圍及資料口徑等中繼資料.

data.meta.sourcestring

資料來源. 本地設定或帳本快照不代表 Stripe 即時狀態. 固定值: "local_ledger".

data.meta.refund_coveragestring

退款資訊覆蓋範圍, 僅含訂單退款快照. 固定值: "order_snapshot_only".

data.meta.standalone_offline_refunds_includedboolean

是否包含獨立線下退款. 目前為 false.

data.meta.payment_amount_basisstring

付款金額的資料口徑, 採用本地訂單快照. 固定值: "local_order_snapshot".

data.meta.consistencystring

資料一致性類型. eventual 表示記錄可能稍後更新.

data.meta.payment_amount_sourcestring

用於確認付款金額的記錄來源.

data.meta.credit_amount_sourcestring

用於確認入帳額度的記錄來源.

響應示例

{
  "code": 0,
  "message": "",
  "data": {
    "id": "501",
    "trade_no": "trade_example_01",
    "provider": "stripe",
    "status": "success",
    "trigger_type": "manual",
    "created_at": "2026-11-01T08:00:00Z",
    "completed_at": "2026-11-01T08:01:00Z",
    "recorded_payment_amount": "10",
    "payment_currency": "USD",
    "planned_credits": "1000",
    "credited_credits": "1000",
    "refunded_credits": "0",
    "refund": null,
    "meta": {
      "source": "local_ledger",
      "consistency": "eventual",
      "payment_amount_basis": "local_order_snapshot",
      "refund_coverage": "order_snapshot_only",
      "standalone_offline_refunds_included": false,
      "payment_amount_source": "paid_amount",
      "credit_amount_source": "credited_credits"
    }
  }
}