> This page is for BaaS.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.api.corpx.com/_mcp/server.

# Disputas — Mecanismo Especial de Devolução (MED)

O MED é o processo pelo qual o pagador de um PIX pede a devolução do valor,
normalmente por suspeita de fraude. Quando uma disputa é aberta contra uma
conta sua, você recebe um webhook, tem **48 horas** para apresentar a defesa
do correntista, e a CorpX conduz a análise e responde ao arranjo dentro do
prazo regulamentar.

Três coisas definem como este módulo funciona, e vale saber delas antes de
integrar:

* **Quem decide é a análise da CorpX, dentro das regras do arranjo.** Não
  existe rota para devolver o PIX, liberar saldo ou recusar a devolução. O que
  você faz aqui é registrar a versão do correntista, com texto e anexos, e
  responder a pedidos de esclarecimento.
* **A API mostra o status da análise, não o do liquidante.** `reviewStatus`
  diz em que etapa a disputa está do lado da CorpX e o que você pode fazer
  nela. O status que o liquidante comunica continua chegando pelo webhook
  `pix.med.updated`, como sempre.
* **O valor fica retido enquanto a disputa corre.** Ao receber a disputa, a
  CorpX retém o valor na conta até o saldo disponível; `lockStatus` e
  `lockedAmount` mostram isso. Se a devolução não acontecer, o valor é
  liberado; se acontecer, sai desse saldo retido.

## As etapas de uma MED

```mermaid
flowchart TD
    A["Disputa aberta pelo banco do pagador<br />Webhook <code>pix.med.opened</code><br />Valor retido na conta"] --> B["<code>awaiting_defense</code><br />Correntista defende: texto + anexos<br /><b>48 h</b> a partir da abertura"]
    B -- "POST .../answer" --> C["<code>pending_review</code><br />CorpX analisa<br /><b>até 7 dias da abertura</b>"]
    B -- "Prazo vence sem resposta" --> C
    C -- "Precisa de mais informação" --> D["<code>info_requested</code><br />Correntista responde: mensagem + anexos<br /><b>24 h</b>, nunca além do prazo da análise"]
    D -- "POST .../submit" --> C
    C -- "Defesa acolhida" --> E["<code>refused</code><br />Devolução recusada<br />Valor liberado na conta"]
    C -- "Devolução devida" --> F["<code>in_execution</code><br />Conta bloqueada, PIX devolvido<br /><b>até 96 h após a decisão</b>"]
    F -- "Saldo cobriu tudo" --> G["<code>refunded</code><br />Conta liberada"]
    F -- "Saldo não cobriu" --> H["<code>awaiting_funds</code><br />Restante retido; devolve conforme entrar saldo"]
    H --> F
    H -- "Encerrada com devolução parcial" --> G
```

| Etapa            | `reviewStatus`          | Quem age              | Prazo                                                                      |
| ---------------- | ----------------------- | --------------------- | -------------------------------------------------------------------------- |
| Defesa           | `awaiting_defense`      | Correntista, via você | **48 h** da abertura (`clientAnswerDeadline`)                              |
| Análise          | `pending_review`        | CorpX                 | Até **7 dias** da abertura, prazo do arranjo                               |
| Esclarecimento   | `info_requested`        | Correntista, via você | **24 h** do pedido (`infoDueAt`), limitado ao prazo da análise             |
| Execução         | `in_execution`          | CorpX                 | Devolução em até **96 h** após a decisão                                   |
| Aguardando saldo | `awaiting_funds`        | CorpX                 | Enquanto houver valor a devolver; novas devoluções conforme o saldo entrar |
| Encerrada        | `refunded` ou `refused` | —                     | —                                                                          |

**Nada é rejeitado automaticamente pelo tempo.** Vencer o prazo da defesa não
encerra a disputa nem gera devolução por si: a análise segue, sem a versão do
correntista. Monitore `clientAnswerDeadline` e `infoDueAt` — ou o painel, que
avisa quando falta menos de 12 horas.

## MED aberta pela CorpX (`direction`)

A lista traz dois tipos de disputa, separados por `direction`:

* `received` — aberta contra a conta pelo banco do pagador. Segue o fluxo acima.
* `opened` — aberta pela CorpX em nome do correntista, porque o PIX contestado
  saiu desta conta. Não há defesa nem prazo (`clientAnswerDeadline` nulo), não
  há retenção de saldo, e a análise fica em `awaiting_result` até o banco
  liquidante decidir. `answer`, `messages`, `submit` e os anexos respondem
  `409 med_opened_by_us`.

Num PIX entre duas contas da CorpX, a disputa na conta que recebeu o valor é
`received`, com defesa e retenção como qualquer outra.

`partnerStatus` (`OPEN`, `PENDING_DECISION`, `ACCEPTED`, `REJECTED`,
`CANCELED`) é a situação no banco liquidante pelo último webhook, e
`lastUpdatedAt` diz quando ela chegou. Na MED `opened`, é o que mostra o
andamento.

## Status da análise

| `reviewStatus`     | Significado                                                                       | O que você pode fazer                       |
| ------------------ | --------------------------------------------------------------------------------- | ------------------------------------------- |
| `awaiting_defense` | Disputa aberta, aguardando a defesa do correntista.                               | Anexar evidências e responder (`answer`).   |
| `pending_review`   | Defesa recebida (ou prazo vencido); a CorpX analisa.                              | Acompanhar.                                 |
| `info_requested`   | A CorpX pediu esclarecimento; a pergunta está em `infoRequest.message`.           | Enviar mensagens e anexos, depois `submit`. |
| `in_execution`     | Devolução decidida; a CorpX bloqueia a conta, devolve o PIX e libera a conta.     | Acompanhar pelo webhook.                    |
| `awaiting_funds`   | O saldo não cobriu o valor; o restante fica retido e é devolvido conforme entrar. | Acompanhar.                                 |
| `refunded`         | Devolução concluída. `refundPartial` indica se foi parcial.                       | —                                           |
| `refused`          | Devolução recusada; valor liberado na conta.                                      | —                                           |
| `awaiting_result`  | Só em `direction: opened`: a CorpX abriu a disputa e aguarda o banco liquidante.  | Acompanhar `partnerStatus`.                 |

| `lockStatus` | Significado                                               |
| ------------ | --------------------------------------------------------- |
| `pending`    | Retenção ainda não efetivada.                             |
| `locked`     | Valor retido; `lockedAmount` diz quanto.                  |
| `failed`     | A retenção não foi possível no momento; a CorpX reavalia. |
| `unlocked`   | Valor liberado.                                           |
| ausente      | Disputa anterior à retenção automática.                   |

Enquanto a conta estiver bloqueada pela execução (`in_execution`), as
operações financeiras dela respondem `403 account_blocked`. A devolução do PIX
em disputa é feita pela CorpX e não passa por esse bloqueio.

## Recebendo disputas por webhook

Três eventos. Assine os três.

| Evento                   | Quando                                                                                                                |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| `pix.med.opened`         | Abertura da disputa.                                                                                                  |
| `pix.med.updated`        | Cada mudança de status que o liquidante comunicar.                                                                    |
| `pix.med.review.updated` | Cada passo da análise da CorpX: defesa recebida, esclarecimento pedido, decisão, bloqueios, devoluções, encerramento. |

```json
{
  "id": "pix-med-opened-204cc938-da3d-4f04-baf3-0b2e6a2f1283-OPEN",
  "type": "pix.med.opened",
  "occurredAt": "2026-02-18T19:34:14.000000000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-suaempresa",
  "accountId": "773107de-...",
  "data": {
    "medId": "204cc938-da3d-4f04-baf3-0b2e6a2f1283",
    "tenantId": "tenant-suaempresa",
    "accountId": "773107de-...",
    "originalEndToEnd": "E303062942026021812490000005QLMv",
    "amount": 1000.00,
    "reasonCode": "unauthorized-transaction",
    "claimMessage": "Não reconheço esta transação",
    "openedAtIso": "2026-02-18T19:34:14.000000000Z",
    "clientAnswerDeadlineIso": "2026-02-20T19:34:14.000000000Z",
    "status": "OPEN"
  }
}
```

O `status` em `pix.med.opened` e `pix.med.updated` é o estado no liquidante
**no instante daquele evento**. Reentrega do mesmo estado não gera evento novo,
e evento atrasado é descartado — você não vê a disputa voltar no tempo.

`reasonCode` é o código do arranjo, repassado como vem
(`unauthorized-transaction`, `fraud`, `scam-or-fraud`, …). Não normalizamos
para um enum nosso.

O relato traz o **banco** do reclamante, não o nome ou documento dele. Essa
informação não é disponibilizada ao recebedor.

### `pix.med.review.updated`

```json
{
  "id": "pix-med-review-204cc938-...-info_requested-1771598551000",
  "type": "pix.med.review.updated",
  "occurredAt": "2026-02-20T14:02:31Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-suaempresa",
  "accountId": "773107de-...",
  "data": {
    "medId": "204cc938-da3d-4f04-baf3-0b2e6a2f1283",
    "accountId": "773107de-...",
    "reason": "info_requested",
    "reviewStatus": "info_requested",
    "round": null,
    "decision": null,
    "decisionMessage": null,
    "infoRequest": { "message": "Envie o comprovante de entrega com o rastreio." },
    "infoDueAt": "2026-02-21T14:02:31Z",
    "lockStatus": "locked",
    "lockedAmount": 1000.00,
    "refund": null,
    "refundedTotal": 0,
    "remaining": 1000.00,
    "refundPartial": false
  }
}
```

`data` é sempre o retrato atual da disputa; `reason` diz o que acabou de
acontecer. Você não precisa acumular eventos para saber onde ela está.

| `reason`            | O que aconteceu                                                                |
| ------------------- | ------------------------------------------------------------------------------ |
| `submitted`         | Defesa (ou esclarecimento) recebida; análise em andamento.                     |
| `info_requested`    | A CorpX pediu esclarecimento. `infoRequest.message` e `infoDueAt` preenchidos. |
| `decided`           | Decisão tomada. `decision` é `accept` ou `refuse`; `decisionMessage` explica.  |
| `balance_locked`    | Valor retido na conta.                                                         |
| `account_blocked`   | Conta bloqueada para a devolução.                                              |
| `balance_unlocked`  | Valor retido liberado.                                                         |
| `refund_sent`       | Devolução enviada; `refund.amount` e, quando houver, `refund.endToEndId`.      |
| `refund_completed`  | Devolução liquidada. `refundedTotal` e `remaining` atualizados.                |
| `refund_failed`     | A devolução não concluiu; a CorpX tenta de novo.                               |
| `remainder_locked`  | O que faltou devolver ficou retido.                                            |
| `account_unblocked` | Conta liberada.                                                                |
| `closed`            | Disputa encerrada (`refunded` ou `refused`).                                   |

## Consultando disputas

```http
GET /v1/accounts/{accountId}/pix/med?limit=50&offset=0
```

Paginada por `limit` (máximo 200) e `offset`. Não há filtro por status.

A lista traz só as disputas em que **esta conta** está: a MED é vinculada à
conta que o banco liquidante identifica no webhook, não ao CPF/CNPJ do
titular. Um titular com mais de uma conta vê cada disputa apenas na conta
do PIX contestado; consultar a MED por outra conta do mesmo titular responde
`404 med_not_found`.

```json
{
  "accountId": "773107de-...",
  "tenantId": "tenant-suaempresa",
  "items": [
    {
      "medId": "204cc938-da3d-4f04-baf3-0b2e6a2f1283",
      "accountId": "773107de-...",
      "tenantId": "tenant-suaempresa",
      "endToEndId": "E303062942026021812490000005QLMv",
      "transactionId": "tx-8f2c...",
      "amount": 1000.00,
      "reasonCode": "unauthorized-transaction",
      "claimMessage": "Não reconheço esta transação",
      "claimantBank": "Banco do reclamante",
      "openedAt": "2026-02-18T19:34:14Z",
      "clientAnswerDeadline": "2026-02-20T19:34:14Z",
      "answered": false,
      "reviewStatus": "awaiting_defense",
      "infoDueAt": null,
      "lockStatus": "locked",
      "lockedAmount": 1000.00,
      "refundedTotal": 0,
      "remaining": 1000.00,
      "refundPartial": false,
      "updatedAt": "2026-02-18T19:34:16Z"
    }
  ],
  "count": 1,
  "limit": 50,
  "offset": 0
}
```

`transactionId` liga a disputa ao lançamento do PIX no seu extrato, quando ele
existe na plataforma. Depois de responder, `answered` fica `true` e aparecem
`answeredAt`, `answerResult` e `answer` (a justificativa que você enviou).

### Detalhe de uma disputa

```http
GET /v1/accounts/{accountId}/pix/med/{medId}
```

Tudo da listagem mais a linha do tempo, as mensagens trocadas, os anexos com
`downloadUrl` e o que está habilitado agora:

```json
{
  "medId": "204cc938-...",
  "reviewStatus": "info_requested",
  "infoRequest": {
    "message": "Envie o comprovante de entrega com o rastreio.",
    "requestedAt": "2026-02-20T14:02:31Z",
    "dueAt": "2026-02-21T14:02:31Z"
  },
  "canUpload": true,
  "canAnswer": false,
  "canMessage": true,
  "canSubmit": true,
  "events": [
    { "at": "2026-02-18T19:34:14Z", "kind": "opened", "reviewStatus": "awaiting_defense", "message": "Disputa aberta", "round": null, "step": null },
    { "at": "2026-02-19T14:02:31Z", "kind": "submitted", "reviewStatus": "pending_review", "message": "Defesa enviada", "round": null, "step": null },
    { "at": "2026-02-20T14:02:31Z", "kind": "info_requested", "reviewStatus": "info_requested", "message": "Esclarecimento solicitado", "round": null, "step": null }
  ],
  "messages": [
    { "messageId": "medmsg_01...", "authorKind": "staff", "body": "Envie o comprovante de entrega com o rastreio.", "createdAt": "2026-02-20T14:02:31Z", "evidenceIds": [] }
  ],
  "evidences": [
    { "evidenceId": "medev_9f1c...", "filename": "comprovante-entrega.pdf", "contentType": "application/pdf", "sizeBytes": 184320, "uploadedAt": "2026-02-19T13:58:00Z", "messageId": null, "scanStatus": "APPROVED", "downloadUrl": "https://..." }
  ],
  "steps": []
}
```

`events` é a linha do tempo visível ao correntista. `steps` lista, em texto, o
que a CorpX já executou na devolução (conta bloqueada, valor devolvido, conta
liberada) — aparece a partir de `in_execution`. Os quatro `can*` dizem o que
está habilitado neste instante; use-os em vez de deduzir pelo status.

## Anexando evidências

Anexo é aceito enquanto a disputa está em `awaiting_defense` (antes do
`answer`) ou em `info_requested`. Fora disso a rota responde `409
med_not_writable`: o pacote já seguiu.

São três passos. O arquivo vai direto do seu lado para o armazenamento, sem
passar pelo corpo da nossa API.

**1. Peça a URL de upload**

```http
POST /v1/accounts/{accountId}/pix/med/{medId}/evidence/upload-url
```

```json
{
  "filename": "comprovante-entrega.pdf",
  "contentType": "application/pdf",
  "sizeBytes": 184320
}
```

```json
{
  "medId": "204cc938-...",
  "evidenceId": "medev_9f1c...",
  "key": "med-evidences/tenant-suaempresa/204cc938-.../medev_9f1c...-comprovante-entrega.pdf",
  "uploadUrl": "https://...",
  "method": "PUT",
  "contentType": "application/pdf",
  "sizeBytes": 184320,
  "expiresIn": 900
}
```

`sizeBytes` é o tamanho **real** do arquivo, não uma estimativa: ele entra na
assinatura da URL. Declarar um número e enviar outro faz o armazenamento
recusar o `PUT`.

**2. Envie o arquivo na URL assinada**

`PUT` direto na `uploadUrl`, com o mesmo `Content-Type` e exatamente os
`sizeBytes` que você declarou. Sem cabeçalho de autenticação nosso — a
assinatura já autoriza, e um header a mais faz o armazenamento recusar.

**3. Registre o anexo**

```http
POST /v1/accounts/{accountId}/pix/med/{medId}/evidence/add
```

```json
{
  "key": "med-evidences/tenant-suaempresa/204cc938-.../medev_9f1c...-comprovante-entrega.pdf",
  "evidenceId": "medev_9f1c...",
  "filename": "comprovante-entrega.pdf",
  "contentType": "application/pdf",
  "sizeBytes": 184320,
  "messageId": "medmsg_02..."
}
```

Sem este passo o arquivo fica no armazenamento e não entra na defesa: é o
registro que liga o binário à disputa. Tipo e tamanho são conferidos de novo
aqui, com os mesmos limites e os mesmos `errorCode` da tabela abaixo — as duas
chamadas são independentes. `messageId` é opcional: em `info_requested`, liga
o anexo à mensagem que o explica.

Todo upload passa por verificação de tipo real, antivírus e sanitização antes
de ficar disponível — alguns segundos. `scanStatus` acompanha isso:
`PENDING` em processamento, `APPROVED` liberado, `REJECTED` recusado (com
`scanReason`). Arquivo recusado não segue com a defesa.

### Limites

| Limite               | Valor                                                                                |
| -------------------- | ------------------------------------------------------------------------------------ |
| Tipos aceitos        | `application/pdf`, `image/jpeg`, `image/png`, `image/webp`, `text/plain`, `text/csv` |
| Tamanho por arquivo  | 5 MB                                                                                 |
| Total por disputa    | 6 MB                                                                                 |
| Arquivos por disputa | 10                                                                                   |

| HTTP | `errorCode`              | Quando                                                 |
| ---- | ------------------------ | ------------------------------------------------------ |
| 413  | `file_too_large`         | Arquivo acima de 5 MB.                                 |
| 413  | `payload_too_large`      | O conjunto da disputa passaria de 6 MB.                |
| 422  | `unsupported_media_type` | `contentType` fora da lista.                           |
| 422  | `too_many_files`         | Décimo primeiro arquivo na mesma disputa.              |
| 409  | `med_not_writable`       | Disputa fora de `awaiting_defense` / `info_requested`. |

### Listando o que está anexado

```http
GET /v1/accounts/{accountId}/pix/med/{medId}/evidence/download
```

Devolve os anexos da disputa com `downloadUrl` assinada (curta duração) para
cada um que passou na verificação. Com `?evidenceId=` retorna apenas um. O
mesmo conteúdo vem em `evidences` no detalhe.

## Respondendo a uma disputa

```http
POST /v1/accounts/{accountId}/pix/med/{medId}/answer
```

```json
{
  "result": "DISAGREE",
  "reason": "Venda legítima: cliente cadastrado há 14 meses, produto entregue e rastreio confirmado em 19/02."
}
```

| Campo    | Obrigatório   | Descrição                                                 |
| -------- | ------------- | --------------------------------------------------------- |
| `result` | sim           | `AGREE` reconhece a fraude; `DISAGREE` contesta o relato. |
| `reason` | em `DISAGREE` | A defesa, em texto livre.                                 |

Resposta `202`:

```json
{
  "medId": "204cc938-...",
  "result": "DISAGREE",
  "answered": true,
  "answeredAt": "2026-02-19T14:02:31Z",
  "reviewStatus": "pending_review",
  "message": "defesa registrada; a disputa segue para análise"
}
```

A defesa e os anexos entram na análise e `reviewStatus` passa a
`pending_review`. Responder é registrar a versão do correntista, não encerrar
o caso: a decisão vem depois, pelo webhook.

Erros específicos desta rota:

| HTTP | `errorCode`       | Quando                                     |
| ---- | ----------------- | ------------------------------------------ |
| 400  | `invalid_payload` | `result` fora de `AGREE`/`DISAGREE`.       |
| 409  | `conflict`        | A disputa já foi respondida.               |
| 422  | `invalid_payload` | `DISAGREE` sem `reason`.                   |
| 404  | `med_not_found`   | A disputa não existe ou não é desta conta. |

## Respondendo a um pedido de esclarecimento

Em `info_requested`, a pergunta da análise está em `infoRequest.message` do
detalhe e no webhook. O correntista responde com mensagens e anexos e você
fecha o pacote com `submit`.

```http
POST /v1/accounts/{accountId}/pix/med/{medId}/messages
```

```json
{ "body": "Segue o comprovante de entrega com rastreio BR123456789BR." }
```

Resposta `201` com `messageId`. Anexos ligados à mensagem vão em
`evidence/add` com esse `messageId`. Até 2.000 caracteres por mensagem; a
rota só aceita em `info_requested` (`409 med_not_writable` fora disso).

```http
POST /v1/accounts/{accountId}/pix/med/{medId}/submit
```

Sem corpo. Devolve `202` com o detalhe e `reviewStatus: pending_review`. Se
não houve mensagem nem anexo novo desde o pedido, responde `422
med_info_missing` — enviar vazio não ajuda a análise.

## Erros do módulo

| HTTP | `errorCode`        | Quando                                                                                      |
| ---- | ------------------ | ------------------------------------------------------------------------------------------- |
| 404  | `med_not_found`    | Disputa inexistente ou de outra conta.                                                      |
| 409  | `med_not_writable` | Mensagem ou anexo fora de `awaiting_defense` / `info_requested`.                            |
| 409  | `med_opened_by_us` | MED aberta pela CorpX em nome do correntista (`direction: opened`): não há o que responder. |
| 422  | `med_info_missing` | `submit` sem mensagem nem anexo novo.                                                       |
| 403  | `account_blocked`  | Operação financeira na conta enquanto a devolução executa.                                  |

## Taxa de MED

```http
GET /v1/backoffice/tenants/{tenantId}/med-stats?days=30&accountId={accountId}
```

Devolve os contadores de prazo e a série diária da taxa:

| Campo            | Descrição                                                                                                               |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `total`          | Total de disputas registradas.                                                                                          |
| `awaitingAnswer` | Disputas ainda sem resposta sua.                                                                                        |
| `dueSoon`        | Sem resposta e com menos de 12 horas de prazo.                                                                          |
| `overdue`        | Sem resposta e com prazo vencido.                                                                                       |
| `openAmount`     | Valor somado das disputas ainda não encerradas.                                                                         |
| `nextDeadline`   | O prazo mais apertado entre as pendentes (vazio se não há pendência).                                                   |
| `stats[]`        | Série diária: `date`, `pixInCount`, `pixInAmount`, `medCount`, `medAmount`, `quantityRatePercent`, `amountRatePercent`. |

A listagem equivalente por tenant é
`GET /v1/backoffice/tenants/{tenantId}/meds`, com os filtros `accountId`,
`limit` e `offset`.

### Faixas de referência

Referência operacional, usada no painel e no acompanhamento comercial. Nenhum
erro ou bloqueio decorre automaticamente delas — ações automáticas por taxa se
configuram em [Políticas e Regras](/baas/guias/autenticacao/politicas).

| Taxa        | Situação                             |
| ----------- | ------------------------------------ |
| \< 0,4%     | Saudável                             |
| 0,4% – 1,0% | Atenção, monitorar                   |
| > 1,0%      | Elevada, ações podem ser necessárias |

## Políticas de MED

Veja [Políticas e Regras](/baas/guias/autenticacao/politicas) para:

* **Auto-block**: reter saldo automaticamente em disputa acima de um valor.
* **Taxa máxima** (seção `med`): teto de proporção MED/PIX recebido por conta, em janela móvel, que bloqueia a saída da conta. Tem um segundo teto, mais baixo, só para MEDs **críticas** — relato do reclamante com termos de golpe ou apostas, ou motivo `scam-or-fraud` do liquidante.