Atualizar uma disputa

curl -X POST "https://api.chargefy.io/v1/disputes/dp_GyJ4Ztc4M62Mz13a" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "evidence": {
      "customer_communication": "Conversation and receipt attached."
    },
    "metadata": {},
    "submit": true
  }'

{
  "id": "dp_GyJ4Ztc4M62Mz13a",
  "object": "dispute",
  "amount": 15000,
  "charge": "ch_nMZLA6hEyVDqMKPA",
  "closed_at": null,
  "created_at": "2026-05-22T03:00:00Z",
  "currency": "brl",
  "customer": "cus_uaJ6D8BocLmmGy4m",
  "evidence": {
    "customer_communication": "Conversation and receipt attached.",
    "file": "file_B9Xkd52jvSTED8G5"
  },
  "evidence_details": {
    "due_by": "2026-05-29T03:00:00Z",
    "has_evidence": true,
    "past_due": false,
    "submission_count": 1
  },
  "is_charge_refundable": true,
  "livemode": true,
  "metadata": {},
  "payment_intent": "pi_7JBx8yagY4TCdvwR",
  "reason": "fraudulent",
  "status": "under_review",
  "updated_at": "2026-05-22T18:10:00Z"
}

Atualiza um dispute com merge: o que você manda em evidence e metadata é combinado com o que já existe, sem apagar o resto. Esse mesmo endpoint serve pra duas coisas diferentes — só anotar informação (sem enviar nada ainda) e efetivamente enviar a defesa pra análise, quando você manda submit: true. Anexar o arquivo de evidência (o PDF ou TIF com a documentação) é feito por um endpoint separado, POST /v1/dispute-evidence-upload, não aqui. O upload grava um arquivo com purpose: "dispute_evidence" e devolve isso já refletido em evidence.file do dispute — então o fluxo normal é: primeiro sobe o arquivo por lá, depois (opcionalmente) usa este endpoint aqui pra completar o texto da defesa e mandar submit: true.

O que precisa estar pronto antes de `submit: true` funcionar

Mandar submit: true só é aceito se todas essas condições forem verdadeiras:

O dispute não pode já estar fechado (status diferente de won e de lost).
O prazo em evidence_details.due_by ainda não pode ter passado — isso é checado contra o relógio no momento da chamada, não contra o valor já salvo em evidence_details.past_due.
Precisa já existir um arquivo de evidência anexado (via dispute-evidence-upload) — mandar só texto em evidence sem nenhum arquivo não é suficiente pra submit: true passar.
Esse arquivo precisa continuar existindo e válido (não pode ter sido removido nem corrompido depois do upload).

Quando submit: true é aceito, a defesa junto com o arquivo anexado é enviada pra análise e o dispute passa para under_review. Cada tentativa de envio — aceita ou não — fica registrada internamente, então mesmo se der erro no meio do caminho, existe rastro de que a tentativa aconteceu.

string

required

ID do dispute (dp_*).

object

Texto livre com o contexto da defesa (histórico de conversa com o cliente, comprovante de entrega, etc.) e referências já registradas, como o file do arquivo anexado. Faz merge raso com o evidence que já existe — chaves novas são adicionadas, chaves repetidas são sobrescritas.

object

Pares chave-valor livres. Também faz merge com o metadata existente.

boolean

Quando true, manda a defesa pra análise de verdade. Só funciona se os requisitos acima estiverem satisfeitos; o dispute passa para under_review quando o envio é aceito.

curl -X POST "https://api.chargefy.io/v1/disputes/dp_GyJ4Ztc4M62Mz13a" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "evidence": {
      "customer_communication": "Conversation and receipt attached."
    },
    "metadata": {},
    "submit": true
  }'

{
  "id": "dp_GyJ4Ztc4M62Mz13a",
  "object": "dispute",
  "amount": 15000,
  "charge": "ch_nMZLA6hEyVDqMKPA",
  "closed_at": null,
  "created_at": "2026-05-22T03:00:00Z",
  "currency": "brl",
  "customer": "cus_uaJ6D8BocLmmGy4m",
  "evidence": {
    "customer_communication": "Conversation and receipt attached.",
    "file": "file_B9Xkd52jvSTED8G5"
  },
  "evidence_details": {
    "due_by": "2026-05-29T03:00:00Z",
    "has_evidence": true,
    "past_due": false,
    "submission_count": 1
  },
  "is_charge_refundable": true,
  "livemode": true,
  "metadata": {},
  "payment_intent": "pi_7JBx8yagY4TCdvwR",
  "reason": "fraudulent",
  "status": "under_review",
  "updated_at": "2026-05-22T18:10:00Z"
}

{
  "error": {
    "code": "resource_state_conflict",
    "message": "Evidence due date has passed",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "resource_state_conflict",
    "message": "Dispute is already closed",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "resource_state_conflict",
    "message": "Dispute evidence file is required",
    "param": "evidence",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Dispute cannot be submitted automatically",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "Failed to submit dispute evidence",
    "type": "api_error"
  }
}

Erros comuns

Status	`message`	Quando ocorre
`409`	`Dispute is already closed`	O dispute já está `won` ou `lost`; não dá pra atualizar evidência nem mandar `submit: true` num caso já decidido.
`409`	`Evidence due date has passed`	Você mandou `submit: true`, mas o prazo em `evidence_details.due_by` já passou no momento da chamada.
`409`	`Dispute evidence file is required`	Você mandou `submit: true` sem ter anexado nenhum arquivo antes pelo `dispute-evidence-upload`.
`422`	`Dispute cannot be submitted automatically`	O dispute não tem uma referência de cobrança no processador (por exemplo, um caso importado manualmente), então não existe pra onde mandar a defesa automaticamente.
`502`	`Failed to submit dispute evidence`	O envio da defesa falhou por um problema pontual de infraestrutura. Nesse caso nada muda no dispute — nem o status, nem o contador de envios — então é seguro tentar de novo.

curl -X POST "https://api.chargefy.io/v1/disputes/dp_GyJ4Ztc4M62Mz13a" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "evidence": {
      "customer_communication": "Conversation and receipt attached."
    },
    "metadata": {},
    "submit": true
  }'

{
  "id": "dp_GyJ4Ztc4M62Mz13a",
  "object": "dispute",
  "amount": 15000,
  "charge": "ch_nMZLA6hEyVDqMKPA",
  "closed_at": null,
  "created_at": "2026-05-22T03:00:00Z",
  "currency": "brl",
  "customer": "cus_uaJ6D8BocLmmGy4m",
  "evidence": {
    "customer_communication": "Conversation and receipt attached.",
    "file": "file_B9Xkd52jvSTED8G5"
  },
  "evidence_details": {
    "due_by": "2026-05-29T03:00:00Z",
    "has_evidence": true,
    "past_due": false,
    "submission_count": 1
  },
  "is_charge_refundable": true,
  "livemode": true,
  "metadata": {},
  "payment_intent": "pi_7JBx8yagY4TCdvwR",
  "reason": "fraudulent",
  "status": "under_review",
  "updated_at": "2026-05-22T18:10:00Z"
}

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Atualizar uma disputa

O que precisa estar pronto antes de `submit: true` funcionar

Erros comuns

​O que precisa estar pronto antes de submit: true funcionar

​Erros comuns

O que precisa estar pronto antes de `submit: true` funcionar

Erros comuns