Contestações e disputas

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 subm

Visão Geral

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.
O prazo de contestação costuma ser de até 7 dias após a abertura.
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)	Sim	URL pública do arquivo/documento
`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."
    }
  ]
}

Resposta

Sucesso (HTTP 200 OK)

Retorna a transação completa atualizada, com status: "dispute" e a disputa preenchida em disputes[] (as evidências agrupadas por tipo). A estrutura é a mesma de Consultar.

{
  "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.",
      "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
`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

On this page