Disputes - Special Return Mechanism (MED)

MED (Mecanismo Especial de Devolucao) is the process by which a payer can request the return of a PIX payment, typically due to suspected fraud or operational error. When a MED is filed against your account, you have a deadline to contest or accept the return.

Lifecycle

RECEIVED -> CONTESTED -> PENDING_DECISION -> ACCEPTED / REJECTED / CANCELED

Status	Description
RECEIVED	MED received. Awaiting your response within the deadline (holderAnswerDeadline).
CONTESTED	Response submitted (AGREE or DISAGREE) with evidence.
PENDING_DECISION	Response sent to the bank, awaiting regulator decision.
ACCEPTED	MED accepted. The amount will be returned to the payer (total or partial).
REJECTED	MED rejected. The amount stays in your account.
CANCELED	MED canceled by the claimant or regulator.

Final Result

When a MED is closed, the result field indicates the banking partner outcome:

Result	Description
AGREED	Bank agreed with the return
DISAGREED	Bank disagreed with the return

Partial Refunds

A MED can result in multiple partial refunds. Each refund has its own E2E (D code) and amount. The refundedAmount field is the sum of all refunds made.

Scenario	Example
Full refund	originalAmount: 1000.00, refundedAmount: 1000.00
Partial refund	originalAmount: 1000.00, refundedAmount: 300.00
No refund (no balance)	originalAmount: 1000.00, refundedAmount: 0.00

Receiving MEDs via Webhook

When a MED is filed, you receive a pix.med.opened webhook. When updated, pix.med.updated.

{
  "type": "pix.med.opened",
  "data": {
    "endToEndId": "E303062942026021812490000005QLMv",
    "medId": "204cc938-da3d-4f04-baf3-0b2e6a2f1283",
    "status": "DELIVERED",
    "type": "REVERSAL",
    "method": "INVASION",
    "description": "I was scammed, did not receive the contracted product",
    "flow": "IN",
    "openedAt": "2026-02-18T19:34:14Z"
  }
}

Status History

The API maintains a complete history of all status changes. Each entry contains:

{
  "history": [
    { "status": "RECEIVED", "rawStatus": "DELIVERED", "timestamp": "2026-02-18T19:34:14Z", "description": "MED received" },
    { "status": "CONTESTED", "rawStatus": "CONTESTED", "timestamp": "2026-02-19T10:00:00Z", "description": "Answer: DISAGREE" },
    { "status": "PENDING_DECISION", "rawStatus": "ACKNOWLEDGED", "timestamp": "2026-02-20T14:00:00Z" },
    { "status": "REJECTED", "rawStatus": "REJECTED", "timestamp": "2026-02-23T09:00:00Z" }
  ]
}

Contesting a MED

Coming soon: Contestation via API (submitting answers and uploading evidence) will be available in a future update. For now, contestation must be done directly through the banking partner's channel.

Listing MEDs

GET /v1/backoffice/tenants/{tenantId}/meds

Returns all MEDs for the tenant with complete history, refunds, and control fields (holderAnswerStatus, holderAnswerDeadline, result).

MED Rate Monitoring

GET /v1/backoffice/tenants/{tenantId}/med-stats?days=30

Reference Thresholds

Rate	Status	Description
< 0.4%	Green	Healthy rate
0.4% - 1.0%	Yellow	Attention, monitor closely
> 1.0%	Red	Elevated rate, action may be required

MED Policies

See the Policies and Rules guide for configuring auto-block and rate limits.