Chargeback API
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
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