● 余额与对账 · /v1 余额与对账
余额、结算批次、明细导出。给你的 ERP 和财务系统自动拉数用,不用人去后台点。
按渠道账户分开返回,不合并。合并会掩盖某个渠道的欠款——那是对账时最先出事的地方。
available 可结算、pending 已扣款未到结算周期、reserved 争议冻结与保证金。
Query 参数
响应 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
一个批次里的每一笔。退款、拒付、调整都在这里,记账要按这个,不要按支付单。
路径参数
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" 大批量取数走这里,不要用列表接口深翻页——在交易表上翻到第一万页会拖垮库,
我们会在 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> | |
错误
请求
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 分钟有效。不要把它存进你的库,过期就失效了,重新查即可。
路径参数
响应 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"