--- title: "Lista disputas de chargeback" url: "https://devcenter.stone.com.br/apis/chargeback-api-v2026-02-01/versions/277b2a7a-855b-475c-a343-f67650befb83/paths/v1-disputes/get" --- > Full API specification: https://devcenter.stone.com.br/apis/chargeback-api-v2026-02-01/versions/277b2a7a-855b-475c-a343-f67650befb83.md # Lista disputas de chargeback `GET` `/v1/disputes` Retorna uma lista paginada de disputas com base nos filtros fornecidos. ## Query parameters - `createdAt__lte` (optional) - 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`. - `createdAt__gte` (optional) - 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`. - `status` (string, optional) - Filtra pelo status da disputa. - `reason.code` (integer, optional) - Filtra pelo código do motivo do chargeback. - `network` (string, optional) - Filtra pela bandeira do cartão. - `cycle` (array, optional) - Filtra pelo ciclo de chargeback em que a disputa está. Aceita múltiplos valores. - `cycleStatus` (array, optional) - Filtra pelo status da disputa dentro do ciclo atual. Aceita múltiplos valores. - `forwardCursor` (string, optional) - Identificador para avançar na paginação. - `limit` (integer, optional) - Número máximo de registros a serem retornados. ## Responses - `200` - Lista de disputas retornada com sucesso. - `400` - Parâmetros de filtro inválidos. - `500` - Erro inesperado ao processar a requisição. ## OpenAPI definition ```yaml openapi: 3.1.0 info: title: Disputas version: v2026-02-01 servers: - url: https://api.stone.com.br description: production - url: https://sandbox.api.stone.com.br description: sandbox paths: /v1/disputes: get: summary: Lista disputas de chargeback description: Retorna uma lista paginada de disputas com base nos filtros fornecidos. tags: - Disputas parameters: - name: createdAt__lte in: query description: > 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`. schema: anyOf: - type: string format: date-time example: 2026-02-26T20:02:18Z - type: string format: date example: 2026-02-26 - name: createdAt__gte in: query description: > 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`. schema: anyOf: - type: string format: date-time example: 2026-02-26T20:02:18Z - type: string format: date example: 2026-02-26 - name: status in: query description: Filtra pelo status da disputa. schema: type: string - name: reason.code in: query description: Filtra pelo código do motivo do chargeback. schema: type: integer - name: network in: query description: Filtra pela bandeira do cartão. schema: type: string - name: cycle in: query description: > Filtra pelo ciclo de chargeback em que a disputa está. Aceita múltiplos valores. schema: type: array items: type: string enum: - FIRST - SECOND example: - FIRST - name: cycleStatus in: query description: > Filtra pelo status da disputa dentro do ciclo atual. Aceita múltiplos valores. schema: type: array items: type: string enum: - RECEIVED - GUARANTEE_ANALYZED - EVIDENCE_RECEIVED - REPRESENTED - REVERSED - WON - LOST - EXPIRED example: - RECEIVED - name: forwardCursor in: query description: Identificador para avançar na paginação. schema: type: string - name: limit in: query description: Número máximo de registros a serem retornados. schema: type: integer default: 5 maximum: 100 responses: "200": description: Lista de disputas retornada com sucesso. content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/Dispute" page: type: object properties: forwardCursor: type: - string - "null" description: Identificador para o inicio da próxima página. examples: default: summary: Exemplo de listagem de disputas value: data: - disputeId: "12345" transactionId: "67890" chargeId: ch_xpto createdAt: 2026-02-20T14:30:00Z updatedAt: 2026-02-22T10:15:00Z responseDeadline: 2026-03-05T23:59:59Z chargebackAmount: amount: "150.47" currencyCode: BRL debitedAmount: amount: "150.47" currencyCode: BRL status: WAITING_MERCHANT_EVIDENCES reason: code: "4853" description: FRAUD stage: CHARGEBACK cycle: FIRST cycleStatus: RECEIVED network: VISA institution: STONE events: - type: FIRST_CHARGEBACK createdAt: 2026-02-20T14:30:00Z - type: DISPUTE_NOTIFIED createdAt: 2026-02-20T14:35:00Z page: forwardCursor: eyJpZCI6MTIzNDV9 "400": description: Parâmetros de filtro inválidos. content: application/problem+json: schema: $ref: "#/components/schemas/ProblemDetail" example: type: /errors/invalid-request title: Invalid Request status: 400 detail: Could not parse query parameters. instance: /v1/disputes traceId: abc-123-trace "500": description: Erro inesperado ao processar a requisição. content: application/problem+json: schema: $ref: "#/components/schemas/ProblemDetail" example: type: /errors/internal-server-error title: Internal Server Error status: 500 detail: An unexpected error occurred on the server. Please try again later. If the issue persists, contact support with the trace ID. instance: /v1/disputes traceId: abc-123-trace components: schemas: Dispute: type: object properties: disputeId: type: string description: ID único da disputa. transactionId: type: string description: ID da transação associada à disputa. chargeId: type: string description: ID da cobrança associada à disputa. createdAt: type: string format: date-time description: Data da criação da disputa. updatedAt: type: string format: date-time description: Data da última atualização da disputa. responseDeadline: type: string format: date-time description: Data limite para o envio de evidências por parte do lojista. chargebackAmount: allOf: - $ref: "#/components/schemas/Amount" - description: Valor do chargeback. debitedAmount: allOf: - $ref: "#/components/schemas/Amount" - description: Valor debitado do lojista. status: type: string enum: - WAITING_MERCHANT_EVIDENCES - WAITING_ACQUIRER_ANALYSIS - MERCHANT_EVIDENCE_DEADLINE_EXPIRED - WAITING_ISSUER - LOST - WON - DEADLINE_EXPIRED - REVERSED description: > Status atual da disputa. **Valores possíveis:** | Status | Code | Significado | |---|---|---| | `REVERSED` | 93 | Chargeback revertido — o valor contestado foi estornado ao lojista. | reason: type: object properties: code: type: string description: Código do motivo do chargeback. description: type: string enum: - FRAUD - PROCESSING_ERROR - COMMERCIAL_DISPUTE - AUTHORIZATION description: Descrição do motivo do chargeback. description: Motivo do pedido de chargeback. stage: type: string description: Estágio do ciclo de chargeback. cycle: type: string enum: - FIRST - SECOND description: > 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`. example: FIRST cycleStatus: type: string enum: - RECEIVED - GUARANTEE_ANALYZED - EVIDENCE_RECEIVED - REPRESENTED - REVERSED - WON - LOST - EXPIRED description: > 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`. example: RECEIVED network: type: string description: Bandeira do cartão. institution: type: string enum: - STONE - PAGAR.ME description: Instituição onde a transação foi processado. events: type: array items: $ref: "#/components/schemas/Event" description: Lista de eventos relacionados à disputa. guarantee: type: object description: > 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`. properties: status: type: string description: "Situação da garantia (ex.: `GUARANTEED`, `NOT_GUARANTEED`)." example: NOT_GUARANTEED reason: type: - string - "null" description: Motivo pelo qual a garantia foi negada. É `null` quando a disputa está garantida. example: deadline_expired updatedAt: type: string format: date-time description: Data da última atualização da análise de garantia. Omitido quando não informado. example: 2026-04-22T10:00:00Z ProblemDetail: type: object description: > Estrutura de erro padronizada conforme RFC 9457 (Problem Details for HTTP APIs). Content-Type da resposta: `application/problem+json`. properties: type: type: string description: "Identificador relativo do tipo de erro (ex.: `/errors/resource-not-found`)." example: /errors/resource-not-found title: type: string description: Resumo curto e legível do tipo de erro (em inglês). example: Resource Not Found status: type: integer description: Código de status HTTP correspondente. example: 404 detail: type: string description: Explicação humana específica desta ocorrência (em inglês). example: Dispute '12332125088527' could not be found. instance: type: string description: Caminho do recurso requisitado. example: /v1/disputes/12332125088527 traceId: type: string description: Identificador da requisição (echo de `X-Request-Id`), útil para rastrear a requisição em caso de suporte. example: abc-123-trace Amount: type: object properties: amount: type: string example: "150.47" currencyCode: type: string example: BRL Event: type: object properties: type: type: string enum: - FIRST_CHARGEBACK - FIRST_CHARGEBACK_REVERSED - DISPUTE_NOTIFIED - MERCHANT_EVIDENCE_RECEIVED - EVIDENCE_ANALYSIS_ACCEPTED - EVIDENCE_ANALYSIS_DENIED - LOST_DISPUTE description: Tipo do evento relacionado à disputa. createdAt: type: string format: date-time description: Data da criação do evento. ```