Chargeback API

Disputas

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

ProblemDetail

object

Estrutura 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

ValidatedFile

object

Resultado da validação de um único arquivo enviado como evidência. Quando
uma submissão é rejeitada, cada arquivo é reportado neste formato,
listando todos os códigos de erro que ele violou (vazio quando o arquivo
em si está OK, mesmo que a transação tenha falhado por outro motivo).

namestring

Nome do arquivo conforme enviado no multipart.

Example:evidence.pdf

transaction_idstring | null

Identificador da transação associada ao arquivo, quando aplicável.

Example:12332125088527

institutionstring | null

Instituição associada à transação, quando aplicável.

Example:stone

errorsarray[string]

Código do erro de validação do arquivo.

Allowed values:FILE_NAME_IS_NOT_VALIDFILE_SIZE_TOO_SMALLFILE_SIZE_TOO_BIGFILE_MIME_TYPE_NOT_ALLOWEDFILE_EXTENSION_NOT_ALLOWEDDISPUTE_NOT_FOUND_TO_INFORMED_TRANSACTION_IDDISPUTE_STATUS_NOT_ALLOWEDDISPUTE_DOESNT_BELONG_TO_MERCHANT

Example:FILE_MIME_TYPE_NOT_ALLOWED, FILE_SIZE_TOO_BIG

is_valid_fileboolean

Indica se o arquivo passou em todas as regras de validação individuais.

Example