Ir para o conteúdo
Docs

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.

  1. O pagador contesta o Pix no banco dele, e o banco abre a disputa. O valor é retido e chega o med.opened.
  2. Você envia a defesa com texto e anexos. A MaxxiPay recebe e a envia à processadora; cada passo chega em med.defense_updated.
  3. Sem defesa, a processadora pode enviar uma resposta padrão em nome da sua empresa.
  4. 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.

CampoTipoDescrição
idstringIdentificador da disputa (UUID).
endToEndIdstringE2E do Pix contestado.
chargeIdstring | nullCobrança que recebeu o Pix.
chargeobject | nullDescrição, data do pagamento e valor da cobrança.
amountCentsintegerValor contestado, em centavos.
holdCentsintegerValor retido no saldo bloqueado: o valor contestado. 0 depois do encerramento.
statusstringEstado da disputa (veja Estados).
openedAtstringQuando a MaxxiPay registrou a disputa. Pode ser depois da abertura no banco: para saber quando o banco abriu, use bankOpenedAt.
bankOpenedAtstring | nullQuando o banco abriu a disputa. É daqui que contam o prazo do Bacen e os de defesa. null quando o processador não informou.
deadlineAtstring | nullPrazo do Bacen para encerrar a disputa: 72 horas depois de bankOpenedAt.
guaranteedUntilstring | nullAté quando a defesa chega antes da resposta padrão da processadora.
hardDeadlineAtstring | nullÚltimo momento para enviar a defesa.
defenseWindowstringguaranteed, late ou closed (veja Prazos).
processorDefaultDefenseAtstring | nullQuando 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.
defenseobject | nullA sua defesa, quando houver (veja Enviar defesa).
closedAtstring | nullEncerramento da disputa.
outcomestring | nullwon (a seu favor) ou lost (devolvido ao pagador).
infractionIdstring | nullIdentificador da infração informado pelo banco.
reportedBy / reportedByLabelstring | nullQuem reportou: DEBITED_PARTICIPANT (Banco do pagador) ou CREDITED_PARTICIPANT (Banco do recebedor).
reportDetailstring | nullRelato do pagador, texto livre de até 4.000 caracteres.
analysisDetailstring | nullDetalhes da análise, texto livre de até 4.000 caracteres.
payerobject | nullname, 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.

Disputa aguardando defesaJSON
{
  "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

statusNo painelO que significa
awaiting_defenseAguardando defesaA disputa foi aberta e o valor está retido. O prazo de defesa está correndo.
under_analysisEm análiseA defesa foi enviada e a disputa está em análise.
releasedLiberadoA disputa foi encerrada sem desfecho informado e a retenção foi liberada.
keptMantido a favorEncerrada a seu favor: o valor fica com você e a retenção volta ao saldo disponível.
refunded_to_payerDevolvido ao pagadorEncerrada 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:

CampoO que é
bankOpenedAtAbertura do MED pelo banco. O prazo do Bacen e os prazos de defesa contam a partir daqui.
openedAtQuando a MaxxiPay registrou a disputa. Serve de referência; nenhum prazo conta a partir dela.
guaranteedUntil3 horas depois da abertura. Envio garantido: uma defesa recebida até aqui é repassada à processadora.
hardDeadlineAt2 horas antes do prazo do Bacen. Depois disso a defesa não é mais aceita.
deadlineAtPrazo 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.

ListarcURL
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"
RespostaJSON200 OK
{
  "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
    }
  }
}
ConsultarcURL
curl https://api.maxxipay.com/v1/med-disputes/aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee \
  -H "Authorization: Bearer $MAXXIPAY_API_KEY"
Encerrada a seu favorJSON200 OK
{
  "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."
  }
}
Exportar CSVcURL
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.csv
Baixar o dossiêcURL
curl https://api.maxxipay.com/v1/med-disputes/aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee/dossier.pdf \
  -H "Authorization: Bearer $MAXXIPAY_API_KEY" \
  -OJ

Enviar 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.

ItemRegra
TextoTexto 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.
AnexosAté 3 arquivos PDF, JPG ou PNG, de até 5 MB cada. O tipo é conferido pelo conteúdo do arquivo, não pelo nome.
RequisiçãoAté 16 MB no total.
QuandoSó 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.

statusNo painelO que significa
receivedRecebida pela MaxxiPayAinda pode ser alterada; vamos enviá-la à processadora.
sentEnviada à processadoraEntregue; sentAt diz quando. Não pode mais mudar.
not_sentNão enviadanotSentLabel 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.

Enviar defesacURL
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"
RespostaJSON202 Accepted
{
  "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."
}
Já enviadaJSON409 Conflict
{
  "error": {
    "code": "defense_already_submitted",
    "message": "A defesa já foi enviada à processadora."
  }
}
Com CPF no textoJSON422 Unprocessable Entity
{
  "error": {
    "code": "defense_contains_document",
    "message": "Não inclua CPF ou CNPJ na defesa.",
    "field": "text"
  }
}
Remover anexocURL
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

EventoQuando chegaid
med.openedUma disputa é aberta.med.opened:<id do MED>
med.defense_updatedA defesa é recebida (a cada envio ou alteração), enviada à processadora ou não enviada.med.defense_updated:<id da defesa>:<n>
med.defense_updatedA 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.closedA 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.

med.openedJSON
{
  "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
  }
}
med.defense_updatedJSON
{
  "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
  }
}
med.defense_updated (resposta padrão)JSON
{
  "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"
  }
}
med.closedJSON
{
  "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.

RespostaJSON200 OK
{
  "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.

HTTPcodeQuando
403forbiddenA chave não tem o escopo da rota.
403account_not_verifiedA conta ainda não foi verificada (envio e remoção na defesa).
403api_key_not_allowedA rota só aceita a sessão do painel (sincronizar).
404not_foundA disputa ou a defesa não existe ou é de outra empresa.
409defense_in_progressA defesa está sendo enviada à processadora e não pode mais mudar.
409defense_already_submittedA defesa já foi enviada à processadora.
413payload_too_largeA requisição passa de 16 MB.
422invalid_textO texto não tem de 11 a 255 caracteres.
422defense_contains_documentO texto tem um CPF ou CNPJ válido.
422invalid_fileUm anexo não é PDF, JPG ou PNG.
422file_too_largeUm anexo passa de 5 MB.
422too_many_filesMais de 3 anexos.
422unknown_attachmentUm id em keepAttachmentIds não é anexo atual da defesa.
422defense_window_closedA disputa não aceita mais defesa.
422webhook_not_configuredNão há endpoint de webhook ativo (sincronizar).
429rate_limitedLimite 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.
esc