Chargeback API
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__lte
Any OfFiltra 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__gte
Any OfFiltra 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
Response
application/json
Lista de disputas retornada com sucesso.
dataarray[object]
Show Child Parameters
pageobject
Show Child Parameters
get/v1/disputes
Query Parameters
application/json
Consulta uma disputa específica
get
Path Parameters
dispute_idstringrequired
ID único da disputa.
Response
application/json
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}
Path Parameters
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
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
Response
application/json
Evidência recebida com sucesso.
disputeIdstring
statusstring
Example:received
messagestring
Example:Evidence received successfully.
post/v1/disputes/{dispute_id}/evidences
Path Parameters
Body
No file selected
Error initializing code snippet
application/json
ProblemDetail
objectEstrutura de erro padronizada conforme RFC 9457 (Problem Details for HTTP APIs).
Content-Type da resposta: application/problem+json.
typestring
Identificador relativo do tipo de erro (ex.: /errors/resource-not-found).
Example:/errors/resource-not-found
titlestring
Resumo curto e legível do tipo de erro (em inglês).
Example:Resource Not Found
statusinteger
Código de status HTTP correspondente.
Example:404
detailstring
Explicação humana específica desta ocorrência (em inglês).
Example:Dispute '12332125088527' could not be found.
instancestring
Caminho do recurso requisitado.
Example:/v1/disputes/12332125088527
traceIdstring
Identificador da requisição (echo de X-Request-Id), útil para rastrear a requisição em caso de suporte.
Example:abc-123-trace
Example