Chargeback API
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
FileValidationProblemDetail
objectExtensão do ProblemDetail (RFC 9457) específica para o erro /errors/invalid-file
quando a submissão de evidência é rejeitada por validação. Inclui o
detalhamento por arquivo (validated_files) e a lista de falhas agregadas por
transação (transaction_batch_errors). O detail é um sumário legível dos
códigos de erro retornados.
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
validated_filesarray[object]required
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).
Show Child Parameters
transaction_batch_errorsarray[object]
Falha 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.
Show Child Parameters
Example
Dispute
objectdisputeIdstring
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
Example
Amount
objectamountstring
Example:150.47
currencyCodestring
Example:BRL
Example