Chargeback API
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
ValidatedFile
objectResultado 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
TransactionBatchError
objectFalha de validação aplicada ao conjunto de arquivos de uma mesma transação
(independente de cada arquivo ser individualmente válido), ex.: a soma de
páginas dos arquivos enviados excede o limite de 10 páginas por transação.
transaction_idstring
Transação alvo da regra de batch.
Example:12332125088527
filenamesarray[string]
Arquivos considerados no batch desta transação.
Example:12332125088527.pdf, dummy_print.pdf
errorsarray[string]
Código do erro de validação de batch da transação.
Allowed values:MAX_ITEMS_PER_TRANSACTION_QUANTITY_EXCEEDED
Example:MAX_ITEMS_PER_TRANSACTION_QUANTITY_EXCEEDED
Example