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 中. 仅含 TopUp 订单, 不含人工赠送和独立线下退款. refund=null 不保证没有其他退款; 本地退款快照不证明银行卡已到账. 不向支付平台查单或补单.

鉴权

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
    }
  }
}

获取账户任务详情

使用系统访问令牌读取当前账户的数据

获取充值订单详情

使用系统访问令牌读取当前账户的数据