余额、账单与限额

查询余额，通过账单对账，并查看账户的限额、手续费和指标。

GET查询余额/transactions/balance GET查询账单/transactions/statement GET查询限额和费用/transactions/limits GET查询指标/transactions/metrics

四个路由都使用作用域 STATEMENT_READ。

余额

GET /transactions/balance

{
  "total": 152030,
  "available": 150530,
  "blocked": 1500,
  "blockedBySecurity": 1500,
  "blockedByWithdraw": 0,
  "blockedByRefund": 0,
  "syncedAt": "2026-10-06T18:20:11.004Z"
}

字段	说明
`available`	可用余额：现在可用于提现、Pix 复制粘贴码付款和退款的金额。它是账单各条目的合计。
`blocked`	在账户中但不能使用的金额，例如进行中的 MED 争议的金额，或仍在处理中的提现、退款或转账的金额。`blockedBySecurity`、`blockedByWithdraw` 和 `blockedByRefund` 按原因分列这部分金额。

total 为 available + blocked。所有字段见查询余额。

提现金额加手续费（限额中的 withdraw）必须在 available 之内。即便如此，提现仍可能以 WITHDRAW_INSUFFICIENT_PROVIDER_BALANCE 被拒绝：银行当时无法支付这笔提现。

账单

GET /transactions/statement?limit=20&dateFrom=2026-10-01&trigger=PAYOUT

每一行是一笔影响可用余额的流水，而不是一整笔操作。一笔 R$ 15,00、手续费 R$ 1,05 的已支付收款记为 +1395。提现在发起请求时扣出，金额和手续费合在一起（amount + serviceFee）。

{
  "data": [
    {
      "id": "cmu9r1a2b000101s6stmt0002",
      "entryId": "cmu9r0z9y000001s6entr0002",
      "amount": -10250,
      "balanceAfter": 150530,
      "trigger": "PAYOUT",
      "description": "Reserva de saque",
      "originId": "cmu3wd7k1000201s6wdrw0001",
      "infractionProtocol": null,
      "gross": 10000,
      "fee": 250,
      "status": "SETTLED",
      "statusDetail": null,
      "statusReason": null,
      "statusAt": "2026-10-05T14:40:14.120Z",
      "payoutOperation": "WITHDRAW",
      "counterparty": { "name": null, "document": null, "pixKey": "f***@exemplo.com" },
      "postedAt": "2026-10-05T14:40:11.002Z"
    }
  ],
  "nextCursor": "cmu9r1a2b000101s6stmt0002",
  "balance": 150530
}

`trigger`	该行
`PAYMENT`	已支付的收款，已扣除手续费。
`DEPOSIT`	无收款单的入账 Pix，已扣除手续费。
`PAYMENT_REFUND`	退款：金额的扣出，或退款被拒时金额的退回。也包括银行自行发起的退款。
`PAYOUT`	提现或 Pix 复制粘贴码付款在发起请求时的扣款。
`PAYOUT_REVERSAL`	提现失败时，提现金额的退回。
`PAYOUT_REFUND_RECEIVED`	账户发出的 Pix 被退回。
`INFRACTION_BLOCK`	MED 争议已发起：金额从可用余额中扣出。
`INFRACTION_SETTLED`	争议成立：金额已退还给付款人。
`INFRACTION_RELEASED`	争议不成立：金额退回，扣除分析费。争议被取消时，全额退回。
`INTERNAL_TRANSFER`	账户间转账，两端都有。`amount` 的正负号表示哪一端。

status 是提现、退款和转账中操作的当前状态：PROCESSING（仍在处理中）、SETTLED（已完成）或 RETURNED（被拒，金额已退回）。其他条目为 null。description 记录后不再改变：已完成提现的扣款行仍显示 "Reserva de saque"。
statusDetail 在两种情况下出现。APPROVAL_REFUSED：银行未批准该提现，金额仍在可用余额之外，statusReason 带有用于展示的消息。PROVIDER_REFUND：银行在你没有请求的情况下退还给了付款人。
counterparty 是交易对方。转入时是付款人：收款中是你填写的客户，证件号完整；无收款单的 Pix 中，证件号已脱敏。转出时，pixKey 带有已脱敏的目标密钥。争议条目中为 null。
与 data 并列的 balance 是当前的可用余额。

筛选

筛选	说明
`originId`	Webhook 中的操作 id：`paymentId`、`withdrawId`、`depositId` 或 `transferId`。创建收款、提现或转账时返回的 `id` 在这里不适用。
`trigger`	一个或多个条目类型，以逗号分隔。
`dateFrom`、`dateTo`	不带时间的日期按巴西利亚时间的整天计算。
`status`	来源操作的状态。见下文。

筛选条件同时生效。路由不认识的参数会以 400 和 REQUEST_UNKNOWN_QUERY_PARAM 被拒绝。所有筛选条件见查询账单。

status 筛选看的是产生该行的操作的状态，而不是该行的 status 字段。它返回处于该状态的操作的所有行，包括退款行。转账行和争议行不在结果中。

限额

GET /transactions/limits 返回账户当前生效的限额和手续费。金额以分为单位；feePercentage 是百分比（150 = 1.5%）。

{
  "payment": { "enabled": true, "ticketMin": 100, "ticketMax": 1000000, "feeFixed": 105, "feePercentage": 0 },
  "withdraw": { "enabled": true, "ticketMin": 100, "ticketMax": 1000000, "feeFixed": 100, "feePercentage": 150 },
  "externalPayment": { "enabled": true, "ticketMin": 100, "ticketMax": 1000000, "feeFixed": 100, "feePercentage": 0 },
  "refund": { "enabled": true, "ticketMin": 100, "ticketMax": 1000000, "feeFixed": 100, "feePercentage": 0 },
  "internalTransfer": { "enabled": true, "ticketMin": 100, "ticketMax": 1000000, "feeFixed": 100, "feePercentage": 0 },
  "dailyWithdraw": { "limit": 1000000, "used": 12850 },
  "dailyInternalTransfer": { "limit": null, "used": 0 },
  "infraction": { "feeFixed": 500, "feePercentage": 0, "blocksBalance": true }
}

区块	说明
`payment`	收款。
`withdraw`	提现到密钥。最小值和最大值适用于所有 Pix 转出。
`externalPayment`	Pix 复制粘贴码付款：沿用提现的限额，手续费单独设置。
`refund`	退款和退回存款，手续费单独设置。每笔操作的最大值沿用提现的；最小值不做校验。
`internalTransfer`	账户间转账。
`dailyWithdraw`	Pix 转出的每日上限，以及今天已用的额度。
`dailyInternalTransfer`	同上，适用于账户间转账。
`infraction`	MED 争议不成立时收取的分析费，以及分析期间被争议金额是否从可用余额中扣出（`blocksBalance`）。

每项操作中，enabled 表示是否开放，ticketMin 和 ticketMax 是最小和最大金额，手续费由固定部分（feeFixed）和百分比部分（feePercentage）相加。

在每日上限中，limit: null 表示无上限，0 表示全部阻止。有上限时，used 按巴西利亚时间统计当天，包括仍在处理中的操作；无上限时为 0。

指标

GET /transactions/metrics?dateFrom=2026-09-01&dateTo=2026-09-30

不传 dateFrom 和 dateTo 时，期间为最近 30 天。

收款按创建日期计入：9 月的转化率是 9 月创建的收款中已支付的比例，即使付款发生在 10 月。
rails 中账户的每种支付方式各一项。没有指标的方式为 available: false，不带数字；期间内没有收款的 Pix 各项数字为零。
比率（conversionRate、refundRate、disputeRate）采用与 feePercentage 相同的格式，没有基数时为 null。
withdrawals 合计未失败的提现，含手续费。deposits 合计无收款单的入账 Pix。pixInflow 合计已支付的收款和存款。

所有字段见查询指标。

余额、账单与限额

余额

账单

筛选

限额

指标

本页内容