余额的每一笔变动明细,做每日对账最合适的口径。
GET /api/v1/balance_transactions余额接口 回答余额是多少,这个接口回答它是怎么变成这样的。手续费、退款、拒付、提现各记一行,加起来就是余额的变化。
除 通用列表参数 外:
| 参数 | 说明 |
|---|---|
type | 变动类型,见下表 |
reference_id | 触发这笔流水的订单号 / 退款号 / 拒付号 / 提现号 |
currency | 三位 ISO 4217 代码 |
| type | 含义 | 金额方向 |
|---|---|---|
payment_credit | 收单入账(订单原始金额) | + |
fee_debit | 平台收单手续费 | − |
refund_freeze | 退款受理,资金转入冻结 | − |
refund_debit | 通道确认退款,真实扣账 | − |
refund_unfreeze | 退款被拒,冻结资金退回 | + |
dispute_freeze | 拒付开案,争议金额冻结 | − |
dispute_unfreeze | 拒付胜诉或被撤销,冻结资金退回 | + |
dispute_debit | 拒付败诉,争议金额扣账 | − |
dispute_fee | 拒付处理费 | − |
payout_freeze | 发起提现,金额冻结 | − |
payout_unfreeze | 提现驳回或失败,冻结资金退回 | + |
payout_success | 提现转账完成,从冻结中扣账 | − |
payout_fee | 提现手续费 | − |
一笔成功支付会产生两行:payment_credit(订单全额)加 fee_debit(手续费),差额就是入账净额。
curl -G "https://web.kukopay.com/api/v1/balance_transactions" \
-H "X-Api-Key: kuko_live_你的密钥" \
-d limit=100 \
-d "created[gte]=2026-09-20T00:00:00Z"{
"object": "balance_transaction",
"id": "LED_8f2c4a1e-...-CRT",
"merchant_id": "mch_a1b2c3d4e5",
"type": "payment_credit",
"currency": "USD",
"amount": 2990,
"balance_before": 120000,
"balance_after": 122990,
"reference_id": "TRD_9F3A2C7E...",
"description": "收单交易入账: Pro 年度订阅 (外单号: ORD_20260921_0001)",
"mode": "live",
"created_at": "2026-09-21T08:31:12.114Z"
}balance_before / balance_after 记录的是可用余额。冻结类变动(refund_freeze、dispute_freeze、payout_freeze)会让可用余额下降、冻结余额上升;从冻结中扣账时可用余额不变,所以这两个值相等。
amount 是有符号整数,支出为负。把某段时间的所有 amount 相加,结果就等于这段时间可用余额的净变化。
curl -G "https://web.kukopay.com/api/v1/balance_transactions" \
-H "X-Api-Key: kuko_live_你的密钥" \
-d format=csv \
-d "created[gte]=2026-09-01T00:00:00Z" \
-d "created[lte]=2026-09-30T23:59:59Z" \
-o 2026-09-对账.csv