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

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.

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

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

A contestação no seu saldo #

O disponível é debitado uma vez, quando o valor é retido. O desfecho só decide para onde vai o que está retido. Para não debitar duas vezes, acompanhe o total retido assim:

O devolucao.concluida da contestação traz id (o da retenção, o mesmo do saldo.bloqueado), tipo, valor, desfecho, endToEndId do Pix contestado e idInfracao. Ele não traz natureza: identifique a contestação pelo tipo MED, pelo id da retenção ou pelo idInfracao.

Controle o retido pelo total, e não retenção por retenção: quando o mesmo Pix tem mais de uma contestação, o valor retido passa de uma para a outra sem mexer no seu disponível. O extrato mostra cada retenção como BLOQUEIO e cada volta ao disponível como DESBLOQUEIO, e GET /v2/ex/bloqueios mostra o retido de cada uma agora.

Se o pagador recebeu de volta mais do que estava retido, a diferença soma em aRecuperar do saldo e não sai do disponível sozinha.

Contestar um saque seu #

Se um saque seu foi para um golpista, por golpe, invasão de conta, coerção ou acesso fraudulento, peça a contestação dele. Quem a abre é a instituição, na instituição de onde o Pix saiu. O pedido não move dinheiro: o que voltar entra como a volta do saque, em payout.devolucao_recebida.

PUT /v2/ex/pedidos-de-med/{id}

Escopo: ex.med.write. O id é seu, de 26 a 35 letras ou algarismos.

PUT /v2/ex/pedidos-de-med/MED01J1ZK7M9QW3ERT5TY6UI8O
{
  "idEnvio": "SAQ04J1ZK7M9QW3ERT5TY6UI8O",
  "motivo": "GOLPE",
  "descricao": "Ligaram dizendo ser do banco e pediram a transferência."
}
→ 201
{
  "id": "MED01J1ZK7M9QW3ERT5TY6UI8O",
  "idEnvio": "SAQ04J1ZK7M9QW3ERT5TY6UI8O",
  "endToEndId": "E12345678202609181200000000000004",
  "motivo": "GOLPE",
  "descricao": "Ligaram dizendo ser do banco e pediram a transferência.",
  "situacao": "PEDIDO",
  "valor": "30.00",
  "valorRecuperado": "0.00",
  "prazoEm": "2026-12-07T12:00:00Z",
  "criadoEm": "2026-09-18T12:00:00Z"
}

Desacordo comercial, como o produto que não chegou ou não agradou, e a chave digitada errada não são caso de contestação, e a instituição recusa o pedido. A repetição com o mesmo corpo responde 200. Cada saque tem um pedido em andamento por vez.

GET /v2/ex/pedidos-de-med/{id} devolve um pedido, e GET /v2/ex/pedidos-de-med lista do mais novo, por página, com idEnvio, situacao, limite e cursor. Escopo: ex.med.read. Você recebe payout.med_pedido, payout.med_aberto, payout.med_recusado e payout.med_encerrado, com as chaves do pedido.

Erros #