ToAPIsToAPIs
帳戶查詢帳單

列出儲值訂單

使用系統存取權杖讀取目前帳戶的資料

GET
/api/v1/account/billing/topups

中國大陸用戶請注意: 中國大陸用戶請使用 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.

請求參數

fromstring查詢

含時區的 RFC 3339 起始時間, 包含該時刻. 與 to 成對提供.

限制: date-time.

tostring查詢

含時區的 RFC 3339 結束時間, 不包含該時刻, 必須晚於 from.

限制: date-time.

cursorstring查詢

原樣傳入上一頁的 next_cursor, 保留相同篩選條件. 變更條件後重新開始.

限制: maxLength=2048.

limitinteger查詢預設值: 20

每頁最多回傳的項目數.

限制: minimum=1; maximum=100; 預設值: 20.

providerstring查詢

付款管道.

限制: stripe, wechat, alipay, creem, nowpayments, offline.

statusstring查詢

帳單: pending, success, superseded, expired, failed, partially_paid.

限制: pending, success, superseded, expired, failed, partially_paid.

請求示例

curl --request GET \
  --url 'https://toapis.com/api/v1/account/billing/topups?from=2026-11-01T00:00:00Z&to=2026-11-02T00:00:00Z&provider=stripe&limit=20' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'
import requests

response = requests.get(
    "https://toapis.com/api/v1/account/billing/topups",
    headers={"Authorization": "Bearer YOUR_SYSTEM_ACCESS_TOKEN"},
    params={
        "from": "2026-11-01T00:00:00Z",
        "to": "2026-11-02T00:00:00Z",
        "provider": "stripe",
        "limit": "20"
    },
    timeout=30,
)
response.raise_for_status()
print(response.json())
const url = new URL("https://toapis.com/api/v1/account/billing/topups");
url.search = new URLSearchParams({
  "from": "2026-11-01T00:00:00Z",
  "to": "2026-11-02T00:00:00Z",
  "provider": "stripe",
  "limit": "20"
}).toString();

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". 實際換算請以回應為準.

清單位於 data.items, 以 has_more 及 next_cursor 分頁. 最後一頁的游標為 null, 不回傳總數.

codeinteger

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

messagestring

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

dataobject

本次查詢的結果物件.

data.itemsobject[]

目前頁面的記錄清單, 空結果為 [].

data.items[].idstring

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

data.items[].trade_nostring

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

data.items[].providerstring

付款服務提供方.

data.items[].statusstring

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

data.items[].trigger_typestring | null

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

data.items[].created_atstring | null

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

data.items[].completed_atstring | null

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

data.items[].recorded_payment_amountstring | null

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

data.items[].payment_currencystring | null

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

data.items[].planned_creditsstring | null

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

data.items[].credited_creditsstring | null

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

data.items[].refunded_creditsstring | null

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

data.items[].refundobject | null

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

data.items[].refund.statusstring

訂單記錄的退款狀態.

data.items[].refund.recorded_amountstring | null

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

data.items[].refund.currencystring | null

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

data.items[].refund.recorded_atstring | null

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

data.items[].metaobject

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

data.items[].meta.sourcestring

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

data.items[].meta.refund_coveragestring

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

data.items[].meta.standalone_offline_refunds_includedboolean

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

data.items[].meta.payment_amount_basisstring

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

data.items[].meta.consistencystring

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

data.items[].meta.payment_amount_sourcestring

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

data.items[].meta.credit_amount_sourcestring

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

data.has_moreboolean

是否還有下一頁.

data.next_cursorstring | null

下一頁游標, 原樣作為 cursor 傳入並保留篩選條件. 最後一頁為 null.

data.metaobject

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

data.meta.sourcestring

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

data.meta.scopestring

查詢資料的歸屬範圍, 目前為驗證帳戶自身.

data.meta.fromstring

查詢時間範圍下界, 包含該時刻.

data.meta.tostring

查詢時間範圍上界, 不包含該時刻.

data.meta.consistencystring

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

data.meta.refund_coveragestring

退款資訊覆蓋範圍, 僅含訂單退款快照.

data.meta.standalone_offline_refunds_includedboolean

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

響應示例

{
  "code": 0,
  "message": "",
  "data": {
    "items": [
      {
        "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"
        }
      }
    ],
    "has_more": false,
    "next_cursor": null,
    "meta": {
      "source": "local_ledger",
      "scope": "self",
      "from": "2026-11-01T00:00:00Z",
      "to": "2026-11-02T00:00:00Z",
      "consistency": "eventual",
      "refund_coverage": "order_snapshot_only",
      "standalone_offline_refunds_included": false
    }
  }
}

取得帳戶任務詳情

使用系統存取權杖讀取目前帳戶的資料

取得儲值訂單詳情

使用系統存取權杖讀取目前帳戶的資料