Defender uma contestação
Dispute a contestação enviando a sua justificativa com um comprovante da venda.
Defenda a contestação
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"import { readFile } from 'node:fs/promises'
const form = new FormData()
form.append('note', 'Produto entregue em 05/11, com assinatura do comprador.')
const pdf = await readFile('comprovante-entrega.pdf')
form.append('file', new Blob([pdf], { type: 'application/pdf' }), 'comprovante-entrega.pdf')
const response = await fetch(
'https://api.sandbox.payzu.dev/v1/chargebacks/chb_4TnW8xQcLb2MzYv7KdRh3E/defend',
{ method: 'POST', headers: { authorization: `Bearer ${process.env.PAYZU_API_KEY}` }, body: form }
)
const chargeback = await response.json()
if (!response.ok) throw new Error(`${chargeback.code ?? response.status}: ${chargeback.message}`)
console.log(chargeback.status, chargeback.response.file_name){
"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
| Campo | Regra |
|---|---|
note | A justificativa, de 1 a 2000 caracteres. |
file | Um ú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ção | Resposta |
|---|---|
| Repetir a mesma ação | 200, com a contestação como ficou na primeira chamada, sem enviar nada de novo. |
| Enviar a outra ação | 409, porque a contestação já foi respondida. |
| Duas respostas ao mesmo tempo | A segunda recebe 409, porque já existe uma resposta em andamento. |
| A adquirente não confirma a tempo | A PayZu relê a contestação antes de responder: com a resposta registrada, a chamada responde 200. |
Erros desta operação
| Código | HTTP | Mensagem |
|---|---|---|
PZ610 | 400 | Envie a defesa em multipart/form-data, com a justificativa em note e um arquivo em file. |
PZ611 | 400 | Informe a justificativa da defesa, com até 2000 caracteres. |
PZ612 | 400 | Envie o arquivo da defesa. |
PZ613 | 400 | O arquivo da defesa deve ter até 8 MB. |
PZ614 | 400 | O arquivo da defesa deve ser PDF, JPEG ou PNG. |
PZ031 | 403 | Esta conta só tem acesso de consulta. |
PZ032 | 403 | Cartão não habilitado para esta conta. Fale com o suporte para habilitar ou ofereça apenas Pix. |
PZ600 | 404 | Contestação não encontrada para o id informado. |
PZ601 | 409 | Esta contestação já foi respondida ou encerrada. |
PZ602 | 409 | O prazo para responder a esta contestação terminou. |
PZ603 | 409 | Já existe uma resposta em andamento para esta contestação. |
PZ604 | 422 | A resposta não foi aceita. Revise a justificativa e o arquivo e envie de novo. |
PZ605 | 422 | Nã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.