争议

付款人的银行可以对收到的 Pix 提出争议。争议进行期间，争议金额会从您的余额中冻结。余额不足时，冻结先部分进行，并随后续入账逐步增加，直到达到争议金额。如果该 Pix 没有计入余额（因为它已在退还付款人的途中），则不冻结任何金额。如果同一笔 Pix 的另一项争议已经冻结了其金额，则不再额外冻结。这些情况下，semBloqueio 都会说明原因。争议开启时您会收到 med.infracao.criada，发生变化时会收到 med.infracao.atualizada。

列出 #

GET /v2/ex/infracoes

权限范围：ex.med.read。

GET /v2/ex/infracoes
→ 200
{
  "infracoes": [
    {
      "idInfracao": "01J1ZK7M9QW3ERT5TY6UI8OPQR",
      "endToEndId": "E12345678202609181200000000000001",
      "tipo": "FRAUDE",
      "valor": "100.00",
      "situacao": "ABERTA",
      "relato": "pagador alega nao reconhecer o pagamento",
      "prazoFinalizacao": "2026-09-25T12:00:00Z",
      "bloqueioId": "med:01J1ZK7M9QW3ERT5TY6UI8OPQR",
      "criadoEm": "2026-09-18T12:00:00Z"
    }
  ]
}

参数	类型	说明
`situacao`	字符串	按 `ABERTA`、`EM_DEFESA`、`ACATADA` 或 `REJEITADA` 过滤。可以传多个，用逗号分隔。
`limite`、`cursor`	整数、字符串	传入其中任意一个时，列表按页返回，从新到旧，并带有 `cursor`。两个都不传时，一次返回完整列表，未结的排在前面。
`de`、`ate`	字符串	`AAAA-MM-DD` 格式的日期，包含首尾，按争议在巴西利亚时间的开启时间计算。也可以只传其中一个。
`origem`	字符串	`PIX` 或 `CARTAO`。
`busca`	字符串	`endToEndId`、销售参考号或 `idInfracao`，精确匹配。

同一笔 Pix 有多个争议时，被驳回且未冻结任何金额的那一个是重复通知：它不出现在列表和汇总中，但仍可通过 idInfracao 查询。

GET /v2/ex/infracoes/{id} 返回单个争议。

字段	类型	说明
`situacao`	字符串	`ABERTA`、`EM_DEFESA`；`ACATADA` 表示付款人一方胜出，金额退还给付款人；`REJEITADA` 表示您一方胜出，金额回到您的可用余额。
`valor`	字符串	争议金额。
`bloqueioId`	字符串	对应的冻结，可在 `GET /v2/ex/bloqueios` 中查看。没有冻结任何金额时不返回。
`semBloqueio`	字符串	没有冻结或仅部分冻结的原因。仅在这些情况下返回。
`valorADescoberto`	字符串	仅当冻结金额不足以覆盖争议金额时出现：即差额，您因此欠我们这笔款项，它会计入余额中的 `aRecuperar`。
`prazoFinalizacao`	字符串	争议的期限。`capacidades.med` 为 `false` 时，结果可能在期限之后才通过 `med.infracao.atualizada` 送达。

申辩方式取决于账户。请读取 GET /v2/ex/config 中的 capacidades.med：为 false 时，由机构向账户的服务提供方提出申辩，您在这里跟进；为 true 时，请参阅内部参考文档。

汇总 #

GET /v2/ex/infracoes/resumo

权限范围：ex.med.read。与列表一样接受 de、ate、origem 和 busca。

GET /v2/ex/infracoes/resumo?de=2026-10-01&ate=2026-10-15
→ 200
{
  "abertas": { "quantidade": 3, "valor": "45.00" },
  "acatadas": { "quantidade": 1, "valor": "20.00" },
  "rejeitadas": { "quantidade": 2, "valor": "30.00" },
  "total": { "quantidade": 6, "valor": "95.00" },
  "retidoAgora": "45.00"
}

字段	类型	说明
`abertas`	对象	处于 `ABERTA` 或 `EM_DEFESA` 的争议：`quantidade` 和争议金额 `valor`。
`acatadas`	对象	金额退还给付款人的争议。
`rejeitadas`	对象	金额回到您可用余额的争议。
`total`	对象	所选范围内的全部争议。
`retidoAgora`	字符串	当前因争议被冻结的金额，不受所选范围影响。

每组的 valor 对每笔 Pix 只计算一次，最多为该 Pix 的金额。quantidade 统计争议的数量。

错误 #

状态码	`title`	触发条件
400	`situacao_invalida`	状态过滤值不在列表中。
400	`limite_invalido`	`limite` 不在 1 到 200 之间。
400	`cursor_invalido`	游标格式错误。
400	`periodo_invalido`	`de` 或 `ate` 不是 `AAAA-MM-DD` 格式，或 `de` 晚于 `ate`。
400	`filtro_invalido`	`origem` 不是 `PIX` 或 `CARTAO`。
404	`nao_encontrado`	该争议在此账户中不存在。