MED (Special Returns)

MED (Special Return Mechanism) is a BACEN mechanism that allows a payer’s institution to request the return of PIX funds in cases of fraud or operational errors. When your account is the recipient of such a request, the BRZ API lets you respond to it and list all inbound MED requests by status.

How It Works

1. A payer’s institution initiates a MED request targeting a transaction received by your account.
2. BACEN places a precautionary hold on the corresponding funds.
3. You receive a webhook notification (pix.med_refund.received) and the MED appears with status OPEN.
4. You review the request and call the Respond endpoint with approve or reject.
5. If approved, the held funds are returned to the payer. If rejected, the hold is released and funds remain in your account.

Listing MED Requests by Status

Use this endpoint to list all inbound MED requests filtered by their current status:

$
curl -X GET "https://api.brzip.com.br/api/v1/pix/med/status/OPEN?page=1&page_size=20" \
>
  -H "Authorization: Bearer <your-jwt>"

Response:

1
{
2
  "meds": [
3
    {
4
      "med_id": "med_e5f6a7b8-c9d0-1e2f-3a4b-5c6d7e8f9a0b",
5
      "status": "OPEN",
6
      "type": "FRAUD",
7
      "amount": "500.00",
8
      "currency": "BRL",
9
      "end_to_end_id": "E12345678202302232120abcdef123456",
10
      "created_at": "2026-02-23T21:50:00.000Z"
11
    }
12
  ]
13
}

Available Statuses

Query Parameters

Responding to a MED Request

Once you have reviewed an inbound MED request, respond with approve or reject:

$
curl -X POST https://api.brzip.com.br/api/v1/pix/med/{med_id}/respond \
>
  -H "Authorization: Bearer <your-jwt>" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "action": "approve",
>
    "reason": "Return approved after internal analysis"
>
  }'

Request Fields

Actions

Webhook Notifications

Subscribe to the pix.med_refund.received event to be notified in real time when a new MED request arrives. See the Webhooks Integration guide for setup instructions.