● 余额与对账 · /v1

余额与对账

余额、结算批次、明细导出。给你的 ERP 和财务系统自动拉数用,不用人去后台点。

查询余额

GET /v1/finance/balances

按渠道账户分开返回,不合并。合并会掩盖某个渠道的欠款——那是对账时最先出事的地方。

available 可结算、pending 已扣款未到结算周期、reserved 争议冻结与保证金。

Query 参数

currency string

响应 200

currency string
currency_exponent integer
available integer 可结算金额
pending integer 已扣款未到结算周期
reserved integer 争议冻结与保证金
connector_code string 余额按渠道账户分开,不合并——合并会掩盖某个渠道的欠款
as_of string<date-time>
请求
curl -X GET https://api.baton.example/v1/finance/balances \
  -H "Authorization: Bearer sk_live_xxx"
响应 · 200
[
  {
    "currency": "USD",
    "currency_exponent": 2,
    "available": 1842300,
    "pending": 390500,
    "reserved": 24000,
    "connector_code": "adyen",
    "as_of": "2026-11-16T09:00:00Z"
  }
]

结算批次列表

GET /v1/finance/settlements

net 以渠道结算文件为准,不是我们按费率算出来的。status=mismatched 表示我们的流水和渠道文件对不上,已挂人工。

Query 参数

connector_code string
status string
settled_from string<date-time>
settled_to string<date-time>
cursor string 上一页返回的 page.next_cursor
limit integer

响应 200

data object[]
└uid string
└connector_code string
└currency string
└currency_exponent integer
└gross integer 交易总额
└fee integer 渠道手续费(含跨境费)
└net integer 实际到账,以渠道结算文件为准
└txn_count integer
└status pending | settled | reconciled | mismatched mismatched 表示我们的流水和渠道文件对不上,已挂起人工处理
└settled_at string<date-time>
page object
└next_cursor string
└has_more boolean
请求
curl -X GET https://api.baton.example/v1/finance/settlements \
  -H "Authorization: Bearer sk_live_xxx"

结算明细

GET /v1/finance/settlements/{uid}/transactions

一个批次里的每一笔。退款、拒付、调整都在这里,记账要按这个,不要按支付单。

路径参数

uid必填 string

Query 参数

cursor string 上一页返回的 page.next_cursor
limit integer

响应 200

data object[]
└payment_uid string
└refund_uid string
└type payment | refund | chargeback | fee | adjustment
└gross integer
└fee integer
└net integer
└provider_txn_id string
└occurred_at string<date-time>
page object
└next_cursor string
└has_more boolean
请求
curl -X GET https://api.baton.example/v1/finance/settlements/{uid}/transactions \
  -H "Authorization: Bearer sk_live_xxx"

创建导出任务

POST /v1/finance/exports

大批量取数走这里,不要用列表接口深翻页——在交易表上翻到第一万页会拖垮库, 我们会在 cursor 过深时直接拒掉。

任务完成后推 settlement.ready 之外的通用完成事件,或你自己轮询。

请求头

Idempotency-Key必填 string 商户生成的唯一串(建议 UUID/ULID)。24 小时内重放同一 key 返回首次结果,不会产生第二笔。

请求体

type必填 payments | refunds | settlements | disputes
format csv | jsonl
created_from必填 string<date-time>
created_to必填 string<date-time> 单次最多跨 31 天

响应 202

uid string
type payments | refunds | settlements | disputes
status queued | running | ready | failed | expired
format csv | jsonl
row_count integer
download_url string 仅 ready 时返回,签名链接 15 分钟有效,不要存进你的库
expires_at string<date-time>
created_at string<date-time>

错误

400参数不合法
请求
curl -X POST https://api.baton.example/v1/finance/exports \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..." \
  -H "Content-Type: application/json" \
  -d '{
  "type": "payments",
  "format": "csv",
  "created_from": "2026-11-01T00:00:00Z",
  "created_to": "2026-11-30T23:59:59Z"
}'

查询导出任务

GET /v1/finance/exports/{uid}

status=ready 时返回 download_url,签名链接 15 分钟有效。不要把它存进你的库,过期就失效了,重新查即可。

路径参数

uid必填 string

响应 200

uid string
type payments | refunds | settlements | disputes
status queued | running | ready | failed | expired
format csv | jsonl
row_count integer
download_url string 仅 ready 时返回,签名链接 15 分钟有效,不要存进你的库
expires_at string<date-time>
created_at string<date-time>

错误

404对象不存在,或属于另一个环境 / 另一个商户
请求
curl -X GET https://api.baton.example/v1/finance/exports/{uid} \
  -H "Authorization: Bearer sk_live_xxx"