PayZu GatewayEstornos e contestações

Defender uma contestação


Nesta páginaDefenda a contestaçãoConfirme a respostaErros desta operação

Dispute a contestação enviando a sua justificativa com um comprovante da venda.

Defenda a contestação

bash
curl -X POST https://api.sandbox.payzu.dev/v1/chargebacks/chb_4TnW8xQcLb2MzYv7KdRh3E/defend \
  -H "Authorization: Bearer SUA_CHAVE_DE_API" \
  -F "note=Produto entregue em 05/11, com assinatura do comprador." \
  -F "file=@comprovante-entrega.pdf"
Trecho da resposta
{
  "id": "chb_4TnW8xQcLb2MzYv7KdRh3E",
  "status": "defended",
  "response": {
    "action": "defend",
    "note": "Produto entregue em 05/11, com assinatura do comprador.",
    "file_name": "comprovante-entrega.pdf",
    "sent_at": "2026-11-21T09:40:27.530Z"
  }
}

Referência: Defender uma contestação

CampoRegra
noteA justificativa, de 1 a 2000 caracteres.
fileUm único arquivo PDF, JPEG ou PNG de até 8 MB. O formato é conferido pelo conteúdo do arquivo, não pela extensão.

A resposta 200 traz a contestação inteira, no formato de Consultar uma contestação. Do arquivo, fica só o nome em response.file_name: a API não tem rota para baixar o arquivo. Esta rota ignora o cabeçalho Idempotency-Key.

Não defina Content-Type à mão no multipart.

O cliente HTTP monta o boundary: com curl -F e com o fetch do Node.js isso é automático. Sem multipart, ou com o arquivo em outro campo, a resposta é 400.

Só a contestação received aceita defesa, e dentro do prazo.

O prazo para responder vem em defense_deadline. Confira o status e o prazo em Consultar uma contestação.

Confirme a resposta

Quando a defesa é registrada, os webhooks da conta recebem chargeback.responded, com a contestação em data.chargeback; veja Contestação respondida. O resultado da defesa na bandeira não aparece na API, e o efeito na fatura e na assinatura está em Contestações.

SituaçãoResposta
Repetir a mesma ação200, com a contestação como ficou na primeira chamada, sem enviar nada de novo.
Enviar a outra ação409, porque a contestação já foi respondida.
Duas respostas ao mesmo tempoA segunda recebe 409, porque já existe uma resposta em andamento.
A adquirente não confirma a tempoA PayZu relê a contestação antes de responder: com a resposta registrada, a chamada responde 200.

Erros desta operação

CódigoHTTPMensagem
PZ610400Envie a defesa em multipart/form-data, com a justificativa em note e um arquivo em file.
PZ611400Informe a justificativa da defesa, com até 2000 caracteres.
PZ612400Envie o arquivo da defesa.
PZ613400O arquivo da defesa deve ter até 8 MB.
PZ614400O arquivo da defesa deve ser PDF, JPEG ou PNG.
PZ031403Esta conta só tem acesso de consulta.
PZ032403Cartão não habilitado para esta conta. Fale com o suporte para habilitar ou ofereça apenas Pix.
PZ600404Contestação não encontrada para o id informado.
PZ601409Esta contestação já foi respondida ou encerrada.
PZ602409O prazo para responder a esta contestação terminou.
PZ603409Já existe uma resposta em andamento para esta contestação.
PZ604422A resposta não foi aceita. Revise a justificativa e o arquivo e envie de novo.
PZ605422Não foi possível responder a esta contestação agora. Tente de novo mais tarde.

Os erros de autenticação estão no Catálogo de erros.