MED
Liste, consulte e exporte as infrações Pix (MED), baixe o dossiê em PDF e envie, consulte e altere a defesa com anexos.
O objeto MED
Um MED é uma infração Pix aberta contra um recebimento da sua empresa. O valor contestado fica retido no saldo bloqueado até o encerramento. Prazos, defesa e webhooks estão explicados no guia MED (disputas Pix).
Campos
objectstringidstringIdentificador da infração Pix (MED).
endToEndIdstringIdentificador da transação Pix contestada no Banco Central.
chargeIdstring · pode ser nuloCobrança ligada à infração, quando identificada.
chargeobject · pode ser nulocharge.descriptionstringcharge.paidAtstring · pode ser nulocharge.amountCentsintegercharge.endToEndMatchesboolean · pode ser nulotrue se o identificador Pix da infração é o da cobrança ligada; false se é outro; null quando não dá para comparar.
amountCentsintegerValor contestado, em centavos.
holdCentsintegerValor retido agora no saldo por esta infração (0 depois da liberação).
platformCoveredCentsintegerParte do valor contestado que a MaxxiPay cobre, porque o Pix foi pago acima do valor da cobrança e só o valor da cobrança foi creditado. Não é retida do seu saldo. Ausente quando não há essa parte.
statusenumopenedAtstringRegistro do MED na MaxxiPay.
bankOpenedAtstring · pode ser nuloAbertura do MED pelo banco (null se a processadora não informou).
deadlineAtstring · pode ser nuloPrazo de defesa.
closedAtstring · pode ser nuloQuando a infração foi encerrada.
outcomeenum · pode ser nuloinfractionIdstring · pode ser nuloIdentificador da infração Pix no MED.
reportedBystring · pode ser nuloQuem abriu a infração (ex.: DEBITED_PARTICIPANT).
reportedByLabelstring · pode ser nuloRótulo em português de reportedBy.
reportDetailstring · pode ser nuloRelato da infração (texto livre, até 4.000 caracteres).
analysisDetailstring · pode ser nuloAnálise da infração (texto livre, até 4.000 caracteres).
payerobjectpayer.namestring · pode ser nuloNome de quem pagou o Pix contestado.
payer.documentMaskedstring · pode ser nuloCPF ou CNPJ de quem pagou, sempre mascarado.
payer.ispbstring · pode ser nuloISPB do banco do pagador (8 dígitos do E2E).
payer.bankNamestring · pode ser nuloNome do banco do pagador, quando conhecido.
guaranteedUntilstring · pode ser nuloAté quando a defesa enviada pela MaxxiPay chega antes de uma resposta padrão da processadora.
hardDeadlineAtstring · pode ser nuloÚltimo momento para enviar a defesa: prazo do MED − 2 h; sem prazo informado, abertura + 7 dias − 2 h.
defenseWindowenumprocessorDefaultDefenseAtstring · pode ser nuloQuando a processadora enviou a resposta padrão dela, se já enviou. Depois da resposta padrão, o MED passa para análise pelo banco do pagador e a defesa não é mais aceita.
defenseobject · pode ser nulodefense.objectstringdefense.idstringdefense.medIdstringdefense.textstringdefense.attachmentsarray de objectdefense.statusenumdefense.statusLabelstringdefense.notSentReasonenum · pode ser nulodefense.notSentLabelstring · pode ser nulodefense.receivedAtstringdefense.updatedAtstringdefense.sentAtstring · pode ser nulodefense.windowAtReceiptenumdefense.noticestringdefense.processorDefaultDefenseAtstring · pode ser nulo
{
"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": {
"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."
}
}Listar MEDs
/v1/med-disputesLista os MEDs da empresa, do mais recente para o mais antigo, com o resumo de abertos, retido e prazos.
- Escopo
charges:read- Idempotency-Key
- Não se aplica
- Sucesso
200
from e to filtram pela abertura. O summary vale para a empresa inteira, sem os filtros. Veja o guia MED.
Parâmetros de consulta
statusenumopcionalfromstring · ISO 8601opcionaltostring · ISO 8601opcionalcursorstringopcionallimitintegeropcional
Resposta
Devolve uma lista paginada de objetos MED, sem a defesa, mais o summary.
Erros desta rota
403forbiddenA chave não tem o escopo exigido pela rota.422invalid_queryUm parâmetro de consulta é inválido. O parâmetro vem em error.field.422invalid_cursorO cursor não foi gerado pela API.
Exemplo de retorno, pelo contrato da rota. Não cria cobrança nem saque.
const response = await fetch("https://api.maxxipay.com/v1/med-disputes?status=awaiting_defense&limit=20", {
headers: {
Authorization: `Bearer ${process.env.MAXXIPAY_API_KEY}`,
},
});
const page = await response.json();{
"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
}
}
}Consultar um MED
/v1/med-disputes/{id}Consulta um MED com os prazos, os dados da infração e a defesa, se houver.
- Escopo
charges:read- Idempotency-Key
- Não se aplica
- Sucesso
200
Parâmetros de caminho
idstringobrigatórioIdentificador da infração Pix (MED).
Resposta
Devolve o objeto MED.
Exemplo de retorno, pelo contrato da rota. Não cria cobrança nem saque.
const response = await fetch("https://api.maxxipay.com/v1/med-disputes/aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee", {
headers: {
Authorization: `Bearer ${process.env.MAXXIPAY_API_KEY}`,
},
});
const med = await response.json();{
"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": {
"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."
}
}Baixar o dossiê em PDF
/v1/med-disputes/{id}/dossier.pdfBaixa o dossiê do MED em PDF, para guardar ou anexar a um processo interno.
- Escopo
charges:read- Idempotency-Key
- Não se aplica
- Sucesso
200
O PDF 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. Vem sempre como download (Content-Disposition: attachment), com o nome dossie-med-<últimos 12 caracteres do endToEndId>.pdf.
Parâmetros de caminho
idstringobrigatórioIdentificador da infração Pix (MED).
Resposta
Devolve o arquivo application/pdf.
Exemplo de retorno, pelo contrato da rota. Não cria cobrança nem saque.
import { writeFile } from "node:fs/promises";
const response = await fetch("https://api.maxxipay.com/v1/med-disputes/aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee/dossier.pdf", {
headers: {
Authorization: `Bearer ${process.env.MAXXIPAY_API_KEY}`,
},
});
await writeFile("dossie-med-700000000001.pdf", Buffer.from(await response.arrayBuffer()));{
"Content-Type": "application/pdf",
"Content-Disposition": "attachment; filename=\"dossie-med-700000000001.pdf\"",
"X-Content-Type-Options": "nosniff",
"Cache-Control": "private, no-store"
}Exportar MEDs em CSV
/v1/med-disputes/exportExporta os MEDs em CSV, com os mesmos filtros da listagem.
- Escopo
charges:read- Idempotency-Key
- Não se aplica
- Sucesso
200
CSV com BOM, separado por ponto e vírgula, até 5.000 linhas. Cada célula tem até 2.000 caracteres.
Parâmetros de consulta
statusenumopcionalfromstring · ISO 8601opcionaltostring · ISO 8601opcional
Resposta
Devolve o arquivo CSV como download (text/csv).
Erros desta rota
403forbiddenA chave não tem o escopo exigido pela rota.422invalid_queryUm parâmetro de consulta é inválido. O parâmetro vem em error.field.
Exemplo de retorno, pelo contrato da rota. Não cria cobrança nem saque.
import { writeFile } from "node:fs/promises";
const response = await fetch("https://api.maxxipay.com/v1/med-disputes/export?from=2026-11-01T00%3A00%3A00-03%3A00&to=2026-11-08T23%3A59%3A59-03%3A00", {
headers: {
Authorization: `Bearer ${process.env.MAXXIPAY_API_KEY}`,
},
});
await writeFile("med-2026-11-01-a-2026-11-08.csv", Buffer.from(await response.arrayBuffer()));{
"Content-Type": "text/csv; charset=utf-8",
"Content-Disposition": "attachment; filename=\"med-2026-11-01-a-2026-11-08.csv\""
}Enviar a defesa
/v1/med-disputes/{id}/defenseEnvia a defesa do MED em multipart/form-data, com texto e até 3 anexos. Enquanto a defesa não for enviada à processadora, um novo envio substitui texto e anexos.
- Escopo
med:write- Idempotency-Key
- Não se aplica
- Sucesso
202
Só com o MED em awaiting_defense e defenseWindow diferente de closed. Texto puro, de 11 a 255 caracteres, sem CPF ou CNPJ. Anexos PDF, JPG ou PNG de até 5 MB, conferidos pelo conteúdo; até 16 MB por requisição. A conta precisa estar verificada.
Parâmetros de caminho
idstringobrigatórioIdentificador da infração Pix (MED).
Corpo da requisição (multipart/form-data)
textstringobrigatórioDefesa em texto puro, de 11 a 255 caracteres. Não inclua CPF ou CNPJ.
filesarray de stringopcionalAnexos novos, no campo files repetido.
keepAttachmentIdsarray de stringopcionalAo alterar uma defesa: ids dos anexos atuais que continuam (campo repetido). Os não listados são apagados. Mantidos + novos ≤ 3. Sem o campo, a defesa fica só com os anexos novos.
Resposta
Devolve a defesa com status received.
Erros desta rota
403forbiddenA chave não tem o escopo exigido pela rota.403account_not_verifiedA conta ainda não foi verificada. A chave de API não autentica e o painel só consulta até a aprovação.404not_foundO recurso não existe ou pertence a 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_largeO corpo passou do limite: 1 MB em JSON ou 16 MB no envio da defesa de MED.422invalid_textO texto da defesa não tem de 11 a 255 caracteres depois de tirar os espaços das pontas.422defense_contains_documentO texto da defesa tem um CPF ou CNPJ válido.422invalid_fileUm anexo não é PDF, JPG ou PNG. O tipo é conferido pelo conteúdo do arquivo.422file_too_largeUm anexo passa de 5 MB.422too_many_filesA defesa passou de 3 anexos.422unknown_attachmentUm id em keepAttachmentIds não é um anexo atual desta defesa.422defense_window_closedO MED não aceita mais defesa: saiu de Aguardando defesa ou passou de hardDeadlineAt.429rate_limitedA chave passou do limite de requisições por minuto.
Exemplo de retorno, pelo contrato da rota. Não cria cobrança nem saque.
import { openAsBlob } from "node:fs";
const form = new FormData();
form.append("text", "Pedido 000123 entregue em 02/11/2026. Segue comprovante de entrega e conversa com o cliente.");
form.append("files", await openAsBlob("comprovante-entrega.pdf", { type: "application/pdf" }), "comprovante-entrega.pdf");
const response = await fetch("https://api.maxxipay.com/v1/med-disputes/aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee/defense", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.MAXXIPAY_API_KEY}`,
},
body: form,
});
const defense = await response.json();{
"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."
}Consultar a defesa
/v1/med-disputes/{id}/defenseConsulta a defesa do MED: texto, anexos e situação do envio à processadora.
- Escopo
charges:read- Idempotency-Key
- Não se aplica
- Sucesso
200
Parâmetros de caminho
idstringobrigatórioIdentificador da infração Pix (MED).
Resposta
Devolve a defesa. Sem defesa enviada, responde 404.
Exemplo de retorno, pelo contrato da rota. Não cria cobrança nem saque.
const response = await fetch("https://api.maxxipay.com/v1/med-disputes/aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee/defense", {
headers: {
Authorization: `Bearer ${process.env.MAXXIPAY_API_KEY}`,
},
});
const defense = await response.json();{
"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."
}Baixar um anexo da defesa
/v1/med-disputes/{id}/defense/attachments/{att}IdBaixa um anexo da defesa.
- Escopo
charges:read- Idempotency-Key
- Não se aplica
- Sucesso
200
O arquivo vem sempre como download (Content-Disposition: attachment), com o tipo conferido de novo na saída.
Parâmetros de caminho
idstringobrigatórioIdentificador da infração Pix (MED).
attIdstringobrigatórioIdentificador do anexo.
Resposta
Devolve o arquivo (application/pdf, image/jpeg ou image/png).
Exemplo de retorno, pelo contrato da rota. Não cria cobrança nem saque.
import { writeFile } from "node:fs/promises";
const response = await fetch("https://api.maxxipay.com/v1/med-disputes/aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee/defense/attachments/att_00000000000000000001", {
headers: {
Authorization: `Bearer ${process.env.MAXXIPAY_API_KEY}`,
},
});
await writeFile("comprovante-entrega.pdf", Buffer.from(await response.arrayBuffer()));{
"Content-Type": "application/pdf",
"Content-Disposition": "attachment; filename=\"comprovante-entrega.pdf\"",
"X-Content-Type-Options": "nosniff",
"Cache-Control": "private, no-store"
}Remover um anexo da defesa
/v1/med-disputes/{id}/defense/attachments/{att}IdRemove um anexo da defesa enquanto ela ainda não foi enviada à processadora.
- Escopo
med:write- Idempotency-Key
- Não se aplica
- Sucesso
200
Parâmetros de caminho
idstringobrigatórioIdentificador da infração Pix (MED).
attIdstringobrigatórioIdentificador do anexo.
Resposta
Devolve a defesa sem o anexo.
Erros desta rota
403forbiddenA chave não tem o escopo exigido pela rota.403account_not_verifiedA conta ainda não foi verificada. A chave de API não autentica e o painel só consulta até a aprovação.404not_foundO recurso não existe ou pertence a outra empresa.409defense_in_progressA defesa está sendo enviada à processadora e não pode mais mudar.409defense_already_submittedA defesa já foi enviada à processadora.422defense_window_closedO MED não aceita mais defesa: saiu de Aguardando defesa ou passou de hardDeadlineAt.
Exemplo de retorno, pelo contrato da rota. Não cria cobrança nem saque.
const response = await fetch("https://api.maxxipay.com/v1/med-disputes/aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee/defense/attachments/att_00000000000000000001", {
method: "DELETE",
headers: {
Authorization: `Bearer ${process.env.MAXXIPAY_API_KEY}`,
},
});
const defense = await response.json();{
"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": [],
"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."
}