Disputes (MED)

What a MED is

A MED (Mecanismo Especial de Devolução) is the PIX contestation the payer's bank opens when the payer reports a transfer as fraudulent. Bacen gives the payer's bank a window measured in days to open it — long after the PIX settled and long after the asset was delivered.

That timing is the whole reason disputes need their own handling:

1. A PIX lands on the account and funds one of your operations.
2. The asset is delivered on-chain, irreversibly, within seconds.
3. Days later the payer's bank opens a MED. The disputed amount is frozen on the receiving account.
4. The MED is accepted, rejected, or withdrawn.

By the time you receive DISPUTE_CREATED, the money has already left the chain. The event is a fraud signal about the payer, not a payment you can still stop.

Subscribing

Dispute events are registered like any other webhook, from the Hodle dashboard:

1. Open API Keys → Webhooks and click Configurar Webhook.
2. Enter your public HTTPS endpoint.
3. Select the dispute events you want: DISPUTE_CREATED, DISPUTE_ACCEPTED, DISPUTE_REJECTED, DISPUTE_CANCELED.

Each event is a separate subscription, so you can register only the legs you act on. Signature verification, headers, and the secret are identical to every other event — see Webhooks.

The four events

The four events carry the same payload shape, so one handler covers all of them; branch on event (or on data.status, which always matches it) for the outcome.

Only DISPUTE_ACCEPTED costs you the money. REJECTED and CANCELED both leave the amount with you.

Payload

{
  "event": "DISPUTE_CREATED",
  "data": {
    "status": "CREATED",
    "providerStatus": "OPENED",
    "disputeId": null,
    "endToEndId": "E00416968202608231253t7wOSElb8rU",
    "value": 10000,
    "valueInBrl": "100.00",
    "reason": "No intuito de recuperar meu primeiro investimento me pediu mais dinheiro",
    "payerName": null,
    "occurredAt": "2026-08-23T12:53:00.000Z",
    "walletCharge": {
      "id": "6650b21c9f4d3a0012ab34cd",
      "externalId": "my-order-123",
      "trackId": "9f4d3a0012ab34cd6650b21c",
      "correlationID": "3f1a9c7e-2b44-4d10-9a51-8c2d6e0f4b73",
      "asset": "USDT",
      "network": "polygon",
      "status": "COMPLETED",
      "valueInBrl": "100.00",
      "fee": "2.00",
      "transactionHash": "0xeafe9c4985963a7a7d6e49f763cca5c6006693031402d46c0da2fced4519fe03",
      "createdAt": "2026-08-23T12:52:41.000Z"
    }
  }
}

Fields

walletCharge — reconciling against your order

A MED identifies nothing but the contested PIX, by its endToEndId. It carries no order id, no account id, and no reference to whatever the PIX paid for.

So we resolve it for you. Every incoming PIX has its endToEndId recorded on the operation it funded, and on a dispute we walk that back and send the operation inline, so you can match the dispute to the order you already settled without a second lookup.

walletCharge is null when the contested PIX did not fund a charge — a direct transfer into the account, or a PIX received before we started recording the endToEndId of incoming payments. The event is still delivered: match it by endToEndId against your own records in that case.

transactionHash is what proves the delivery happened. Keep it: it is the evidence that answers the contestation.

Attribution — and its one gap

Because the MED payload has no account identifier, we attribute the dispute by matching its endToEndId, in order, against:

1. the PIX2STABLE delivery that consumed the PIX (which already knows its merchant account),
2. the wallet charge the PIX paid,
3. the transaction ledger entry for the PIX.

The first match wins and identifies the account — and therefore you, the customer the event is sent to.

Attribution is resolved once, when the MED is first seen. Later legs (ACCEPTED, REJECTED, CANCELED) reuse it, so every leg of one MED is delivered to the same endpoint with the same walletCharge.

Delivery semantics

• One delivery attempt per event. A 2xx is success; anything else is logged as a failure and not retried — same policy as every other Hodle webhook.
• There is no dispute endpoint to poll. Unlike payouts, a dispute cannot be re-read over the API. Return 2xx fast and process asynchronously; a delivery your endpoint drops is recoverable only through support.
• Deduplicate on endToEndId + status. A PIX has exactly one MED, but the provider can redeliver a leg, so the same (endToEndId, status) pair may arrive more than once.
• Expect legs out of order, or missing. A MED may be canceled without ever being accepted or rejected, and it can sit open for days with no further event.

Handling the event

type DisputeData = {
  status: 'CREATED' | 'ACCEPTED' | 'REJECTED' | 'CANCELED'
  endToEndId: string
  value: number
  reason: string | null
  walletCharge: { externalId: string | null } | null
}

const handleDispute = async (data: DisputeData): Promise<void> => {
  const orderRef = data.walletCharge?.externalId ?? null

  if (data.status === 'CREATED') {
    return flagOrderUnderDispute({
      dedupeKey: data.endToEndId,
      orderRef,
      amountInCents: data.value,
      reason: data.reason,
    })
  }

  return closeDispute({
    dedupeKey: data.endToEndId,
    orderRef,
    lostToPayer: data.status === 'ACCEPTED',
  })
}

Checklist

• On DISPUTE_CREATED: flag the order, freeze the end user, and keep the transactionHash — it is your evidence.
• Do not attempt to reverse or re-run the delivery. The asset is gone.
• On DISPUTE_ACCEPTED: book the loss and treat the end user as confirmed fraud.
• On DISPUTE_REJECTED / DISPUTE_CANCELED: close the flag. The money stayed with you.