MED (disputas Pix)
Disputas Pix abertas por pagadores: o ciclo do MED, prazos, defesa com anexos, listar, consultar e exportar pela API e os webhooks med.opened, med.defense_updated e med.closed.
Visão geral
O MED (Mecanismo Especial de Devolução) é o processo do Bacen para o pagador contestar um Pix. Quando uma disputa é aberta contra uma cobrança sua, o valor contestado fica retido no saldo bloqueado até o encerramento. Pela API você acompanha as disputas, envia a sua defesa e recebe por webhook cada mudança.
- O pagador contesta o Pix no banco dele, e o banco abre a disputa. O valor é retido e chega o
med.opened. - Você envia a defesa com texto e anexos. A MaxxiPay recebe e a envia à processadora; cada passo chega em
med.defense_updated. - Sem defesa, a processadora pode enviar uma resposta padrão em nome da sua empresa.
- O banco analisa e encerra a disputa: a favor da sua empresa, com a retenção liberada, ou a favor do pagador, com o valor devolvido. Chega o
med.closed.
Objeto MED
Todas as rotas e os webhooks devolvem a disputa no mesmo formato. Datas em ISO 8601 (UTC) e valores em centavos.
| Campo | Tipo | Descrição |
|---|---|---|
id | string | Identificador da disputa (UUID). |
endToEndId | string | E2E do Pix contestado. |
chargeId | string | null | Cobrança que recebeu o Pix. |
charge | object | null | Descrição, data do pagamento e valor da cobrança. |
amountCents | integer | Valor contestado, em centavos. |
holdCents | integer | Valor retido no saldo bloqueado: o valor contestado. 0 depois do encerramento. |
status | string | Estado da disputa (veja Estados). |
openedAt | string | Quando a MaxxiPay registrou a disputa. Pode ser depois da abertura no banco: para saber quando o banco abriu, use bankOpenedAt. |
bankOpenedAt | string | null | Quando o banco abriu a disputa. É daqui que contam o prazo do Bacen e os de defesa. null quando o processador não informou. |
deadlineAt | string | null | Prazo do Bacen para encerrar a disputa: 72 horas depois de bankOpenedAt. |
guaranteedUntil | string | null | Até quando a defesa chega antes da resposta padrão da processadora. |
hardDeadlineAt | string | null | Último momento para enviar a defesa. |
defenseWindow | string | guaranteed, late ou closed (veja Prazos). |
processorDefaultDefenseAt | string | null | Quando a processadora enviou a resposta padrão dela, se já enviou. Depois disso o MED fica em análise e a defesa não é mais aceita. |
defense | object | null | A sua defesa, quando houver (veja Enviar defesa). |
closedAt | string | null | Encerramento da disputa. |
outcome | string | null | won (a seu favor) ou lost (devolvido ao pagador). |
infractionId | string | null | Identificador da infração informado pelo banco. |
reportedBy / reportedByLabel | string | null | Quem reportou: DEBITED_PARTICIPANT (Banco do pagador) ou CREDITED_PARTICIPANT (Banco do recebedor). |
reportDetail | string | null | Relato do pagador, texto livre de até 4.000 caracteres. |
analysisDetail | string | null | Detalhes da análise, texto livre de até 4.000 caracteres. |
payer | object | null | name, documentMasked (sempre mascarado), ispb e bankName (pode vir null). |
reportDetail, analysisDetail e o texto da defesa são texto puro, com quebras de linha. Mostre como texto, nunca como HTML ou markdown.
{
"object": "med_dispute",
"id": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
"endToEndId": "E0000000020261108131700000000001",
"chargeId": "11111111-2222-4333-8444-555555555555",
"charge": {
"description": "Depósito",
"paidAt": "2026-11-08T13:17:40.000Z",
"amountCents": 1960
},
"amountCents": 1960,
"holdCents": 1960,
"status": "awaiting_defense",
"openedAt": "2026-11-08T14:02:11.000Z",
"bankOpenedAt": "2026-11-08T13:39:56.000Z",
"deadlineAt": "2026-11-11T13:39:56.000Z",
"closedAt": null,
"outcome": null,
"infractionId": "inf_000000000000000001",
"reportedBy": "DEBITED_PARTICIPANT",
"reportedByLabel": "Banco do pagador",
"reportDetail": "Cliente relata que não reconhece a transação.\nSolicita a devolução do valor.",
"analysisDetail": null,
"payer": {
"name": "Fulano de Tal",
"documentMasked": "***.000.000-**",
"ispb": "00000000",
"bankName": null
},
"guaranteedUntil": "2026-11-08T16:39:56.000Z",
"hardDeadlineAt": "2026-11-11T11:39:56.000Z",
"defenseWindow": "guaranteed",
"processorDefaultDefenseAt": null,
"defense": null
}Estados
| status | No painel | O que significa |
|---|---|---|
awaiting_defense | Aguardando defesa | A disputa foi aberta e o valor está retido. O prazo de defesa está correndo. |
under_analysis | Em análise | A defesa foi enviada e a disputa está em análise. |
released | Liberado | A disputa foi encerrada sem desfecho informado e a retenção foi liberada. |
kept | Mantido a favor | Encerrada a seu favor: o valor fica com você e a retenção volta ao saldo disponível. |
refunded_to_payer | Devolvido ao pagador | Encerrada a favor do pagador: o valor foi devolvido a ele. |
Prazos e defesa padrão
Cada disputa traz a abertura no banco, o registro na MaxxiPay e três prazos, na tela, na API e nos webhooks:
| Campo | O que é |
|---|---|
bankOpenedAt | Abertura do MED pelo banco. O prazo do Bacen e os prazos de defesa contam a partir daqui. |
openedAt | Quando a MaxxiPay registrou a disputa. Serve de referência; nenhum prazo conta a partir dela. |
guaranteedUntil | 3 horas depois da abertura. Envio garantido: uma defesa recebida até aqui é repassada à processadora. |
hardDeadlineAt | 2 horas antes do prazo do Bacen. Depois disso a defesa não é mais aceita. |
deadlineAt | Prazo do Bacen para o banco encerrar a disputa. |
Todas as datas chegam em ISO 8601, em UTC. O painel mostra no horário de Brasília. O prazo do Bacen é a abertura no banco (bankOpenedAt) mais 72 horas.
defenseWindow resume a situação agora: guaranteed até guaranteedUntil; late entre guaranteedUntil e hardDeadlineAt; closed depois de hardDeadlineAt, quando a disputa sai de awaiting_defense ou quando a processadora envia a resposta padrão.
Quando a processadora envia a resposta padrão, processorDefaultDefenseAt traz o horário, inclusive antes de guaranteedUntil. A partir daí: "A processadora já respondeu a este MED; ele está em análise pelo banco do pagador." O MED passa para under_analysis, defenseWindow vira closed e a defesa não é mais aceita: um envio responde 422 defense_window_closed. O painel mostra o passo "Resposta padrão enviada pela processadora" na linha do tempo e esse aviso no lugar do formulário, e chega um med.defense_updated.
Listar e consultar
As rotas de leitura aceitam a sessão do painel ou uma chave de API com o escopo charges:read. Veja Escopos.
Listar
GET /v1/med-disputes lista as disputas da mais recente para a mais antiga. Filtros opcionais: status, from e to (ISO 8601 com fuso, aplicados à abertura), limit de 1 a 100 (padrão 20) e cursor com o nextCursor da página anterior.
summary vale para a empresa inteira, sem os filtros: open conta as disputas abertas, retainedCents soma o que está retido e dueWithin48h conta as abertas com prazo nas próximas 48 horas.
Consultar
GET /v1/med-disputes/:id devolve uma disputa com a defesa, se houver. Depois do encerramento, holdCents vem 0 e outcome diz o desfecho.
Exportar CSV
GET /v1/med-disputes/export aceita os mesmos filtros e devolve um CSV separado por ;, com BOM, até 5.000 linhas. Colunas: data_pix, e2e, cobranca, valor, retido, prazo, status, encerrado_em, pagador, documento, banco, reportado_por, relato, analise, infracao. Cada célula tem até 2.000 caracteres; um texto maior é cortado com "…" no fim.
Dossiê em PDF
GET /v1/med-disputes/:id/dossier.pdf devolve o dossiê da disputa em PDF, sempre como download, com o nome dossie-med-<últimos 12 caracteres do endToEndId>.pdf. Ele traz os dados do MED, o relato e a análise com dados pessoais minimizados, o pagador mascarado, a defesa (texto, situação e horários), os anexos e a linha do tempo. Imagens JPG e PNG vêm dentro do PDF; anexos em PDF aparecem listados com nome, tamanho e sha256. No painel, use Baixar dossiê (PDF) no detalhe da disputa.
curl "https://api.maxxipay.com/v1/med-disputes?status=awaiting_defense&from=2026-11-01T00:00:00-03:00&limit=20" \
-H "Authorization: Bearer $MAXXIPAY_API_KEY"{
"object": "list",
"data": [
{
"object": "med_dispute",
"id": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
"endToEndId": "E0000000020261108131700000000001",
"chargeId": "11111111-2222-4333-8444-555555555555",
"charge": {
"description": "Depósito",
"paidAt": "2026-11-08T13:17:40.000Z",
"amountCents": 1960
},
"amountCents": 1960,
"holdCents": 1960,
"status": "awaiting_defense",
"openedAt": "2026-11-08T14:02:11.000Z",
"bankOpenedAt": "2026-11-08T13:39:56.000Z",
"deadlineAt": "2026-11-11T13:39:56.000Z",
"closedAt": null,
"outcome": null,
"infractionId": "inf_000000000000000001",
"reportedBy": "DEBITED_PARTICIPANT",
"reportedByLabel": "Banco do pagador",
"reportDetail": "Cliente relata que não reconhece a transação.\nSolicita a devolução do valor.",
"analysisDetail": null,
"payer": {
"name": "Fulano de Tal",
"documentMasked": "***.000.000-**",
"ispb": "00000000",
"bankName": null
},
"guaranteedUntil": "2026-11-08T16:39:56.000Z",
"hardDeadlineAt": "2026-11-11T11:39:56.000Z",
"defenseWindow": "guaranteed",
"processorDefaultDefenseAt": null,
"defense": null
}
],
"hasMore": true,
"nextCursor": "eyJ2IjoiMjAyNi0xMS0wOFQxNDowMjoxMS4wMDBaIiwiaWQiOiJhYWFhYWFhYS1iYmJiLTRjY2MtOGRkZC1lZWVlZWVlZWVlZWUifQ",
"summary": {
"open": 3,
"retainedCents": 2345678,
"dueWithin48h": 1,
"notifiedPending": 2,
"webhook": {
"configured": true,
"subscribed": true
}
}
}curl https://api.maxxipay.com/v1/med-disputes/aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee \
-H "Authorization: Bearer $MAXXIPAY_API_KEY"{
"object": "med_dispute",
"id": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
"endToEndId": "E0000000020261108131700000000001",
"chargeId": "11111111-2222-4333-8444-555555555555",
"charge": {
"description": "Depósito",
"paidAt": "2026-11-08T13:17:40.000Z",
"amountCents": 1960
},
"amountCents": 1960,
"holdCents": 0,
"status": "kept",
"openedAt": "2026-11-08T14:02:11.000Z",
"bankOpenedAt": "2026-11-08T13:39:56.000Z",
"deadlineAt": "2026-11-11T13:39:56.000Z",
"closedAt": "2026-11-10T18:00:00.000Z",
"outcome": "won",
"infractionId": "inf_000000000000000001",
"reportedBy": "DEBITED_PARTICIPANT",
"reportedByLabel": "Banco do pagador",
"reportDetail": "Cliente relata que não reconhece a transação.\nSolicita a devolução do valor.",
"analysisDetail": "Análise concluída.\nDocumentação do recebedor aceita.",
"payer": {
"name": "Fulano de Tal",
"documentMasked": "***.000.000-**",
"ispb": "00000000",
"bankName": null
},
"guaranteedUntil": "2026-11-08T16:39:56.000Z",
"hardDeadlineAt": "2026-11-11T11:39:56.000Z",
"defenseWindow": "closed",
"processorDefaultDefenseAt": null,
"defense": {
"object": "med_defense",
"id": "mdf_00000000000000000001",
"medId": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
"text": "Pedido 000123 entregue em 02/11/2026. Segue comprovante de entrega e conversa com o cliente.",
"attachments": [
{
"id": "att_00000000000000000001",
"fileName": "comprovante-entrega.pdf",
"contentType": "application/pdf",
"sizeBytes": 182304,
"sha256": "0000000000000000000000000000000000000000000000000000000000000000"
}
],
"status": "sent",
"statusLabel": "Enviada à processadora",
"notSentReason": null,
"notSentLabel": null,
"receivedAt": "2026-11-08T15:00:00.000Z",
"updatedAt": "2026-11-08T16:10:00.000Z",
"sentAt": "2026-11-08T16:10:00.000Z",
"windowAtReceipt": "guaranteed",
"notice": "Envio garantido até 08/11/2026, 13:39 (horário de Brasília). Depois disso, a processadora pode já ter enviado uma resposta padrão; ainda aceitamos a sua defesa até 11/11/2026, 08:39, mas ela pode não ser repassada."
}
}curl "https://api.maxxipay.com/v1/med-disputes/export?from=2026-11-01T00:00:00-03:00&to=2026-11-08T23:59:59-03:00" \
-H "Authorization: Bearer $MAXXIPAY_API_KEY" \
-o med-2026-11-01-a-2026-11-08.csvcurl https://api.maxxipay.com/v1/med-disputes/aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee/dossier.pdf \
-H "Authorization: Bearer $MAXXIPAY_API_KEY" \
-OJEnviar defesa
POST /v1/med-disputes/:id/defense recebe a defesa em multipart/form-data, com o campo text e até 3 campos files. Pela API, a chave precisa do escopo med:write; no painel, só responsável e administradores enviam. A conta precisa estar verificada.
| Item | Regra |
|---|---|
| Texto | Texto puro, de 11 a 255 caracteres depois de tirar os espaços das pontas. Não inclua CPF ou CNPJ; números de pedido, protocolo e rastreio ajudam. |
| Anexos | Até 3 arquivos PDF, JPG ou PNG, de até 5 MB cada. O tipo é conferido pelo conteúdo do arquivo, não pelo nome. |
| Requisição | Até 16 MB no total. |
| Quando | Só com a disputa em awaiting_defense e defenseWindow diferente de closed. |
A resposta 202 traz a defesa com status received. Enquanto ela estiver assim (ou em not_sent com a janela aberta), um novo POST substitui o texto e os anexos e mantém o id. Para manter anexos já enviados, repita o campo keepAttachmentIds com o id de cada um; o total, somando os mantidos e os novos, é de até 3. Sem esse campo, os anexos anteriores são trocados pelos novos. Um id que não é anexo atual da defesa responde 422 unknown_attachment; se a defesa mudar durante o envio, a resposta é 409 defense_in_progress e nada é apagado. DELETE /v1/med-disputes/:id/defense/attachments/:attId remove um anexo. GET /v1/med-disputes/:id/defense devolve a defesa, e GET /v1/med-disputes/:id/defense/attachments/:attId baixa um anexo.
| status | No painel | O que significa |
|---|---|---|
received | Recebida pela MaxxiPay | Ainda pode ser alterada; vamos enviá-la à processadora. |
sent | Enviada à processadora | Entregue; sentAt diz quando. Não pode mais mudar. |
not_sent | Não enviada | notSentLabel diz o motivo. Com a janela aberta, você pode enviar de novo. |
Uma defesa que já está sendo enviada responde 409 defense_in_progress, e uma já enviada, 409 defense_already_submitted. Texto ou anexos fora das regras e prazo encerrado respondem 422; veja Erros.
curl https://api.maxxipay.com/v1/med-disputes/aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee/defense \
-H "Authorization: Bearer $MAXXIPAY_API_KEY" \
-F "text=Pedido 000123 entregue em 02/11/2026. Segue comprovante de entrega e conversa com o cliente." \
-F "files=@comprovante-entrega.pdf"{
"object": "med_defense",
"id": "mdf_00000000000000000001",
"medId": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
"text": "Pedido 000123 entregue em 02/11/2026. Segue comprovante de entrega e conversa com o cliente.",
"attachments": [
{
"id": "att_00000000000000000001",
"fileName": "comprovante-entrega.pdf",
"contentType": "application/pdf",
"sizeBytes": 182304,
"sha256": "0000000000000000000000000000000000000000000000000000000000000000"
}
],
"status": "received",
"statusLabel": "Recebida pela MaxxiPay",
"notSentReason": null,
"notSentLabel": null,
"receivedAt": "2026-11-08T15:00:00.000Z",
"updatedAt": "2026-11-08T15:00:00.000Z",
"sentAt": null,
"windowAtReceipt": "guaranteed",
"notice": "Envio garantido até 08/11/2026, 13:39 (horário de Brasília). Depois disso, a processadora pode já ter enviado uma resposta padrão; ainda aceitamos a sua defesa até 11/11/2026, 08:39, mas ela pode não ser repassada."
}{
"error": {
"code": "defense_already_submitted",
"message": "A defesa já foi enviada à processadora."
}
}{
"error": {
"code": "defense_contains_document",
"message": "Não inclua CPF ou CNPJ na defesa.",
"field": "text"
}
}curl -X DELETE https://api.maxxipay.com/v1/med-disputes/aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee/defense/attachments/att_00000000000000000001 \
-H "Authorization: Bearer $MAXXIPAY_API_KEY"Webhooks
| Evento | Quando chega | id |
|---|---|---|
med.opened | Uma disputa é aberta. | med.opened:<id do MED> |
med.defense_updated | A defesa é recebida (a cada envio ou alteração), enviada à processadora ou não enviada. | med.defense_updated:<id da defesa>:<n> |
med.defense_updated | A processadora enviou a resposta padrão. defenseId, status e statusLabel vêm nulos se você ainda não enviou defesa. | med.defense_updated:<id do MED>:processor_default |
med.closed | A disputa é encerrada. Traz closedAt, outcome e releasedHoldCents. | med.closed:<id do MED> |
Os eventos usam o mesmo envelope dos outros e só chegam aos endpoints que os marcarem em Desenvolvedor, Webhooks, no grupo Disputas (MED). Veja Webhooks.
Use o id para descartar repetições. A ordem de entrega não é garantida: confie no status e nas datas do payload.
{
"id": "med.opened:aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
"type": "med.opened",
"createdAt": "2026-11-08T14:02:11.000Z",
"data": {
"object": "med_dispute",
"id": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
"endToEndId": "E0000000020261108131700000000001",
"chargeId": "11111111-2222-4333-8444-555555555555",
"amountCents": 1960,
"holdCents": 1960,
"status": "awaiting_defense",
"deadlineAt": "2026-11-11T13:39:56.000Z",
"openedAt": "2026-11-08T14:02:11.000Z",
"bankOpenedAt": "2026-11-08T13:39:56.000Z",
"infractionId": "inf_000000000000000001",
"reportedBy": "DEBITED_PARTICIPANT",
"reportedByLabel": "Banco do pagador",
"reportDetail": "Cliente relata que não reconhece a transação.\nSolicita a devolução do valor.",
"analysisDetail": null,
"payer": {
"name": "Fulano de Tal",
"documentMasked": "***.000.000-**",
"ispb": "00000000",
"bankName": null
},
"guaranteedUntil": "2026-11-08T16:39:56.000Z",
"hardDeadlineAt": "2026-11-11T11:39:56.000Z",
"defenseWindow": "guaranteed",
"processorDefaultDefenseAt": null
}
}{
"id": "med.defense_updated:mdf_00000000000000000001:2",
"type": "med.defense_updated",
"createdAt": "2026-11-08T16:10:00.000Z",
"data": {
"object": "med_defense_update",
"medId": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
"defenseId": "mdf_00000000000000000001",
"status": "sent",
"statusLabel": "Enviada à processadora",
"sentAt": "2026-11-08T16:10:00.000Z",
"notSentReason": null,
"notSentLabel": null,
"processorDefaultDefenseAt": null
}
}{
"id": "med.defense_updated:aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee:processor_default",
"type": "med.defense_updated",
"createdAt": "2026-11-08T17:30:00.000Z",
"data": {
"object": "med_defense_update",
"medId": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
"defenseId": null,
"status": null,
"statusLabel": null,
"sentAt": null,
"notSentReason": null,
"notSentLabel": null,
"processorDefaultDefenseAt": "2026-11-08T17:30:00.000Z"
}
}{
"id": "med.closed:aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
"type": "med.closed",
"createdAt": "2026-11-10T18:00:00.000Z",
"data": {
"object": "med_dispute",
"id": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
"endToEndId": "E0000000020261108131700000000001",
"chargeId": "11111111-2222-4333-8444-555555555555",
"amountCents": 1960,
"holdCents": 0,
"status": "kept",
"deadlineAt": "2026-11-11T13:39:56.000Z",
"openedAt": "2026-11-08T14:02:11.000Z",
"bankOpenedAt": "2026-11-08T13:39:56.000Z",
"infractionId": "inf_000000000000000001",
"reportedBy": "DEBITED_PARTICIPANT",
"reportedByLabel": "Banco do pagador",
"reportDetail": "Cliente relata que não reconhece a transação.\nSolicita a devolução do valor.",
"analysisDetail": null,
"payer": {
"name": "Fulano de Tal",
"documentMasked": "***.000.000-**",
"ispb": "00000000",
"bankName": null
},
"guaranteedUntil": "2026-11-08T16:39:56.000Z",
"hardDeadlineAt": "2026-11-11T11:39:56.000Z",
"defenseWindow": "closed",
"processorDefaultDefenseAt": null,
"closedAt": "2026-11-10T18:00:00.000Z",
"outcome": "won",
"releasedHoldCents": 1960
}
}Sincronizar eventos
Uma disputa que abre ou fecha sem nenhum endpoint assinando fica pendente. summary.notifiedPending conta essas disputas, e summary.webhook diz se há endpoint ativo (configured) e se algum assina os eventos de MED (subscribed). A página MED do painel mostra o botão Enviar por webhook para o responsável e administradores.
O botão chama POST /v1/med-disputes/sync, que só aceita a sessão do painel. Cada chamada envia até 200 eventos, do MED mais antigo ao mais novo, com o med.opened antes do med.closed da mesma disputa; remaining diz quantos ainda faltam.
O envio é idempotente: um evento já enviado não se repete e conta em skippedExisting. Há um envio por minuto por empresa. Com endpoint ativo que não assina MED, nada é enviado e reason vem not_subscribed.
{
"object": "med_sync",
"requested": 200,
"enqueued": 198,
"skippedExisting": 2,
"remaining": 14,
"reason": null,
"endpoints": [
{
"id": "we_00000000000000000001",
"url": "https://hooks.loja-exemplo.com.br/maxxipay?token=••••••••",
"subscribed": true
}
]
}Erros
Os erros vêm no formato padrão, com error.code e error.message. Veja Erros.
| HTTP | code | Quando |
|---|---|---|
| 403 | forbidden | A chave não tem o escopo da rota. |
| 403 | account_not_verified | A conta ainda não foi verificada (envio e remoção na defesa). |
| 403 | api_key_not_allowed | A rota só aceita a sessão do painel (sincronizar). |
| 404 | not_found | A disputa ou a defesa não existe ou é de outra empresa. |
| 409 | defense_in_progress | A defesa está sendo enviada à processadora e não pode mais mudar. |
| 409 | defense_already_submitted | A defesa já foi enviada à processadora. |
| 413 | payload_too_large | A requisição passa de 16 MB. |
| 422 | invalid_text | O texto não tem de 11 a 255 caracteres. |
| 422 | defense_contains_document | O texto tem um CPF ou CNPJ válido. |
| 422 | invalid_file | Um anexo não é PDF, JPG ou PNG. |
| 422 | file_too_large | Um anexo passa de 5 MB. |
| 422 | too_many_files | Mais de 3 anexos. |
| 422 | unknown_attachment | Um id em keepAttachmentIds não é anexo atual da defesa. |
| 422 | defense_window_closed | A disputa não aceita mais defesa. |
| 422 | webhook_not_configured | Não há endpoint de webhook ativo (sincronizar). |
| 429 | rate_limited | Limite de chamadas; espere o tempo do header retry-after. |
Boas práticas
- Assine o grupo Disputas (MED) num endpoint e trate os eventos pelo
id, sem depender da ordem. - Envie a defesa antes de
guaranteedUntil. Depois disso a processadora pode já ter enviado a resposta padrão, e aí a defesa não é mais aceita. - Seja objetivo: diga o que foi vendido ou entregue e anexe nota, comprovante de entrega ou conversa com o cliente.
- Não coloque CPF, CNPJ ou dados de cartão no texto ou nos anexos.
- Mostre relato, análise e defesa como texto puro.
- Concilie pelo extrato: a retenção e a liberação aparecem como "Retenção de MED" e "Liberação de MED" com o E2E.