MED API (Special Refund Mechanism)

Last updated: 2026-09-29

The MED (Mecanismo Especial de Devolução, Special Refund Mechanism) API manages PIX fraud disputes and return requests, regulated by the Brazilian Central Bank (Banco Central do Brasil). It allows you to list, analyze, and resolve MED infraction reports related to your account's PIX transactions.

This is a direct-connection API for merchants: you operate MEDs directly in your own name, and every MED belongs to your own merchant account.

1. What is MED?

Adopay handles several types of MED, including:

Fraud: Scams and fraudulent activities under the identifier SCAM_FRAUD.
Unauthorized Transactions: Account access without authorization.
Coercive Crimes: Transactions made under threat or coercion.
Fraudulent Authorization: Unauthorized access and transaction approval.
Other Situations: Other MED categories.

2. Key Concepts

MED (Mecanismo Especial de Devolução): The Pix fraud refund mechanism regulated by the Brazilian Central Bank.
Infraction Report: An infraction report initiated by the BCB against a Pix transaction.
Chargeback / Refund: The refund process triggered once a MED is approved.
Evidence Requirements: The evidence material requirements Adopay matches based on the industry and merchant type the MED belongs to (common materials + industry-specific materials; platform/PSP merchants additionally receive platform-related materials).
Response File: A file uploaded by evidence material type and used to support the analysis decision (e.g. transaction receipts, communication records).

Parties Involved

Role	Description
Creator PSP	The financial institution that created the infraction report.
Payer	The party that sent the PIX (potential fraud victim).
Payee	The party that received the PIX (potential fraudster).

3. MED Status Flow

mermaid

flowchart TB
    S([ ]) -->|"Infraction report delivered (RECEIVED)"| WAITING["WAITING<br/>Awaiting merchant action"]
    WAITING ~~~ EVI["EVIDENCE_REQUIRED<br/>Additional evidence required"]
    WAITING -->|Submits analysis: accept refund| A["ACCEPTED_BY_USER<br/>Agreed to refund"]
    WAITING -->|Submits analysis: dispute| R["REJECTED_BY_USER<br/>Disputed"]
    EVI -->|Resubmit after evidence| U["UNDER_REVIEW<br/>Under platform review"]
    A -->|Enters platform review| U
    R -->|Enters platform review| U
    U -->|Platform returns the dispute| EVI
    U -->|Upheld| ACC["ACCEPTED_BY_PSP<br/>Upheld · refund executed"]
    U -->|Not upheld| REJ["REJECTED_BY_PSP<br/>Not upheld · no refund"]
    WAITING -->|Cancelled by user| CU["CANCELLED_BY_USER<br/>Cancelled by user · unfrozen"]
    WAITING -->|Cancelled by platform| CP["CANCELLED_BY_PSP<br/>Cancelled by platform · unfrozen"]
    ACC -->|Closed| CLOSED["CLOSED<br/>Closed (terminal)"]
    REJ -->|Closed| CLOSED
    CU -->|Closed| CLOSED
    CP -->|Closed| CLOSED
    CLOSED --> E([ ])

Processing deadline: the MED collection-side analysis phase (evidence upload and analysis submission while in WAITING / EVIDENCE_REQUIRED) must be completed within 7 calendar days as required by regulation, i.e. before the evidence submission deadline (dueTime).

Timeout handling: if the merchant has not submitted by dueTime, the case no longer waits for the merchant — the platform submits on the merchant's behalf and the case enters platform review (UNDER_REVIEW). Merchant non-response does not automatically establish the MED; the final outcome follows the review decision of the PSP / settlement institution.

Terminal state: every MED eventually reaches a terminal state: a review outcome or cancellation is issued first (ACCEPTED_BY_PSP / REJECTED_BY_PSP / CANCELLED_BY_USER / CANCELLED_BY_PSP), and after fund processing (deduction or return) is complete the case enters CLOSED, after which the status never changes. Cancellations can occur from any unclosed status before the review outcome; the diagram draws them from WAITING as a representative.

Status Descriptions

WAITING (pending): The MED case is waiting to be handled by the merchant (upload evidence files and submit the analysis).
EVIDENCE_REQUIRED (additional evidence required): The platform has returned the merchant's dispute submission and requires additional evidence; the merchant can resubmit the analysis after uploading the additional files.
UNDER_REVIEW (under platform review): The merchant has submitted an analysis verdict (accept or dispute), or the platform has submitted on their behalf; the platform is reviewing and the status is held until the review result.
ACCEPTED_BY_USER (merchant has accepted the refund): The merchant has submitted an analysis verdict accepting the refund.
REJECTED_BY_USER (merchant has disputed): The merchant has submitted an analysis verdict disputing the MED.
ACCEPTED_BY_PSP (review result upheld): The platform's review result is that the MED is upheld and the refund is executed; funds enter deduction/refund processing.
REJECTED_BY_PSP (review result not upheld): The platform's review result is that the MED is not upheld; usually no refund.
CANCELLED_BY_USER (cancelled by user): The paying user / complainant withdraws the MED request; no refund (frozen funds, if any, are unfrozen).
CANCELLED_BY_PSP (cancelled by platform): The platform cancels or terminates the MED processing; no refund (frozen funds, if any, are unfrozen).
CLOSED (closed): Closed after fund processing (deduction or return) is complete; terminal state.

Interaction Sequence (with Central Bank infraction report statuses and fund flow)

mermaid

sequenceDiagram
    autonumber
    participant BCB as Brazilian Central Bank (BCB)
    participant CPSP as Creator PSP (originator)
    participant PSP as Platform (PSP)
    participant MER as Merchant

    CPSP->>BCB: Submit infraction report
    BCB->>PSP: Deliver infraction report
    Note over BCB: infractionReportStatus = RECEIVED
    Note over PSP: Create MED, status = WAITING
    PSP->>PSP: Freeze merchant funds (disputed transaction amount)
    PSP-->>MER: Webhook: MED_CREATED

    MER->>PSP: Query list / get details
    MER->>PSP: Query the evidence types for the MED's industry
    PSP-->>MER: Return evidence items (evidenceType + requirements)
    opt Only merchant disputes (REJECTED) require uploading evidence files first
        loop Returned evidence items
            MER->>PSP: Submit the corresponding file (evidenceType + file)
        end
    end
    alt Submitted before the evidence deadline (dueTime)
        MER->>PSP: Submit analysis (ACCEPTED / REJECTED)
    else No response by the deadline
        PSP->>PSP: Platform submits on the merchant's behalf (non-response does not automatically establish the MED)
    end
    Note over PSP: status = UNDER_REVIEW (under platform review)

    PSP->>PSP: Platform review
    alt Returns the dispute submission
        rect rgb(255, 236, 210)
            Note over PSP: status = EVIDENCE_REQUIRED, merchant funds remain frozen
            PSP-->>MER: Webhook: MED_ANALYSIS_REJECTED
            Note right of MER: Resubmit the analysis after providing the additional evidence
        end
    else Review result: MED upheld
        rect rgb(219, 240, 219)
            Note over BCB: infractionReportStatus = ANALYZED
            Note over PSP: status = ACCEPTED_BY_PSP (review result upheld)
            PSP-->>MER: Webhook: MED_APPROVED
            PSP->>PSP: Unfreeze and deduct merchant funds (execute chargeback refund)
            PSP-->>MER: Webhook: MED_REFUND_EXECUTED (delivered once per refund executed)
        end
    else Review result: MED not upheld
        rect rgb(250, 230, 230)
            Note over BCB: infractionReportStatus = ANALYZED
            Note over PSP: status = REJECTED_BY_PSP (review result not upheld)
            PSP-->>MER: Webhook: MED_REJECTED
            PSP->>PSP: Unfreeze merchant funds
        end
    end

    opt Before the ruling is made
        alt Cancelled by the paying user / complainant
            CPSP->>BCB: Withdraw the MED request
            BCB-->>PSP: infractionReportStatus = CANCELLED
            Note over PSP: status = CANCELLED_BY_USER (cancelled by user)
        else Cancelled or terminated by the platform
            Note over PSP: status = CANCELLED_BY_PSP (cancelled by platform)
        end
        PSP-->>MER: Webhook: MED_CANCELLED
        PSP->>PSP: Unfreeze merchant funds
    end

    Note over PSP: After fund processing (deduction or return) is complete<br/>status = CLOSED (closed)

4. Authentication

All MED API endpoints use ES256 request signing and require X-Merchant-Id, X-Timestamp, X-Nonce, Digest, and Authorization. See Request Signing.

5. Endpoints

Endpoint	Description
Query MED List	List all MED infraction reports using cursor-based pagination, with filtering by date range, status, and infraction report status
Query MED Details	Get the full details of a specific MED, including both parties' accounts, funds freeze status, analysis information, and refund history
Get Evidence Requirements	Get the evidence requirement list and completion state for the industry the MED belongs to
Upload Evidence File	Upload an evidence file (PDF, images, etc.) for a MED under an `evidenceType`
Submit Analysis Result	Submitting the analysis moves the MED to `UNDER_REVIEW` (under platform review); the platform reviews and issues the result (`ACCEPTED_BY_PSP` / `REJECTED_BY_PSP`), and a dispute submission may be returned for `EVIDENCE_REQUIRED`
Webhooks	Asynchronous notification events for MED status, funds freeze, and refund execution (payload fields identical to the detail endpoint)

6. Enums & Statuses

Analysis Result

Value	Description
`ACCEPTED`	MED accepted — the refund will be processed
`REJECTED`	MED rejected — no refund will be processed
`null`	Pending analysis — no decision has been made yet

MED Status

Value	Description
`WAITING`	Pending: the case is waiting to be handled by the merchant (upload evidence files and submit the analysis)
`EVIDENCE_REQUIRED`	Additional evidence required: the platform has returned the merchant's dispute submission; the merchant can resubmit the analysis after uploading the additional files
`UNDER_REVIEW`	Under platform review: the merchant has submitted an analysis verdict (or the platform has submitted on their behalf); the platform is reviewing until the review result
`ACCEPTED_BY_USER`	The merchant has submitted an analysis verdict accepting the refund
`REJECTED_BY_USER`	The merchant has submitted an analysis verdict disputing the MED
`ACCEPTED_BY_PSP`	Review result upheld: the platform's review result is that the MED is upheld and the refund is executed
`REJECTED_BY_PSP`	Review result not upheld: the platform's review result is that the MED is not upheld
`CANCELLED_BY_USER`	Cancelled by user: the paying user / complainant withdraws the MED request
`CANCELLED_BY_PSP`	Cancelled by platform: the platform cancels or terminates the MED processing
`CLOSED`	Closed: closed after fund processing (deduction or return) is complete; terminal state

Infraction Report Status

Value	Description
`RECEIVED`	The report has been received
`ANALYZED`	The report analysis is complete
`CANCELLED`	The report has been cancelled

Origin Situation Type

Value	Description
`SCAM_FRAUD`	Scam or fraud situation
`UNAUTHORIZED_TRANSACTION`	Unauthorized transaction
`COERCIVE_CRIME`	Coercive crime transaction
`FRAUDULENT_ACCESS_AND_AUTHORIZATION`	Fraudulent access and authorization
`OTHER`	Other situation types
`UNKNOWN`	Unknown situation type

7. Business Rules

Data Isolation

MEDs are isolated by merchant account; you can only view and operate the MEDs of your own account.
Cross-merchant visibility is prohibited.

Evidence Requirement Matching

Each MED corresponds to exactly one industry and merchant type; the requirement list consists of common materials, industry-specific materials (and, for platform/PSP merchants, platform-related materials), returned in the platform-configured order.
Template codes, template versions, and the matching process are internal Adopay information and are not returned in API responses.
When submitting a REJECTED (dispute) verdict, Adopay validates that a file has been uploaded for every required (REQUIRED) evidence item; when the evidence is incomplete, the submission is rejected and the MED keeps its current status. Submitting an ACCEPTED (acceptance) verdict requires no evidence files. CONDITIONAL (conditionally required) items are informational only and are not enforced.
Evidence file uploads and analysis submissions must be completed before the evidence submission deadline (dueTime); after the deadline, both the upload and submission endpoints reject requests.
MEDs not submitted by dueTime are submitted by the platform on the merchant's behalf and enter platform review (UNDER_REVIEW); merchant non-response does not automatically establish the MED — the final outcome follows the review decision of the PSP / settlement institution, and every case eventually reaches the terminal state (CLOSED).

8. Webhook Events

MED status and funds freeze status changes, as well as the execution of each refund operation, trigger webhook events: MED_CREATED, MED_APPROVED, MED_REJECTED, MED_CANCELLED, MED_ANALYSIS_REJECTED (the platform returns the dispute submission and the case enters EVIDENCE_REQUIRED), the funds events MED_FUNDS_FROZEN and MED_FUNDS_UNFROZEN, and the refund execution event MED_REFUND_EXECUTED (delivered once for each refund executed). All event payloads use the full structure: they contain the full field set identical to the data of Query MED Details. See Webhooks for details.

9. Best Practices

Poll for new MEDs periodically (e.g., every 15 minutes).
Subscribe to webhooks instead of relying solely on polling.
Get the evidence requirements before submitting a dispute verdict, upload files under the returned evidenceType values, and confirm that data.complete is true (complete counts only the REQUIRED items); an acceptance verdict needs no evidence files.
Watch dueTime and complete the evidence uploads and analysis submission before the evidence submission deadline.
Log all analyses and decisions for compliance and auditing.

10. Compliance (Brazilian Central Bank)

Resolution time: the MED collection-side analysis phase must be completed within 7 calendar days as required by regulation.
Merchant non-response: merchant non-response does not automatically establish the MED; the final outcome follows the review decision of the PSP / settlement institution.
Appeal period: a 10-day appeal period is allowed for MEDs.
Documentation: all decisions must be documented.
Notification: all parties involved must be notified of decisions.

Account

PIX PayIn

PIX PayOut

PixKey Management

Reconciliation Files

MED API

Webhooks

MED API (Special Refund Mechanism)

1. What is MED?

2. Key Concepts

Parties Involved

3. MED Status Flow

Status Descriptions

Interaction Sequence (with Central Bank infraction report statuses and fund flow)

4. Authentication

5. Endpoints

6. Enums & Statuses

Analysis Result

MED Status

Infraction Report Status

Origin Situation Type

7. Business Rules

Data Isolation

Evidence Requirement Matching

8. Webhook Events

9. Best Practices

10. Compliance (Brazilian Central Bank)

MED API (Special Refund Mechanism) ​

1. What is MED? ​

2. Key Concepts ​

Parties Involved ​

3. MED Status Flow ​

Status Descriptions ​

Interaction Sequence (with Central Bank infraction report statuses and fund flow) ​

4. Authentication ​

5. Endpoints ​

6. Enums & Statuses ​

Analysis Result ​

MED Status ​

Infraction Report Status ​

Origin Situation Type ​

7. Business Rules ​

Data Isolation ​

Evidence Requirement Matching ​

8. Webhook Events ​

9. Best Practices ​

10. Compliance (Brazilian Central Bank) ​

MED API (Special Refund Mechanism)

1. What is MED?

2. Key Concepts

Parties Involved

3. MED Status Flow

Status Descriptions

Interaction Sequence (with Central Bank infraction report statuses and fund flow)

4. Authentication

5. Endpoints

6. Enums & Statuses

Analysis Result

MED Status

Infraction Report Status

Origin Situation Type

7. Business Rules

Data Isolation

Evidence Requirement Matching

8. Webhook Events

9. Best Practices

10. Compliance (Brazilian Central Bank)