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

Chargebacks

Fila de chargebacks do seller, com dossiê de provas, classificação e desfecho.

A Central de Chargebacks mostra ao seller os casos em que um cliente contestou uma compra dele no cartão. Não há módulo nem privilégio extra: basta ser seller. O seller só vê e altera os próprios casos; o caso de outro seller responde como se não existisse.

Prazo de 7 dias

Caso open ou evidence_ready passado de due_at vira expired na próxima leitura e perde a chance de defesa.

Fluxo de situação

open (caso novo) vira evidence_ready quando o dossiê é montado, submitted quando o seller envia, e termina em won, lost ou resolved_refunded. expired é o prazo vencido.

Listar chargebacks

Um chargeback acontece quando o cliente contesta a cobrança com o banco dele. A plataforma abre um caso com prazo de 7 dias para o seller se defender, e já monta um dossiê de provas. Lista os casos do seller, os de prazo mais curto primeiro. O tamanho da página é fixo em 50. Casos abertos com prazo vencido são marcados expired na leitura.

GET/api/v1/vendor/chargebacksSeller

Casos de chargeback do seller

Cabeçalhos

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

Parâmetros de consulta

statusstring
Só os casos neste status, texto exato (open, evidence_ready, submitted, won, lost, resolved_refunded, expired).
pageintegerpadrão: 1
Página de 50, a partir de 1.

Exemplo de requisição

Resposta

200Casos

Campos da resposta

casesobject[]

Casos da página.

iduuid
Id do caso.
order_iduuid
Pedido contestado.
gatewaystring
Gateway que avisou (por exemplo pagarme, stripe).
gateway_dispute_idstring
Id da contestação no gateway. Omitido se não há.
amount_centsinteger
Valor contestado, em centavos.
reasonstring
Motivo informado pelo gateway. Omitido se vazio.
classificationstring
Classificação dada pelo seller ou pela loja (texto livre, por exemplo fraud). Omitido se vazio.
statusstring
openevidence_readysubmittedwonlostresolved_refundedexpired
Situação do caso.
vendor_iduuid
Seller dono do caso.
return_iduuid
Devolução ligada ao caso. Omitido se não há.
detected_atstring
Quando o chargeback foi detectado, RFC 3339.
due_atstring
Prazo para enviar a defesa (7 dias após a detecção). Passado o prazo sem envio, o caso vira expired.
submitted_atstring
Quando a defesa foi enviada. Omitido antes.
submitted_byuuid
Usuário que enviou. Omitido antes.
resolved_atstring
Quando o caso foi resolvido. Omitido antes.
created_atstring
Criação do caso, RFC 3339.
updated_atstring
Última alteração, RFC 3339.
totalinteger
Total de casos que casam com o filtro.

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"}

Indicadores de chargeback

Resumo da fila de casos: quantos estão abertos, quantos vencem em até 2 dias, ganhos, perdidos, a taxa de chargeback e o valor perdido.

GET/api/v1/vendor/chargebacks/statsSeller

Indicadores dos chargebacks do seller

Cabeçalhos

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

Exemplo de requisição

Resposta

200Indicadores

Campos da resposta

openinteger
Casos open ou evidence_ready.
due_sooninteger
Desses, os que vencem em menos de 2 dias.
woninteger
Casos ganhos.
lostinteger
Casos perdidos.
chargeback_ratenumber
Casos divididos pelos pedidos pagos do seller nos últimos 30 dias (fração, 0.012 = 1,2%).
lost_amount_centsinteger
Soma dos valores dos casos perdidos, em centavos.

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"}

Ver um chargeback

Devolve o caso e as evidências que a plataforma juntou: retrato do pedido, análise antifraude, histórico do cliente, rastreio e nota fiscal. Evidência com available: false ainda não existe (por exemplo o rastreio de um pedido sem envio).

GET/api/v1/vendor/chargebacks/{id}Seller

Caso de chargeback com o dossiê de provas

Cabeçalhos

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

Parâmetros de caminho

iduuidobrigatório
Id do caso de chargeback.

Exemplo de requisição

Resposta

200Caso e evidências

Campos da resposta

caseobject

O caso (mesmos campos da listagem).

iduuid
Id do caso.
order_iduuid
Pedido contestado.
gatewaystring
Gateway que avisou (por exemplo pagarme, stripe).
gateway_dispute_idstring
Id da contestação no gateway. Omitido se não há.
amount_centsinteger
Valor contestado, em centavos.
reasonstring
Motivo informado pelo gateway. Omitido se vazio.
classificationstring
Classificação dada pelo seller ou pela loja (texto livre, por exemplo fraud). Omitido se vazio.
statusstring
openevidence_readysubmittedwonlostresolved_refundedexpired
Situação do caso.
vendor_iduuid
Seller dono do caso.
return_iduuid
Devolução ligada ao caso. Omitido se não há.
detected_atstring
Quando o chargeback foi detectado, RFC 3339.
due_atstring
Prazo para enviar a defesa (7 dias após a detecção). Passado o prazo sem envio, o caso vira expired.
submitted_atstring
Quando a defesa foi enviada. Omitido antes.
submitted_byuuid
Usuário que enviou. Omitido antes.
resolved_atstring
Quando o caso foi resolvido. Omitido antes.
created_atstring
Criação do caso, RFC 3339.
updated_atstring
Última alteração, RFC 3339.
evidencesobject[]

Dossiê de provas.

iduuid
Id da evidência.
case_iduuid
Caso.
kindstring
order_snapshotfraud_analysiscustomer_historytrackingnfe
Tipo da evidência.
payloadobject
Dados da evidência; o formato depende do kind.
file_urlstring
Arquivo anexado, quando houver.
availableboolean
Se a evidência pôde ser reunida.
created_atstring
Criação, RFC 3339.

Erros

StatusQuandoCorpo de exemplo
404O caso não existe ou é de outro seller (a plataforma não diferencia).{"error":"chargeback case not found"}
500id não é um UUID válido (hoje volta 500, a mensagem está em detail).{"error":"failed to load chargeback","detail":"o valor \"xyz\" não é um uuid válido..."}
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"}

Atualizar um chargeback

O seller classifica o caso e move sua situação: marca como enviado (submitted, grava data e autor) ou registra o desfecho (won, lost, resolved_refunded, que gravam resolved_at e avisam a loja). O motivo (reason) e o valor (amount_cents) só a loja altera: enviar qualquer um dos dois dá 403.

PUT/api/v1/vendor/chargebacks/{id}Seller

Classificar o caso ou registrar sua situação

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 do caso de chargeback.

Corpo da requisição

classificationstring
Classificação do caso (texto livre).
statusstring
Nova situação. submitted, won, lost e resolved_refunded têm efeitos próprios. Outro texto é gravado como veio, sem validação.

Exemplo de requisição

Resposta

200Caso atualizado

Campos da resposta

iduuid
Id do caso.
order_iduuid
Pedido contestado.
gatewaystring
Gateway que avisou (por exemplo pagarme, stripe).
gateway_dispute_idstring
Id da contestação no gateway. Omitido se não há.
amount_centsinteger
Valor contestado, em centavos.
reasonstring
Motivo informado pelo gateway. Omitido se vazio.
classificationstring
Classificação dada pelo seller ou pela loja (texto livre, por exemplo fraud). Omitido se vazio.
statusstring
openevidence_readysubmittedwonlostresolved_refundedexpired
Situação do caso.
vendor_iduuid
Seller dono do caso.
return_iduuid
Devolução ligada ao caso. Omitido se não há.
detected_atstring
Quando o chargeback foi detectado, RFC 3339.
due_atstring
Prazo para enviar a defesa (7 dias após a detecção). Passado o prazo sem envio, o caso vira expired.
submitted_atstring
Quando a defesa foi enviada. Omitido antes.
submitted_byuuid
Usuário que enviou. Omitido antes.
resolved_atstring
Quando o caso foi resolvido. Omitido antes.
created_atstring
Criação do caso, RFC 3339.
updated_atstring
Última alteração, RFC 3339.

Erros

StatusQuandoCorpo de exemplo
400Corpo inválido ou falha ao gravar.{"error":"invalid request body","detail":"..."}
403Enviou reason ou amount_cents, que são só da loja.{"error":"chargeback_fact_admin_only","detail":"chargeback: reason e amount_cents só podem ser alterados pelo admin da loja"}
404O caso não existe ou é de outro seller (a plataforma não diferencia).{"error":"chargeback case not found"}
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

  • Disputas com o comprador
  • Visão geral
Anterior
Pagar.me: transferência automática
Próxima
Disputas com o comprador
Nesta página
  • Listar chargebacks
  • Exemplo de requisição
  • Resposta
  • Erros
  • Indicadores de chargeback
  • Exemplo de requisição
  • Resposta
  • Erros
  • Ver um chargeback
  • Exemplo de requisição
  • Resposta
  • Erros
  • Atualizar um chargeback
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
bash
curl "$BASE_URL/api/v1/vendor/chargebacks?status=open&page=1" \
  -H "Authorization: Bearer $TOKEN"
bash
curl "$BASE_URL/api/v1/vendor/chargebacks/stats" \
  -H "Authorization: Bearer $TOKEN"
bash
curl "$BASE_URL/api/v1/vendor/chargebacks/e3a01a16-bf25-496d-899d-0418644f4cda" \
  -H "Authorization: Bearer $TOKEN"
bash
curl -X PUT "$BASE_URL/api/v1/vendor/chargebacks/e3a01a16-bf25-496d-899d-0418644f4cda" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "classification": "fraud",
  "status": "submitted"
}'
json
{
  "cases": [
    {
      "id": "e3a01a16-bf25-496d-899d-0418644f4cda",
      "order_id": "f1b696f9-7674-480d-96a6-5ec81efc8246",
      "gateway": "pagarme",
      "gateway_dispute_id": "dp_1234",
      "amount_cents": 50000,
      "reason": "fraud",
      "classification": "fraud",
      "status": "open",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "detected_at": "2026-10-05T05:23:08Z",
      "due_at": "2026-10-12T05:23:08Z",
      "created_at": "2026-10-05T05:23:08Z",
      "updated_at": "2026-10-05T05:23:08Z"
    }
  ],
  "total": 1
}
json
{
  "open": 2,
  "due_soon": 1,
  "won": 3,
  "lost": 1,
  "chargeback_rate": 0.012,
  "lost_amount_cents": 50000
}
json
{
  "case": {
    "id": "e3a01a16-bf25-496d-899d-0418644f4cda",
    "order_id": "f1b696f9-7674-480d-96a6-5ec81efc8246",
    "gateway": "pagarme",
    "gateway_dispute_id": "dp_1234",
    "amount_cents": 50000,
    "reason": "fraud",
    "classification": "fraud",
    "status": "open",
    "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
    "detected_at": "2026-10-05T05:23:08Z",
    "due_at": "2026-10-12T05:23:08Z",
    "created_at": "2026-10-05T05:23:08Z",
    "updated_at": "2026-10-05T05:23:08Z"
  },
  "evidences": [
    {
      "id": "446681d5-59e3-4988-92d6-1cd9ba69148f",
      "case_id": "e3a01a16-bf25-496d-899d-0418644f4cda",
      "kind": "order_snapshot",
      "payload": {
        "status": "O",
        "created_at": "2026-10-04T19:00:45Z",
        "total_cents": 3963,
        "amount_cents": 50000,
        "order_number": "VND-20261004-04314",
        "payment_status": "P"
      },
      "available": true,
      "created_at": "2026-10-05T07:11:01Z"
    },
    {
      "id": "989781e6-f4e5-4287-a5ee-40d57c29dc5b",
      "case_id": "e3a01a16-bf25-496d-899d-0418644f4cda",
      "kind": "tracking",
      "payload": {},
      "available": false,
      "created_at": "2026-10-05T07:11:01Z"
    }
  ]
}
json
{
  "id": "e3a01a16-bf25-496d-899d-0418644f4cda",
  "order_id": "f1b696f9-7674-480d-96a6-5ec81efc8246",
  "gateway": "pagarme",
  "gateway_dispute_id": "dp_1234",
  "amount_cents": 50000,
  "reason": "fraud",
  "classification": "fraud",
  "status": "submitted",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "detected_at": "2026-10-05T05:23:08Z",
  "due_at": "2026-10-12T05:23:08Z",
  "created_at": "2026-10-05T05:23:08Z",
  "updated_at": "2026-10-05T05:23:08Z",
  "submitted_at": "2026-10-08T10:00:00Z",
  "submitted_by": "b00d3e7c-d5b4-4942-827a-06e2c43645af"
}