Disputes

The bank of the payer can dispute a received Pix. The disputed amount is held from your balance while the dispute runs. Without enough balance, the hold starts partial and grows with the next credits up to the disputed amount. If the Pix did not become balance, because it is already going back to the payer, nothing is held. If another dispute on the same Pix already holds its amount, nothing more is held. In these cases semBloqueio says why. You receive med.infracao.criada when it opens and med.infracao.atualizada when it changes.

List #

GET /v2/ex/infracoes

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

When the same Pix has more than one dispute, the one rejected without holding anything is a repeated notice: it does not appear in the list or in the summary, and it remains available by its idInfracao.

GET /v2/ex/infracoes/{id} returns a dispute.

The defense depends on the account. Read capacidades.med in GET /v2/ex/config: when it is false, the defense is made by the institution with the provider of the account, and you follow it here. When it is true, see the internal reference.

Summary #

GET /v2/ex/infracoes/resumo

Scope: ex.med.read. Accepts de, ate, origem and busca, like the list.

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

The valor of each group counts each Pix once, up to the amount of the Pix. The quantidade counts the disputes.

Disputes in your balance #

The available balance is debited once, when the amount is held. The outcome only decides where the held amount goes. To avoid debiting twice, track the total held like this:

The dispute's devolucao.concluida carries id (the hold's, the same as in saldo.bloqueado), tipo, valor, desfecho, endToEndId of the disputed Pix and idInfracao. It does not carry natureza: identify the dispute by tipo MED, by the hold id or by idInfracao.

Track the held amount as a total, not hold by hold: when the same Pix has more than one dispute, the held amount moves from one to the other without touching your available balance. The statement shows each hold as BLOQUEIO and each return to available as DESBLOQUEIO, and GET /v2/ex/bloqueios shows what each one holds now.

If the payer got back more than was held, the difference adds to aRecuperar in the balance and does not leave available on its own.

Dispute one of your payouts #

If one of your payouts went to a fraudster, through a scam, account takeover, coercion or fraudulent access, request its dispute. The institution opens it, at the institution the Pix left from. The request moves no money: what comes back arrives as the return of the payout, in payout.devolucao_recebida.

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

Scope: ex.med.write. The id is yours, 26 to 35 letters or digits.

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

A commercial disagreement, such as a product that did not arrive or did not please, and a mistyped key are not cases for a dispute, and the institution refuses the request. A repeat with the same body answers 200. Each payout has one request in progress at a time.

GET /v2/ex/pedidos-de-med/{id} returns one request, and GET /v2/ex/pedidos-de-med lists from the newest, by page, with idEnvio, situacao, limite and cursor. Scope: ex.med.read. You receive payout.med_pedido, payout.med_aberto, payout.med_recusado and payout.med_encerrado, with the keys of the request.

Errors #