Pagnivpagniv
Dashboard

Disputas

Liste disputas, conteste com evidências ou aceite chargebacks.

Referência rápida

Quick start

Ciclo de vida da disputa

Uma disputa é aberta quando o pagador contesta uma cobrança paga junto ao banco (devolução/MED ou chargeback) e o provedor de pagamento reporta a contestação. O valor da cobrança é reservado automaticamente e você recebe o evento de webhook dispute.opened. Conteste pela aba de disputas enviando as comprovações da transação. Entenda cada status:

OPEN

Significado: Disputa aberta, valor reservado

Ações possíveis: Aceitar ou contestar

MERCHANT_RESPONDED

Significado: Merchant contestou com evidências

Ações possíveis: Aguardar análise

UNDER_REVIEW

Significado: Em análise pela Pagniv

Ações possíveis: Aguardar resolução

RESOLVED_MERCHANT

Significado: Resolvida a favor do merchant

Ações possíveis: Valor liberado. Estado final

RESOLVED_BUYER

Significado: Resolvida a favor do comprador

Ações possíveis: Valor estornado. Estado final

Conteste uma disputa com evidências:

Contestar disputa
curl -X POST https://api.pagniv.com/v1/disputes/{id}/contest \
  -H "X-API-Key: sk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "response": "Produto entregue em 10/01. Rastreio: AB123BR",
    "evidences": ["https://storage.example.com/comprovante.pdf"]
  }'

Automatize com webhooks

Todos os endpoints de disputa aceitam autenticação por API key (X-API-Key) ou JWT. Para responder em tempo real, assine os webhooks e conecte ao fluxo:

dispute.opened

Quando dispara: Disputa criada, valor reservado

Ação automatizada sugerida: Buscar evidências e chamar /contest ou /accept

dispute.resolved

Quando dispara: Disputa finalizada (a favor ou contra)

Ação automatizada sugerida: Atualizar estado interno e conciliar saldo

Listar disputas

Lista disputas com filtro por status. Use para monitorar disputas abertas e acompanhar resoluções.

GET/v1/disputes

Autenticação

X-API-Keystringheaderobrigatório

Sua chave de API no header X-API-Key: sk_live_.... Gere em Dashboard → Integrações.

Query params

statusstringopcional

OPEN, MERCHANT_RESPONDED, UNDER_REVIEW, RESOLVED_MERCHANT, RESOLVED_BUYER

pageintegeropcional

Página (padrão: 1)

limitintegeropcional

Itens por página (padrão: 20)

/v1/disputes
curl "https://api.pagniv.com/v1/disputes?status=OPEN&page=1" \
  -H "X-API-Key: sk_live_sua_chave"
{
  "success": true,
  "data": [
    {
      "id": "660e8400-...",
      "chargeId": "550e8400-...",
      "reason": "PRODUCT_NOT_RECEIVED",
      "status": "OPEN",
      "createdAt": "2026-01-20T10:00:00Z"
    }
  ],
  "meta": { "total": 5, "page": 1, "limit": 20, "pages": 1 }
}

Detalhar disputa

Retorna todos os dados da disputa: motivo, evidências enviadas, resposta do merchant e resolução.

GET/v1/disputes/{id}

Autenticação

X-API-Keystringheaderobrigatório

Sua chave de API no header X-API-Key: sk_live_.... Gere em Dashboard → Integrações.

/v1/disputes/{id}
curl "https://api.pagniv.com/v1/disputes/{id}" \
  -H "X-API-Key: sk_live_sua_chave"
{
  "success": true,
  "data": {
    "id": "660e8400-...",
    "chargeId": "550e8400-...",
    "reason": "PRODUCT_NOT_RECEIVED",
    "status": "OPEN",
    "createdAt": "2026-01-20T10:00:00Z"
  }
}

Aceitar disputa

Aceita a disputa e estorna o valor ao comprador. Se o saldo reservado for insuficiente, a diferença vira um DISPUTE_DEFICIT que é coberto automaticamente nos próximos recebimentos.

POST/v1/disputes/{id}/accept

Autenticação

X-API-Keystringheaderobrigatório

Sua chave de API no header X-API-Key: sk_live_.... Gere em Dashboard → Integrações.

/v1/disputes/{id}/accept
curl -X POST "https://api.pagniv.com/v1/disputes/{id}/accept" \
  -H "X-API-Key: sk_live_sua_chave"
{
  "success": true,
  "data": {
    "id": "660e8400-...",
    "status": "RESOLVED_BUYER"
  }
}

Contestar disputa

Contesta a disputa enviando uma resposta e URLs de evidência (comprovantes, prints, rastreio). O status muda para MERCHANT_RESPONDED e a equipe Pagniv analisa.

POST/v1/disputes/{id}/contest

Autenticação

X-API-Keystringheaderobrigatório

Sua chave de API no header X-API-Key: sk_live_.... Gere em Dashboard → Integrações.

Body (JSON)

responsestringobrigatório

Resposta detalhada

evidencesstring[]opcional

URLs de evidência

/v1/disputes/{id}/contest
curl -X POST https://api.pagniv.com/v1/disputes/{id}/contest \
  -H "X-API-Key: sk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "response": "Produto entregue em 10/01. Rastreio: AB123456BR",
    "evidences": ["https://storage.example.com/comprovante.pdf"]
  }'
{
  "success": true,
  "data": {
    "id": "660e8400-...",
    "status": "MERCHANT_RESPONDED"
  }
}