Disputas

Disputa é o mecanismo de contestação do PIX (MED). Quando o comprador aciona o banco dizendo que não recebeu o produto, o valor daquela transação fica retido no seu saldo até a operadora decidir. Enquanto está aberta, o valor aparece em disputeBlocked na carteira e sai do withdrawable. Não dá pra sacar o que está contestado.

Disputas não existem em sandbox. Os endpoints respondem 404 com chave ps_test_, porque contestação nasce de uma transação real.

Monitorando

curl "https://api.purincash.com/v1/disputes?status=aberta&limit=50" \
  -H "Authorization: Bearer $PURINCASH_KEY"

{
  "disputes": [
    {
      "id": "665f1a2b3c4d5e6f7a8b9c0d",
      "code": "MED-2024-001",
      "endToEndId": "E123456782026...",
      "orderCode": "JUE7Y9MPSX",
      "buyer": "João Silva",
      "product": "Plano Premium",
      "amount": 23.07,
      "reason": "Produto não recebido",
      "status": "aberta",
      "evidences": [],
      "resolvedAt": null,
      "createdAt": "2026-03-18T10:00:00.000Z"
    }
  ],
  "total": 3,
  "limit": 50,
  "offset": 0
}

Status possíveis: aberta, resolvida e perdida.

Vale rodar essa listagem uma vez por dia filtrando por aberta. Disputa tem prazo, e perder por não ter respondido é o pior jeito de perder.

Respondendo

Só disputa com status aberta aceita evidência. Você pode mandar documentos, um texto que vira PDF, ou os dois.

curl -X POST https://api.purincash.com/v1/disputes/665f1a2b3c4d5e6f7a8b9c0d/evidence \
  -H "Authorization: Bearer $PURINCASH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {
        "url": "https://minhaloja.com/comprovantes/1042.pdf",
        "description": "Comprovante de entrega",
        "correlationID": "MED-2024-001-EV1"
      }
    ],
    "textForPdf": "Produto entregue em 15/03 às 10h05. Acesso registrado pelo IP do comprador em 15/03 às 10h12."
  }'

Resposta 200

{ "uploaded": 2 }

array

Até 10 itens. Cada um precisa de url http ou https. Itens sem URL válida são descartados em silêncio.

string

Texto convertido automaticamente em PDF de defesa. Serve sozinho, sem documents.

Um dos dois é obrigatório. Sem nenhum, a resposta é 400.

As URLs precisam apontar direto para o arquivo (PDF, PNG, JPEG ou WebP). Link de página HTML, tipo encurtador de print, é recusado pela operadora. Se o seu comprovante está numa página, gere um PDF e hospede o arquivo.

O que costuma funcionar como evidência

Prova de entrega

Log de acesso, e-mail de entrega com data e hora, código de rastreio, print do sistema mostrando a liberação.

Prova de aceite

Termos aceitos, confirmação de recebimento, conversa em que o comprador reconhece que recebeu.

Identidade do comprador

O endToEndId da transação, o e-mail usado na compra, o externalId que amarra ao usuário da sua base.

Contexto de uso

Histórico mostrando que a conta foi usada depois da compra. É o que mais derruba “produto não recebido”.

Junte a evidência de forma programática assim que o pagamento confirma, não quando a disputa chega. Trinta dias depois o log já rotacionou e o print não existe mais.

Consultando uma disputa

curl https://api.purincash.com/v1/disputes/665f1a2b3c4d5e6f7a8b9c0d \
  -H "Authorization: Bearer $PURINCASH_KEY"

O retorno traz as evidências já enviadas, com URLs assinadas que são regeneradas a cada consulta. Elas expiram, então não vale guardar a URL: guarde o id e consulte de novo quando precisar. Disputa que não é da sua conta responde 404, e não 403. É proposital: a API não confirma a existência de recurso de terceiro.

Erros

Código	Motivo
`400`	Disputa já resolvida, corpo sem `documents` nem `textForPdf`, nenhuma URL válida, ou ID em formato inválido
`404`	Disputa inexistente, de outra conta, ou chamada em sandbox
`502`	Falha ao enviar a evidência à operadora. Tente de novo
`503`	Provedor de pagamento não configurado

Comece por aqui

Receber

Produtos e entrega

Dinheiro na conta

Referência rápida

Monitorando

Respondendo

O que costuma funcionar como evidência

Prova de entrega

Prova de aceite

Identidade do comprador

Contexto de uso

Consultando uma disputa

Erros

​Monitorando

​Respondendo

​O que costuma funcionar como evidência

Prova de entrega

Prova de aceite

Identidade do comprador

Contexto de uso

​Consultando uma disputa

​Erros

Monitorando

Respondendo

O que costuma funcionar como evidência

Consultando uma disputa

Erros