Chargeback API

Disputas

v2026-02-01OAS 3.1

Introdução

Fornecemos uma API para consulta e gestão de chargebacks, permitindo listar, filtrar e acompanhar eventos, além de executar ações dentro do fluxo de contestação.

Ao integrar a API, os eventos de chargeback passam a ficar disponíveis de forma estruturada, viabilizando automação da operação e integração com sistemas internos.

Hosts

Production: https://api.stone.com.br

Autenticação

A autenticação é feita via chave estática. O processo de obtenção da chave é idêntico ao de outros endpoints/APIs já expostas pelo Pagar.me.

  • Escopo necessário: Transacional.
  • Permissão: Somente leitura.

Nota: Não é necessária uma chave exclusiva para esta API. Chaves existentes com este escopo e permissão podem ser reutilizadas.

O envio da credencial segue o padrão definido na Documentação do Pagar.me.

Alguma dúvida na integração ou feedback?

Mande um email para chargeback.tech@stone.com.br.

API Base URL
  • Server 1:https://api.stone.com.br

    production

  • Server 2:https://sandbox.api.stone.com.br

    sandbox

Disputas

Operações relacionadas à busca de disputas de chargeback. Aqui é possível ver o estado atual da disputa, histórico de eventos daquela disputa, dentre outras informações relevantes.

Lista disputas de chargeback

Retorna uma lista paginada de disputas com base nos filtros fornecidos.

get

Query Parameters

createdAt__lteAny Of

Filtra valores menores ou iguais à data fornecida. A API aceita datetimes em RFC3339 com timezone (ex.: 2026-02-26T20:02:18Z) ou datas no formato YYYY-MM-DD.

Variant 1string(date-time)

Example:2026-02-26T20:02:18Z

createdAt__gteAny Of

Filtra valores maiores ou iguais à data fornecida. A API aceita datetimes em RFC3339 com timezone (ex.: 2026-02-26T20:02:18Z) ou datas no formato YYYY-MM-DD.

Variant 1string(date-time)

Example:2026-02-26T20:02:18Z

statusstring

Filtra pelo status da disputa.

reason.codeinteger

Filtra pelo código do motivo do chargeback.

networkstring

Filtra pela bandeira do cartão.

cyclearray[string]

Filtra pelo ciclo de chargeback em que a disputa está. Aceita múltiplos valores.

Allowed values:FIRSTSECOND

Example:FIRST

cycleStatusarray[string]

Filtra pelo status da disputa dentro do ciclo atual. Aceita múltiplos valores.

Allowed values:RECEIVEDGUARANTEE_ANALYZEDEVIDENCE_RECEIVEDREPRESENTEDREVERSEDWONLOSTEXPIRED

Example:RECEIVED

forwardCursorstring

Identificador para avançar na paginação.

limitinteger

Número máximo de registros a serem retornados.

Default:5

<= 100

Response

application/json

Lista de disputas retornada com sucesso.

dataarray[object]
Show Child Parameters
pageobject
Show Child Parameters
get/v1/disputes
 
application/json

Consulta uma disputa específica

get

Path Parameters

dispute_idstringrequired

ID único da disputa.

Response

application/json

Detalhes da disputa encontrados.

Dispute

disputeIdstring

ID único da disputa.

transactionIdstring

ID da transação associada à disputa.

chargeIdstring

ID da cobrança associada à disputa.

createdAtstring(date-time)

Data da criação da disputa.

updatedAtstring(date-time)

Data da última atualização da disputa.

responseDeadlinestring(date-time)

Data limite para o envio de evidências por parte do lojista.

chargebackAmountobject

Valor do chargeback.

Show Child Parameters
debitedAmountobject

Valor debitado do lojista.

Show Child Parameters
statusstring

Status atual da disputa.

Valores possíveis:

Status Code Significado
REVERSED 93 Chargeback revertido — o valor contestado foi estornado ao lojista.

Allowed values:WAITING_MERCHANT_EVIDENCESWAITING_ACQUIRER_ANALYSISMERCHANT_EVIDENCE_DEADLINE_EXPIREDWAITING_ISSUERLOSTWONDEADLINE_EXPIREDREVERSED

reasonobject

Motivo do pedido de chargeback.

Show Child Parameters
stagestring

Estágio do ciclo de chargeback.

cyclestring

Ciclo de chargeback em que a disputa está. O campo é omitido da resposta para
disputas coletadas antes de o ciclo passar a ser registrado — não é retornado como
null.

Allowed values:FIRSTSECOND

Example:FIRST

cycleStatusstring

Status da disputa dentro do ciclo atual. É independente de status, que acompanha o
ciclo de vida da disputa como um todo. O campo é omitido da resposta para disputas
coletadas antes de o ciclo passar a ser registrado — não é retornado como null.

Allowed values:RECEIVEDGUARANTEE_ANALYZEDEVIDENCE_RECEIVEDREPRESENTEDREVERSEDWONLOSTEXPIRED

Example:RECEIVED

networkstring

Bandeira do cartão.

institutionstring

Instituição onde a transação foi processado.

Allowed values:STONEPAGAR.ME

eventsarray[object]

Lista de eventos relacionados à disputa.

Show Child Parameters
guaranteeobject

Resultado da análise de garantia da disputa. O campo é omitido da resposta
quando a disputa não possui garantia — não é retornado como null.

Show Child Parameters
get/v1/disputes/{dispute_id}
 
application/json

Envia evidências de defesa para uma disputa

Precisa de ajuda com a integração? Manda um email para chargeback.tech@stone.com.br.

Submete um ou mais arquivos PDF como evidências de defesa para uma disputa de chargeback existente,
em um único multipart. A validação é all-or-nothing — se qualquer arquivo falhar (MIME, tamanho,
extensão, limite de páginas), todos são rejeitados.

Limites:

  • Por arquivo: ≤ 2 MB.
  • Por disputa: máximo de 10 páginas no total (somatório de páginas entre todos os arquivos enviados — ex.: 1 PDF de 10 páginas já ocupa o limite, então não cabe mais nenhum arquivo).
  • Por requisição: ≤ 11 MB no total.
post

Path Parameters

dispute_idstringrequired

ID único da disputa.

Body

multipart/form-data
filesarray[string](binary)required

Um ou mais arquivos PDF. Use o nome de campo files em cada parte do multipart.

Response

application/json

Evidência recebida com sucesso.

disputeIdstring
statusstring

Example:received

messagestring

Example:Evidence received successfully.

post/v1/disputes/{dispute_id}/evidences

Body

No file selected
 
Error initializing code snippet
application/json