Disputas e MED PIX

Uma disputa ocorre quando um comprador contesta uma cobrança. No PIX, o mecanismo regulatório é o MED (Mecanismo Especial de Devolução do BACEN).

Tipos de Disputa

Tipo	Método	Origem	Voluntário?
MED (PIX)	PIX	BACEN / banco do comprador	Não, regulatório
Disputa manual	PIX	Linka	Aberta pela Linka em casos operacionais

Impacto Financeiro

Ao receber um MED:

O status da transação muda para CHARGEDBACK
O netAmount da transação é debitado imediatamente da sua wallet
Uma disputa MED é criada automaticamente para rastreamento
Você recebe o evento DISPUTE_CREATED via webhook

O débito é imediato e automático. Se a wallet não tiver saldo suficiente, o saldo ficará negativo. Mantenha uma reserva para cobrir eventuais devoluções.

Fluxo Completo

Contestando uma Disputa

Se você acredita que a disputa é indevida, pode contestar enviando evidências para análise.

Identifique a disputa

Você receberá o evento DISPUTE_CREATED no webhook com o disputeId. Guarde este ID.

Evento DISPUTE_CREATED

{
  "eventType": "DISPUTE_CREATED",
  "signature": "v1=...",
  "id": "dispute_uuid_aqui",
  "amount": 15000,
  "status": "OPEN",
  "reason": "Comprador não reconhece a compra",
  "createdAt": "2026-04-09T14:00:00.000Z"
}

Envie o appeal com evidências

Envie as evidências via multipart/form-data. São aceitos até 10 arquivos por disputa.

curl -X POST https://api.linkagateway.com/v1/disputes/appeal \
  -H "x-api-key: {sua_api_key}" \
  -H "Idempotency-Key: {uuid_v4_unico}" \
  -F "disputeId=dispute_uuid_aqui" \
  -F "appealReason=Compra realizada pelo próprio titular. Temos nota fiscal e log de entrega." \
  -F "[email protected]" \
  -F "[email protected]"

const formData = new FormData();
formData.append('disputeId', 'dispute_uuid_aqui');
formData.append('appealReason', 'Compra realizada pelo próprio titular. Temos nota fiscal e log de entrega.');
formData.append('files', file1Blob, 'nota-fiscal.pdf');
formData.append('files', file2Blob, 'comprovante-entrega.pdf');

const response = await fetch('https://api.linkagateway.com/v1/disputes/appeal', {
  method: 'POST',
  headers: {
    'x-api-key': apiKey,
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: formData,
});

const { data } = await response.json();

const formData = new FormData();
formData.append('disputeId', 'dispute_uuid_aqui');
formData.append('appealReason', 'Compra realizada pelo próprio titular. Temos nota fiscal e log de entrega.');
formData.append('files', file1Blob, 'nota-fiscal.pdf');
formData.append('files', file2Blob, 'comprovante-entrega.pdf');

const response = await fetch('https://api.linkagateway.com/v1/disputes/appeal', {
  method: 'POST',
  headers: {
    'x-api-key': apiKey,
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: formData,
});

const { data } = await response.json() as any;

import requests
import uuid

with open('nota-fiscal.pdf', 'rb') as f1, open('comprovante-entrega.pdf', 'rb') as f2:
    response = requests.post(
        'https://api.linkagateway.com/v1/disputes/appeal',
        headers={
            'x-api-key': api_key,
            'Idempotency-Key': str(uuid.uuid4()),
        },
        data={
            'disputeId': 'dispute_uuid_aqui',
            'appealReason': 'Compra realizada pelo próprio titular. Temos nota fiscal e log de entrega.',
        },
        files=[
            ('files', ('nota-fiscal.pdf', f1, 'application/pdf')),
            ('files', ('comprovante-entrega.pdf', f2, 'application/pdf')),
        ],
    )

data = response.json()['data']

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "mime/multipart"
    "net/http"
    "os"
    "path/filepath"

    "github.com/google/uuid"
)

func main() {
    var buf bytes.Buffer
    writer := multipart.NewWriter(&buf)

    writer.WriteField("disputeId", "dispute_uuid_aqui")
    writer.WriteField("appealReason", "Compra realizada pelo próprio titular. Temos nota fiscal e log de entrega.")

    for _, path := range []string{"nota-fiscal.pdf", "comprovante-entrega.pdf"} {
        file, _ := os.Open(path)
        defer file.Close()
        part, _ := writer.CreateFormFile("files", filepath.Base(path))
        io.Copy(part, file)
    }
    writer.Close()

    req, _ := http.NewRequest("POST", "https://api.linkagateway.com/v1/disputes/appeal", &buf)
    req.Header.Set("x-api-key", apiKey)
    req.Header.Set("Idempotency-Key", uuid.New().String())
    req.Header.Set("Content-Type", writer.FormDataContentType())

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    var data map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&data)
    fmt.Println(data)
}

Resposta 200

{
  "status": true,
  "data": {
    "id": "dispute_uuid_aqui",
    "status": "UNDER_REVIEW",
    "appealReason": "Compra realizada pelo próprio titular...",
    "updatedAt": "2026-04-09T15:00:00.000Z"
  },
  "uploadedFiles": 2,
  "message": "Appeal submitted successfully with files"
}

Aguarde a decisão

Após a análise, você receberá um dos seguintes eventos:

DISPUTE_RESOLVED, você ganhou, saldo restaurado
DISPUTE_REJECTED, comprador ganhou, valor debitado permanentemente

Gerando URLs para Evidências

Para visualizar os arquivos enviados, gere URLs temporárias (válidas por 15 minutos):

curl -X POST https://api.linkagateway.com/v1/disputes/{id}/generate-file-urls \
  -H "x-api-key: {sua_api_key}" \
  -H "Idempotency-Key: {uuid_v4_unico}"

const response = await fetch('https://api.linkagateway.com/v1/disputes/{id}/generate-file-urls', {
  method: 'POST',
  headers: {
    'x-api-key': apiKey,
    'Idempotency-Key': crypto.randomUUID(),
  },
});

const { data } = await response.json();

const response = await fetch('https://api.linkagateway.com/v1/disputes/{id}/generate-file-urls', {
  method: 'POST',
  headers: {
    'x-api-key': apiKey,
    'Idempotency-Key': crypto.randomUUID(),
  },
});

const { data } = await response.json() as any;

import requests
import uuid

response = requests.post(
    'https://api.linkagateway.com/v1/disputes/{id}/generate-file-urls',
    headers={
        'x-api-key': api_key,
        'Idempotency-Key': str(uuid.uuid4()),
    },
)

data = response.json()['data']

package main

import (
    "encoding/json"
    "fmt"
    "net/http"

    "github.com/google/uuid"
)

func main() {
    req, _ := http.NewRequest("POST", "https://api.linkagateway.com/v1/disputes/{id}/generate-file-urls", nil)
    req.Header.Set("x-api-key", apiKey)
    req.Header.Set("Idempotency-Key", uuid.New().String())

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    var data map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&data)
    fmt.Println(data)
}

Resposta

{
  "files": [
    {
      "name": "nota-fiscal.pdf",
      "url": "https://files.linkagateway.com/disputes/nota-fiscal.pdf?assinatura-temporaria",
      "expiresIn": 900
    }
  ]
}

MED PIX, Detalhe

O MED (Mecanismo Especial de Devolução) é um mecanismo regulatório do BACEN para devolver valores transferidos por engano ou fraude via PIX. Quando um evento de MED é recebido, a Linka:

Marca a transação como CHARGEDBACK
Cria um registro de disputa MED vinculado ao infractionReportId (quando disponível)
Envia o evento MED_DISPUTE_CREATED para você

Evento MED_DISPUTE_CREATED

{
  "eventType": "MED_DISPUTE_CREATED",
  "signature": "v1=...",
  "id": "med_dispute_uuid",
  "status": "OPEN",
  "amount": 15000,
  "transactionId": "txn_uuid_aqui",
  "deadline": "2026-04-16T23:59:59.000Z",
  "end2EndId": "E12345678202604091200...",
  "createdAt": "2026-04-09T14:30:00.000Z"
}

O campo deadline indica o prazo regulatório para resposta ao BACEN. Em casos com infractionReportId, a Linka pode responder ao BACEN de forma bidirecional.

Status de Disputa

Status	Descrição
`OPEN`	Disputa criada, aguardando análise ou contestação
`UNDER_REVIEW`	Em análise pela Linka (contestação recebida)
`RESOLVED`	Você ganhou, saldo restaurado
`REJECTED`	Comprador ganhou, valor debitado

Eventos de Webhook

Evento	Quando ocorre
`DISPUTE_CREATED`	Disputa aberta
`DISPUTE_RESOLVED`	Decisão a seu favor
`DISPUTE_REJECTED`	Decisão a favor do comprador
`MED_DISPUTE_CREATED`	MED PIX criado automaticamente
`MED_DISPUTE_REFUND_PENDING`	Devolução MED em processamento

Boas Práticas para Redução de Disputas

Mantenha descrições claras na transação que o comprador reconheça no extrato bancário
Salve logs de entrega, aceitação de termos e confirmações de compra
Configure notificações por email para o comprador após o pagamento
Para valores altos, considere solicitar confirmação adicional do comprador
Responda disputas rapidamente, quanto antes o appeal chegar, mais dados você tem disponíveis

Visao Geral

Onboarding

Guias

Referencia

Disputas e MED PIX

Tipos de Disputa

Impacto Financeiro

Fluxo Completo

Contestando uma Disputa

Gerando URLs para Evidências

MED PIX, Detalhe

Status de Disputa

Eventos de Webhook

Boas Práticas para Redução de Disputas

​Tipos de Disputa

​Impacto Financeiro

​Fluxo Completo

​Contestando uma Disputa

​Gerando URLs para Evidências

​MED PIX, Detalhe

​Status de Disputa

​Eventos de Webhook

​Boas Práticas para Redução de Disputas

Tipos de Disputa

Impacto Financeiro

Fluxo Completo

Contestando uma Disputa

Gerando URLs para Evidências

MED PIX, Detalhe

Status de Disputa

Eventos de Webhook

Boas Práticas para Redução de Disputas