Contestações e disputas

Para saber o que precisa ser defendido agora, use a fila em vez de varrer transações uma a uma:

A fila de disputas (Dismart)

Para saber o que precisa ser defendido agora, use a fila em vez de varrer transações uma a uma:

GET /dismart/disputes
GET /dismart/disputes/{disputeId}

Aceita status (open | closed), transactionId, limit/offset. Vem ordenada da mais antiga aberta primeiro — a que está para vencer, não a mais recente. Cada item traz:

Campo	Para quê
`reason` · `reasonCode` · `reasonDescription`	O motivo da contestação — é ele que decide quais documentos reunir
`deadline`	O seu prazo de envio (`hoursRemaining`, `expired`, `urgent`)
`defensible`	Ainda vale a pena enviar. `false` = caso decidido ou janela encerrada na adquirente
`evidence`	Quais tipos de comprovante já foram anexados
`awaitingDocuments`	Defensável e sem nenhum comprovante — a lista de trabalho
`caseNumber`	Como a defesa é identificada pela adquirente

O summary traz awaitingDocuments/urgent/open sobre o conjunto filtrado, não sobre a página.

A fila é somente leitura. O envio dos documentos continua sendo o POST descrito abaixo.

Quando o titular do cartão contesta uma cobrança junto ao emissor, a transação entra no status dispute (a disputa é aberta a partir do webhook da adquirente). Este endpoint permite que o vendedor submeta evidências para defender a transação.

⚠️ Cada submissão substitui todo o conjunto de evidências anterior da disputa (é uma sobrescrita completa, não um acréscimo). Envie sempre o conjunto completo de documentos.

Precauções

A transação precisa estar em dispute e já ter uma disputa aberta (caso contrário, retorna 422/404).
Envie o maior número possível de documentos relevantes — a ausência de documentação adequada pode encerrar a disputa em favor do cliente.
Há um prazo para enviar os documentos, contado a partir da abertura da disputa. Não presuma o valor: cada disputa devolve o seu prazo em deadline (ver O objeto disputes[]). Envie antes de deadline.hoursRemaining chegar a zero.
O ID da transação é sensível a maiúsculas e minúsculas (tra_... ou trx_...).

Requisição

POST /v1/transactions/{transactionId}/dispute

Parâmetros de URL

Parâmetro	Tipo	Obrigatório	Descrição
`transactionId`	string	Sim	Identificador da transação em disputa

Parâmetros do Corpo da Requisição

Parâmetro	Tipo	Obrigatório	Descrição
`documents`	array	Sim	Lista de documentos de evidência (mínimo 1, máximo 50)
`description`	string	Não	Descrição da situação (máx. 2000)
`returnEmail`	string	Não	Email para notificações sobre a disputa (máx. 255)

Objeto Document

Campo	Tipo	Obrigatório	Descrição
`type`	string	Sim	Tipo do documento (ver tabela abaixo)
`assetUrl`	string (url)	Condicional	URL pública do arquivo. Um entre `assetUrl` e `assetId`
`assetId`	string (`asset_…`)	Condicional	Arquivo que você subiu para nós (`POST /v1/assets/uploads` → `/confirm`). Um entre `assetUrl` e `assetId`
`description`	string	Não	Descrição do documento (máx. 1000)
`shippingDate`	string	Não	Data de envio (apenas para `shipmentProof`)
`trackingCode`	string	Não	Código de rastreamento (apenas para `shipmentProof`)
`carrier`	string	Não	Transportadora (apenas para `shipmentProof`)
`authentication`	object	Não	Credenciais para acessar o documento (`username`, `password`, `token`)

Tipos de Documentos (type)

Tipo	Descrição
`deliveryProof`	Comprovante de entrega
`shipmentProof`	Comprovante de envio
`deliveryReceipt`	Recibo de entrega
`fiscalDocument`	Documento fiscal (nota fiscal)
`communicationProof`	Comprovante de comunicação com o cliente

Exemplo de Requisição

{
  "returnEmail": "[email protected]",
  "description": "Disputa referente a inconsistência alegada na entrega do pedido.",
  "documents": [
    {
      "type": "deliveryProof",
      "assetUrl": "https://exemplo.com/comprovante-entrega.png",
      "description": "Registro da assinatura no momento da entrega.",
      "authentication": { "token": "bearer ey..." }
    },
    {
      "type": "shipmentProof",
      "assetUrl": "https://exemplo.com/comprovante-envio.png",
      "description": "Comprovante de envio da encomenda.",
      "shippingDate": "2026-06-10",
      "trackingCode": "CA1234CA",
      "carrier": "Correios"
    },
    {
      "type": "fiscalDocument",
      "assetUrl": "https://exemplo.com/nota-fiscal.pdf",
      "description": "Nota fiscal da compra."
    }
  ]
}

Campo	Tipo	Descrição
`status`	string	`open` (ainda defensável) ou `closed` (já decidida — evidência enviada aqui não muda nada)
`reason`	string	Família do motivo informado pela adquirente (ex.: `fraud`)
`reasonCode`	string	Código do motivo (ex.: `F01`) — chave estável para mapear o checklist de documentos
`reasonDescription`	string	Descrição legível do motivo
`openedAt`	datetime	Abertura da disputa — é daqui que o prazo conta
`closedAt`	datetime	Encerramento, quando já decidida (`null` enquanto aberta)
`deadline.deadlineAt`	datetime	Instante em que a janela de defesa fecha
`deadline.hoursRemaining`	integer	Horas restantes (negativo depois de vencido)
`deadline.expired`	boolean	Janela fechada — a adquirente não aceitará mais evidências
`deadline.urgent`	boolean	Ainda defensável, mas dentro do limiar de urgência

Leia o prazo em horas, não em dias: a janela é curta, e "aberta há 2 dias" não distingue um caso com 10 horas de vida de um já encerrado para envio. deadline é o prazo desta disputa — não presuma um valor fixo. É null apenas quando a adquirente não informou a data de abertura.

{
  "id": "tra_123456789",
  "customId": "E5D4C3B2A1",
  "amount": 1229,
  "originalAmount": 1229,
  "status": "dispute",
  "method": "credit",
  "currency": "BRL",
  "payment": {
    "provider": "selectwin",
    "version": "1.1",
    "refused": null,
    "reusable": false,
    "cardFirstDigits": "553121",
    "cardLastDigits": "4567",
    "cardBrand": "Mastercard",
    "cardRegistered": true,
    "installments": 1,
    "expirationDate": null,
    "paidAt": "2026-02-04T12:48:08.000Z",
    "allowRenewPayment": false,
    "invoiceLink": "https://selectwin.io/invoices/tra_123456789"
  },
  "discount": null,
  "discounts": null,
  "customer": {
    "id": "cus_123456789",
    "firstName": "Ariadini",
    "lastName": "Priscila Gissi",
    "email": "[email protected]",
    "birthdate": null,
    "gender": null,
    "document": { "type": "cpf", "number": "30998527831" },
    "telephone": {
      "countryCode": "55",
      "areaCode": "12",
      "number": "997706389",
      "line": "5512997706389"
    },
    "available": true,
    "delinquent": false,
    "externalReference": null,
    "additionalEmails": null,
    "metadata": null,
    "updatedAt": "2026-02-04T13:58:09.000Z",
    "createdAt": "2026-02-03T21:29:11.000Z"
  },
  "billing": {
    "address": {
      "id": "addr_123456789",
      "ownerId": "cus_123456789",
      "ownerType": "customer",
      "street": "Avenida Paulista",
      "number": "302",
      "complement": "Conjunto 3B, Bloco 3",
      "district": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "postcode": "01310000",
      "country": "BR",
      "latitude": null,
      "longitude": null,
      "line": "Avenida Paulista, 302 - Conjunto 3B, Bloco 3, Bela Vista, São Paulo - SP, 01310000, BR",
      "line1": "Avenida Paulista, 302",
      "line2": "Conjunto 3B, Bloco 3",
      "line3": "Bela Vista",
      "updatedAt": "2026-02-04T13:58:10.000Z",
      "createdAt": "2026-02-03T21:29:11.000Z"
    }
  },
  "shipping": null,
  "externalReference": null,
  "shippable": true,
  "spplited": false,
  "items": null,
  "receivables": [
    {
      "id": "rec_123456789",
      "recipient": "bus_123456789",
      "split": null,
      "status": "pending",
      "amount": 1229,
      "grossAmount": 1229,
      "anticipationFee": 0,
      "installmentNumber": 1,
      "description": null,
      "currency": "BRL",
      "authorizationCode": null,
      "paidAt": null,
      "refundedAt": null,
      "canceledAt": null,
      "expectedOn": null,
      "liable": true,
      "chargeProcessingFee": true,
      "updatedAt": "2026-02-04T12:48:08.000Z",
      "createdAt": "2026-02-04T12:48:08.000Z"
    }
  ],
  "splits": null,
  "refunds": null,
  "disputes": [
    {
      "id": "trd_123456789",
      "returnEmail": "[email protected]",
      "description": "Disputa referente a inconsistência alegada na entrega do pedido.",
      "status": "open",
      "reason": "fraud",
      "reasonCode": "F01",
      "reasonDescription": "unauthorized",
      "openedAt": "2026-02-04T18:00:00.000Z",
      "closedAt": null,
      "deadline": {
        "deadlineAt": "2026-02-07T18:00:00.000Z",
        "hoursRemaining": 22,
        "expired": false,
        "urgent": true
      },
      "deliveryProof": [
        {
          "assetUrl": "https://exemplo.com/comprovante-entrega.png",
          "description": "Registro da assinatura no momento da entrega.",
          "authentication": { "token": "bearer ey..." }
        }
      ],
      "shipmentProof": [
        {
          "carrier": "Correios",
          "assetUrl": "https://exemplo.com/comprovante-envio.png",
          "description": "Comprovante de envio da encomenda.",
          "shippingDate": "2026-06-10",
          "trackingCode": "CA1234CA"
        }
      ],
      "deliveryReceipts": null,
      "fiscalDocuments": [
        {
          "assetUrl": "https://exemplo.com/nota-fiscal.pdf",
          "description": "Nota fiscal da compra."
        }
      ],
      "communicationProof": null,
      "updatedAt": "2026-02-04T19:03:52.000Z",
      "createdAt": "2026-02-04T19:03:52.000Z"
    }
  ],
  "timeline": [
    {
      "id": "tl_900",
      "message": "Dispute evidence submitted",
      "details": null,
      "type": "dispute",
      "updatedAt": "2026-02-04T19:03:52.000Z",
      "createdAt": "2026-02-04T19:03:52.000Z"
    }
  ],
  "callback": null,
  "metadata": { "storeId": "str_123456", "storeName": "marketplace" },
  "updatedAt": "2026-02-04T19:19:13.000Z",
  "createdAt": "2026-02-04T12:48:07.000Z",
  "merchant": {
    "name": "Selectwin Corp",
    "merchantId": "bus_123456789",
    "isSubAccount": false
  },
  "_links": {
    "self": {
      "href": "https://api.selectwin.io/v1/transactions/tra_123456789",
      "method": "GET",
      "description": "Read a transaction."
    },
    "refund": {
      "href": "https://api.selectwin.io/v1/transactions/tra_123456789/refund",
      "method": "POST",
      "description": "Refund the transaction."
    },
    "capture": {
      "href": "https://api.selectwin.io/v1/transactions/tra_123456789/capture",
      "method": "POST",
      "description": "Capture the transaction."
    }
  }
}

Erros

`error.code`	HTTP	Quando
`transactionNotInDispute`	422	A transação não está em `dispute`
`disputeNotFound`	404	Não há disputa aberta para esta transação
`disputeAssetNotFound`	422	Um `assetId` enviado não existe ou não é seu
`transactionNotFound`	404	Transação inexistente

Melhores Práticas

Responda rapidamente para maximizar as chances de resolução favorável.
Envie o conjunto completo de evidências em cada submissão (a submissão sobrescreve a anterior).
Inclua comprovantes de entrega com assinatura e dados de rastreamento.
Documente a comunicação com o cliente.
Implemente medidas preventivas (descrições claras de produto, políticas transparentes) para reduzir disputas.

Contestações e disputas

A fila de disputas (Dismart)

Visão Geral

Precauções

Requisição

Parâmetros de URL

Parâmetros do Corpo da Requisição

Objeto Document

Tipos de Documentos (type)

Exemplo de Requisição

Resposta

Sucesso (HTTP 200 OK)

O objeto disputes[]

Erros

Melhores Práticas

On this page