Disputes and MED (Pix chargeback)

A Pix payment can be disputed after it settles. On Pix the channel for that is the MED (BACEN's Mecanismo Especial de Devolução, the Special Refund Mechanism): the payer asks their own bank to reverse a transaction they claim was fraud, a scam, or a mistake. When a MED is opened against one of your charges, AvioraPay opens a MED case for it, holds the amount from your account while the case runs, and notifies you — by webhook, by email and in the dashboard — so you don't discover the loss only at month-end.

This is different from a refund, which is a reversal you choose to issue. A MED is initiated by the payer, on their bank's side.

Everything on this page is available through the API (/v1/med/cases), the official SDKs (medCases resource) and the Disputes & MED Cases panel of your dashboard. The three read and change the same case.

#Lifecycle at a glance

                 charge paid
                      │
        MED opened by the payer's bank
                      │
                      ▼
   med_case "open"  ── amount held from your account,
                      │  charge becomes "disputed", refund blocked
          ┌───────────┴──────────────┐
          ▼                          ▼
   you accept                 you appeal (+ evidence)
          │                          │
          ▼                          ▼
     "accepted"                 "appealed"
   (loss taken)                      │
                         ┌───────────┴───────────┐
                         ▼                       ▼
                    "rejected"               "closed"
                  (MED upheld,          (in your favor, or
                   loss taken)       closed without refund)

A case can also go straight from open to closed — for example when the payer withdraws the claim, or the ruling comes back in your favor before you respond.

#What happens when a MED opens

1. A MED case is created (med_case, id med_…) linked to the disputed charge (charge_id, ch_…). It starts in open.
2. AvioraPay holds the amount from your account. The disputed amount is debited from your operational balance (it may go negative) and held while the case runs. If the case closes in your favor, it comes back; if you lose, it was already reserved.
3. The charge becomes disputed. The public charge status (status vocabulary) moves from paid to disputed. A disputed charge cannot be refunded — a refund would double the reversal (your refund + the bank-executed MED). If the case closes in your favor the charge goes back to paid.
4. You are notified, through every channel below.

#How you are notified

Payloads and signatures of the three events are in Webhooks.

No charge.* webhook is fired for a MED. The charge was paid; a MED is not a charge failure, and it is not a refund — charge.failed and charge.refunded are not sent when a MED opens, is won or is lost. Subscribe to med_case.created, med_case.updated and med.resolved. Re-reading the charge (GET /v1/charges/{id}) shows status: "disputed" while the case is open.

Webhooks are a signal; the API is the source of truth. Outcome notifications (med.resolved, and med_case.updated for accepted / rejected / closed) are on by default, but the platform can switch them off, and a MED case event that fails to be published is not retried. Reconcile with GET /v1/med/cases (for example once a day, filtered by created_after) and treat status + money_outcome from the API as final.

#Case states

money_outcome is null while the case is open or appealed, and then tells you the final destination of the money:

closed alone does not mean you won. Always read money_outcome.

Some outcomes are applied automatically when the payer's bank or BACEN rules on the case; others go through a review by the AvioraPay operations team first, and the case keeps its current status until that review is done.

#Deadlines

response_deadline (ISO 8601, UTC) is the deadline to respond to the case. It is filled in when the deadline was informed to AvioraPay, and is null otherwise. It is sent in med_case.created and returned by every read. Plan to appeal (with your evidence) well before it — the ruling does not wait for you.

#Your defense: appeal, accept and evidence

While a case is open you choose one of two paths:

• Appeal (POST /v1/med/cases/{id}/appeal) — you contest the MED with a written justification (reason, 5 to 2,000 characters). The case moves to appealed.
• Accept (POST /v1/med/cases/{id}/accept) — you give up contesting. The case moves to accepted and the amount stays debited.

Evidence (invoice, delivery proof, conversations with the buyer — anything showing the charge was legitimate) is attached with the three-step upload below. You can attach evidence before or after appealing; attach it before the deadline.

Important — what the defense is, and isn't. Your appeal and your evidence are recorded on the AvioraPay platform, where the operations team uses them to assess and handle the case. They are not forwarded automatically to the payment provider, to the payer's bank or to BACEN: today no provider offers AvioraPay a channel to submit a MED defense. Appealing is therefore not a formal submission to BACEN. The official ruling reaches AvioraPay through the MED channel and is reflected on the case (status, money_outcome) and in the webhooks above.

#API

All routes use your API key and only ever see your cases. The canonical path is /v1/med/cases; /v1/infractions is an alias that serves the same routes.

apikey: ak_live_...

The case {id} accepts the med_… id.

#The med_case object

{
  "id": "med_3f1c2b9e-0d7a-4a55-9a51-6f0e3c1d2b10",
  "object": "med_case",
  "type": "med",
  "status": "open",
  "amount": 15000,
  "currency": "BRL",
  "charge_id": "ch_6b0f4c1e-2a8d-4c1b-9d0e-1f2a3b4c5d6e",
  "reason": "Payer reports a scam",
  "response_deadline": "2026-09-30T23:59:59.000Z",
  "evidence_requested_at": null,
  "appeal_reason": null,
  "appealed_at": null,
  "evidence_count": 0,
  "money_outcome": null,
  "opened_at": "2026-09-23T14:02:11.000Z",
  "closed_at": null,
  "created_at": "2026-09-23T14:02:12.000Z",
  "updated_at": "2026-09-23T14:02:12.000Z"
}

#List cases

curl "https://aviorapay.app/v1/med/cases?status=open&limit=25" \
  -H "apikey: $AVIORAPAY_API_KEY"

{
  "object": "list",
  "data": [
    { "id": "med_3f1c2b9e-0d7a-4a55-9a51-6f0e3c1d2b10", "object": "med_case", "status": "open", "...": "..." }
  ],
  "has_more": true,
  "next_cursor": "med_3f1c2b9e-0d7a-4a55-9a51-6f0e3c1d2b10"
}

Cases are ordered newest first (created_at descending). While has_more is true, pass next_cursor as starting_after to read the next page. An unknown value for status, type or limit, or a malformed date, returns 400 — filters are never silently ignored.

#Retrieve a case

curl "https://aviorapay.app/v1/med/cases/med_3f1c2b9e-0d7a-4a55-9a51-6f0e3c1d2b10" \
  -H "apikey: $AVIORAPAY_API_KEY"

Returns the med_case object, or 404 if the case does not exist in your account.

#Appeal a case

curl -X POST "https://aviorapay.app/v1/med/cases/med_3f1c2b9e-0d7a-4a55-9a51-6f0e3c1d2b10/appeal" \
  -H "apikey: $AVIORAPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Order #8812 was delivered on 2026-09-20; signed delivery receipt attached."}'

reason is required, 5 to 2,000 characters. Returns 200 with the updated case (status: "appealed", appeal_reason and appealed_at filled in). Only an open case can be appealed: any other status returns 400.

#Accept a case

curl -X POST "https://aviorapay.app/v1/med/cases/med_3f1c2b9e-0d7a-4a55-9a51-6f0e3c1d2b10/accept" \
  -H "apikey: $AVIORAPAY_API_KEY"

No body. Returns 200 with the updated case (status: "accepted", money_outcome: "lost"). Only an open case can be accepted: any other status returns 400. Accepting is final.

#Upload evidence

Files go straight to storage through a short-lived signed URL; they never pass through the API body. Limits: 10 MB per file; types image/png, image/jpeg, image/webp, image/gif and application/pdf.

Step 1 — request an upload URL. Declare the file name, its exact size in bytes and its type:

curl -X POST "https://aviorapay.app/v1/med/cases/med_3f1c2b9e-0d7a-4a55-9a51-6f0e3c1d2b10/evidence" \
  -H "apikey: $AVIORAPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_name": "delivery-receipt.pdf", "file_size": 52341, "mime_type": "application/pdf"}'

201 Created:

{
  "id": "0b8e6f52-7c3d-4e1a-9f40-2d6c8a1b5e77",
  "object": "med_case_evidence_upload",
  "upload_url": "https://storage.example.com/…?X-Amz-Signature=…",
  "upload_method": "PUT",
  "upload_headers": { "Content-Type": "application/pdf", "Content-Length": "52341" },
  "expires_in": 900
}

Step 2 — PUT the file to upload_url within expires_in seconds (15 minutes), with exactly the headers in upload_headers. The signature binds the type and the size, so a different Content-Type or a file of a different size is refused by storage. Do not send your API key (or any Authorization header) to this URL — the URL itself is the credential.

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @delivery-receipt.pdf

(curl --data-binary sends the Content-Length of the file for you; it must match file_size from step 1.)

Step 3 — confirm the upload. AvioraPay checks that the file really arrived and marks the evidence as uploaded:

curl -X POST "https://aviorapay.app/v1/med/cases/med_3f1c2b9e-0d7a-4a55-9a51-6f0e3c1d2b10/evidence/0b8e6f52-7c3d-4e1a-9f40-2d6c8a1b5e77/complete" \
  -H "apikey: $AVIORAPAY_API_KEY"

200 OK with the evidence object:

{
  "id": "0b8e6f52-7c3d-4e1a-9f40-2d6c8a1b5e77",
  "object": "med_case_evidence",
  "file_name": "delivery-receipt.pdf",
  "file_size": 52341,
  "mime_type": "application/pdf",
  "uploaded_by": "merchant",
  "created_at": "2026-09-23T15:10:02.000Z",
  "uploaded_at": "2026-09-23T15:10:09.000Z",
  "view_url": "https://storage.example.com/…?X-Amz-Signature=…"
}

complete is idempotent: calling it again for a confirmed file returns the same evidence. If the PUT has not happened yet (or the URL expired), it returns 409 with error.code EVIDENCE_NOT_UPLOADED — request a new URL (step 1) and upload again. Evidence that was never confirmed does not exist for the API: it is not listed and does not count in evidence_count.

The official SDKs do the three steps in one call — see SDKs.

#List evidence

curl "https://aviorapay.app/v1/med/cases/med_3f1c2b9e-0d7a-4a55-9a51-6f0e3c1d2b10/evidence" \
  -H "apikey: $AVIORAPAY_API_KEY"

{
  "object": "list",
  "data": [
    { "id": "0b8e6f52-7c3d-4e1a-9f40-2d6c8a1b5e77", "object": "med_case_evidence", "file_name": "delivery-receipt.pdf", "...": "..." }
  ]
}

Only confirmed evidence is returned, newest first. uploaded_by is merchant (you), partner or platform (the AvioraPay team). view_url is a signed download link valid for 5 minutes — fetch the list again for a fresh one.

#Errors

Errors use the standard error shape. The ones specific to MED cases:

#SDKs

The official SDKs expose the same routes as a medCases resource (med_cases in Python, MedCases in .NET), plus an uploadEvidence helper that runs the three upload steps:

import { AvioraPayClient } from '@aviorapay/node';
import { readFile } from 'node:fs/promises';

const client = new AvioraPayClient({ apiKey: process.env.AVIORAPAY_API_KEY! });

const { data, has_more, next_cursor } = await client.medCases.list({ status: 'open' });

for (const medCase of data) {
  await client.medCases.uploadEvidence(medCase.id, await readFile('delivery-receipt.pdf'), {
    fileName: 'delivery-receipt.pdf',
    mimeType: 'application/pdf',
  });
  await client.medCases.appeal(medCase.id, 'Order delivered; signed receipt attached.');
}

See Official SDKs for installation and the other languages.

#Transaction metadata fields

A disputed charge may also carry informational blocks in its metadata. They are informational and non-authoritative: they mirror what was reported about the case, are read-only, can change on each case event, and their shape may change. Do not build logic on top of them — use the med_case object above.

#metadata.med — present on a disputed charge

Other keys may appear in this block; ignore the ones you don't recognise.

#metadata.failure — present on an expired / cancelled / failed charge

#Related

• MED webhook payloads and signatures: Webhooks.
• Voluntary refund (different from MED): see the refund question in Pix and the API reference.