Contestações

O banco do pagador pode contestar um Pix recebido. O valor contestado fica retido do seu saldo enquanto a contestação corre. Sem saldo suficiente, a retenção começa parcial e cresce com os próximos créditos até o valor contestado. Se o Pix não virou saldo, porque já está voltando ao pagador, nada é retido. Se outra contestação do mesmo Pix já segura o valor dele, nada mais é retido. Nesses casos semBloqueio diz o motivo. Você recebe med.infracao.criada quando ela abre e med.infracao.atualizada quando ela muda.

Listar #

GET /v2/ex/infracoes

Escopo: 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"
    }
  ]
}

Parâmetro	Tipo	Descrição
`situacao`	string	Filtra por `ABERTA`, `EM_DEFESA`, `ACATADA` ou `REJEITADA`. Aceita várias, separadas por vírgula.
`limite`, `cursor`	inteiro, string	Com um dos dois, a lista vem por página, da mais recente para a mais antiga, com `cursor`. Sem eles, vem inteira, as abertas primeiro.
`de`, `ate`	string	Datas `AAAA-MM-DD`, inclusivas, pela abertura da contestação no horário de Brasília. Uma das duas sozinha também vale.
`origem`	string	`PIX` ou `CARTAO`.
`busca`	string	O `endToEndId`, a referência da venda ou o `idInfracao`, exato.

Quando o mesmo Pix tem mais de uma contestação, a que foi rejeitada sem reter nada é um aviso repetido: ela não aparece na lista nem no resumo, e continua na consulta pelo idInfracao.

GET /v2/ex/infracoes/{id} devolve uma contestação.

Campo	Tipo	Descrição
`situacao`	string	`ABERTA`, `EM_DEFESA`, `ACATADA` quando o pagador ganhou e o valor volta a ele, `REJEITADA` quando você ganhou e o valor volta ao seu disponível.
`valor`	string	O valor contestado.
`bloqueioId`	string	A retenção correspondente, em `GET /v2/ex/bloqueios`. Não vem quando nada é retido.
`semBloqueio`	string	Por que a retenção não houve ou é parcial. Só vem nesses casos.
`valorADescoberto`	string	Só aparece quando a retenção não cobriu o valor contestado: a diferença, que você passa a nos dever e que soma em `aRecuperar` do saldo.
`prazoFinalizacao`	string	Prazo da contestação. Quando `capacidades.med` é `false`, o desfecho pode chegar depois dele, em `med.infracao.atualizada`.

A defesa depende da conta. Leia capacidades.med em GET /v2/ex/config: quando é false, a defesa é feita pela instituição junto ao provedor da conta, e você acompanha por aqui. Quando é true, consulte a referência interna.

Resumo #

GET /v2/ex/infracoes/resumo

Escopo: ex.med.read. Aceita de, ate, origem e busca, como a lista.

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"
}

Campo	Tipo	Descrição
`abertas`	objeto	As contestações em `ABERTA` ou `EM_DEFESA`: `quantidade` e `valor` contestado.
`acatadas`	objeto	As que voltaram ao pagador.
`rejeitadas`	objeto	As que voltaram ao seu disponível.
`total`	objeto	Todas do recorte.
`retidoAgora`	string	O que está retido por contestação agora, fora do recorte.

O valor de cada grupo conta cada Pix uma vez, até o valor do Pix. A quantidade conta as contestações.

Erros #

Status	`title`	Quando
400	`situacao_invalida`	Filtro de situação fora da lista.
400	`limite_invalido`	`limite` fora de 1 a 200.
400	`cursor_invalido`	Cursor malformado.
400	`periodo_invalido`	`de` ou `ate` fora de `AAAA-MM-DD`, ou `de` depois de `ate`.
400	`filtro_invalido`	`origem` fora de `PIX` e `CARTAO`.
404	`nao_encontrado`	A contestação não existe nesta conta.