VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Pagar.me, chargebacks e disputas

Disputas com o comprador

Lista as disputas abertas contra o seller e envia a proposta de solução.

Diferente do chargeback (o cliente reclama ao banco), a disputa nasce dentro da loja: o comprador reclama de um pedido e a plataforma conduz uma conversa estruturada entre as partes, com prazos. Não há módulo nem privilégio extra para o seller.

Ciclo da disputa

opened > awaiting_seller (48 h) > awaiting_buyer (72 h) > encerrada em resolved_*, ou escalated para a mediação da loja, ou canceled.

Listar disputas

Uma disputa é uma reclamação do comprador depois da compra (produto não chegou, veio diferente, danificado...). O seller tem 48 horas para responder com uma proposta. Esta rota lista as disputas do seller, da mais nova para a mais antiga, até 500, sem paginação.

GET/api/v1/vendor/disputesSeller

Disputas abertas por compradores contra o seller

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).

Parâmetros de consulta

statusstring
Só as disputas neste status (nome por extenso).

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/disputes?status=awaiting_seller" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Disputas
json
{
  "items": [
    {
      "id": "9a5f3c1e-7b44-4e0e-8a41-0f6f2b3c9d10",
      "order_id": "a8a3c7a3-5f15-45a8-a385-4f20fbf8b722",
      "order_item_id": "ccb748c1-a2a4-49a8-b52e-a6db1a989147",
      "customer_id": "220b672c-90fe-4841-ae86-bd4f1ace982e",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "reason": "damaged",
      "status": "awaiting_seller",
      "amount_cents": 19900,
      "seller_deadline_at": "2026-10-13T12:00:00Z",
      "created_at": "2026-10-11T12:00:00Z",
      "events": [
        {
          "actor_type": "buyer",
          "action": "opened",
          "payload": {
            "description": "Chegou com a tela trincada."
          },
          "created_at": "2026-10-11T12:00:00Z"
        }
      ]
    }
  ]
}

Campos da resposta

itemsobject[]

Disputas.

iduuid
Id da disputa.
order_iduuid
Pedido.
order_item_iduuid
Item específico, quando a disputa é de um item. Omitido se for do pedido todo.
customer_iduuid
Comprador.
vendor_iduuid
Seller.
reasonstring
not_receiveddifferent_from_descriptiondamagedwrong_itemother
Motivo escolhido pelo comprador.
statusstring
openedawaiting_sellerawaiting_buyerescalatedresolved_refund_fullresolved_refund_partialresolved_reshipresolved_rejectedcanceled
Situação da disputa.
amount_centsinteger
Valor em disputa, em centavos.
refund_centsinteger
Valor reembolsado, quando resolvida com reembolso. Omitido antes.
thread_iduuid
Conversa de mensagens ligada. Omitido se não há.
seller_deadline_atstring
Prazo do seller para responder (48 horas após a abertura).
buyer_deadline_atstring
Prazo do comprador para reagir à proposta (72 horas após a resposta do seller).
resolution_notestring
Texto de encerramento. Omitido antes.
created_atstring
Abertura, RFC 3339.
eventsobject[]

Linha do tempo.

actor_typestring
buyerselleradminsystem
Quem agiu.
actionstring
Ação registrada (por exemplo opened, responded, escalated).
payloadobject
Dados da ação (proposta, nota...).
created_atstring
Quando ocorreu, RFC 3339.

Erros

StatusQuandoCorpo de exemplo
401Token ausente, inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.{"error":"insufficient permissions"}
403O usuário não está vinculado a nenhum seller.{"error":"no vendor account associated with this user"}

Responder uma disputa

O seller responde a uma disputa que está awaiting_seller com uma proposta: reembolso total, reembolso parcial, reenvio ou recusa. A disputa passa a awaiting_buyer e o comprador tem 72 horas para aceitar (o que encerra a disputa conforme a proposta) ou escalar para a mediação da loja. Um job horário trata os prazos: sem resposta do seller em 48 horas, a disputa é escalada para a loja (ou reembolsada sozinha, se a loja ligou essa opção e o motivo é not_received); sem reação do comprador em 72 horas, a disputa é cancelada.

POST/api/v1/vendor/disputes/{id}/respondSeller

Enviar a proposta do seller ao comprador

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).
Content-Typestringobrigatório
application/json.

Parâmetros de caminho

iduuidobrigatório
Id da disputa.

Corpo da requisição

proposalstringobrigatório
refund_fullrefund_partialreshipreject
Proposta do seller.
refund_centsinteger
Valor do reembolso em centavos, para refund_partial. A API não confere se passa do valor da disputa.
notestring
Mensagem ao comprador.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/vendor/disputes/9a5f3c1e-7b44-4e0e-8a41-0f6f2b3c9d10/respond" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "proposal": "refund_partial",
  "refund_cents": 9900,
  "note": "Reembolso de metade e você fica com o produto."
}'

Resposta

200Disputa atualizada
json
{
  "id": "9a5f3c1e-7b44-4e0e-8a41-0f6f2b3c9d10",
  "order_id": "a8a3c7a3-5f15-45a8-a385-4f20fbf8b722",
  "order_item_id": "ccb748c1-a2a4-49a8-b52e-a6db1a989147",
  "customer_id": "220b672c-90fe-4841-ae86-bd4f1ace982e",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "reason": "damaged",
  "status": "awaiting_buyer",
  "amount_cents": 19900,
  "seller_deadline_at": "2026-10-13T12:00:00Z",
  "created_at": "2026-10-11T12:00:00Z",
  "events": [
    {
      "actor_type": "buyer",
      "action": "opened",
      "payload": {
        "description": "Chegou com a tela trincada."
      },
      "created_at": "2026-10-11T12:00:00Z"
    }
  ],
  "buyer_deadline_at": "2026-10-14T12:00:00Z"
}

Campos da resposta

iduuid
Id da disputa.
order_iduuid
Pedido.
order_item_iduuid
Item específico, quando a disputa é de um item. Omitido se for do pedido todo.
customer_iduuid
Comprador.
vendor_iduuid
Seller.
reasonstring
not_receiveddifferent_from_descriptiondamagedwrong_itemother
Motivo escolhido pelo comprador.
statusstring
openedawaiting_sellerawaiting_buyerescalatedresolved_refund_fullresolved_refund_partialresolved_reshipresolved_rejectedcanceled
Situação da disputa.
amount_centsinteger
Valor em disputa, em centavos.
refund_centsinteger
Valor reembolsado, quando resolvida com reembolso. Omitido antes.
thread_iduuid
Conversa de mensagens ligada. Omitido se não há.
seller_deadline_atstring
Prazo do seller para responder (48 horas após a abertura).
buyer_deadline_atstring
Prazo do comprador para reagir à proposta (72 horas após a resposta do seller).
resolution_notestring
Texto de encerramento. Omitido antes.
created_atstring
Abertura, RFC 3339.
eventsobject[]

Linha do tempo.

actor_typestring
buyerselleradminsystem
Quem agiu.
actionstring
Ação registrada (por exemplo opened, responded, escalated).
payloadobject
Dados da ação (proposta, nota...).
created_atstring
Quando ocorreu, RFC 3339.

Erros

StatusQuandoCorpo de exemplo
400Corpo inválido, proposta fora da lista, disputa que não é sua ou que não está awaiting_seller (motivo em detail, em inglês).{"error":"failed to respond","detail":"cannot respond in status awaiting_buyer"}
401Token ausente, inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.{"error":"insufficient permissions"}
403O usuário não está vinculado a nenhum seller.{"error":"no vendor account associated with this user"}

Veja também

  • Chargebacks
  • Visão geral
Anterior
Chargebacks
Próxima
Cupons, vales, pagamentos e NF-e
Nesta página
  • Listar disputas
  • Exemplo de requisição
  • Resposta
  • Erros
  • Responder uma disputa
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também