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 in accordance with the regulations of the Brazilian Central Bank (Banco Central do Brasil). The API allows you to query, analyze, and handle MED infraction reports related to your account's PIX transactions.

Under the Partner API, you operate MEDs on behalf of your sub-merchants: each MED belongs to exactly one sub-merchant under your partner account, and all responses and webhook events carry that sub-merchant's number (subMerchantNo) so you can route the record to the right sub-merchant.

1. What is MED?

Adopay handles several types of MED, including:

Fraud: Scams and fraudulent activities handled under the identifier SCAM_FRAUD.
Unauthorized Transactions: Covers account access without authorization.
Coercive Crimes: Applies to transactions made under threat or coercion.
Fraudulent Authorization: Involves unauthorized access and transaction approval.
Other Situations: Covers other MED categories.

2. Key Concepts

MED (Mecanismo Especial de Devolução): The Pix fraud refund mechanism regulated by the Brazilian Central Bank.
Sub-merchant: A merchant onboarded under the partner account. Each MED belongs to exactly one sub-merchant, identified by its merchant number (subMerchantNo).
Infraction Report: A violation report initiated by the BCB against a Pix transaction.
Chargeback / Refund: The refund process triggered once a MED is approved.
Evidence Requirements: The evidence 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 type to support the analysis decision (e.g., transaction proof, 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 partner 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 partner has not submitted by dueTime, the case no longer waits for the partner — the platform submits on the partner's behalf and the case enters platform review (UNDER_REVIEW). Partner 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 non-closed 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 partner (upload evidence files and submit the analysis).
EVIDENCE_REQUIRED (additional evidence required): The platform has returned the partner's dispute submission and requested additional evidence; the partner can supplement files and resubmit the analysis.
UNDER_REVIEW (under platform review): The partner 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 (partner has agreed to the refund): The partner has submitted an analysis verdict agreeing to the refund.
REJECTED_BY_USER (partner has disputed): The partner 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 (user cancelled): The paying user / complaint initiator withdrew this MED application; no refund (any frozen funds are unfrozen).
CANCELLED_BY_PSP (platform cancelled): The platform cancelled or terminated this MED processing; no refund (any frozen funds 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 Partner

    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 partner funds (disputed transaction amount)
    PSP-->>MER: Webhook: MED_CREATED

    MER->>PSP: Query list / get details
    MER->>PSP: Query evidence types for the MED's industry
    PSP-->>MER: Return evidence items (evidenceType + requirements)
    opt Only a partner dispute (REJECTED) requires 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 partner'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 Dispute submission returned
        rect rgb(255, 236, 210)
            Note over PSP: status = EVIDENCE_REQUIRED, partner funds remain frozen
            PSP-->>MER: Webhook: MED_ANALYSIS_REJECTED
            Note right of MER: Resubmit the analysis after supplementing 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 partner funds (execute refund chargeback)
            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 partner funds
        end
    end

    opt Before the ruling is made
        alt Paying user / complaint initiator cancels
            CPSP->>BCB: Withdraw the MED application
            BCB-->>PSP: infractionReportStatus = CANCELLED
            Note over PSP: status = CANCELLED_BY_USER (user cancelled)
        else Platform cancels or terminates processing
            Note over PSP: status = CANCELLED_BY_PSP (platform cancelled)
        end
        PSP-->>MER: Webhook: MED_CANCELLED
        PSP->>PSP: Unfreeze partner funds
    end

    opt After fund processing is complete
        PSP->>PSP: Close the case
        Note over PSP: status = CLOSED (terminal, no dedicated webhook)
    end

4. Authentication

All MED API endpoints use ES256 request signing and must carry X-Merchant-Id, X-Timestamp, X-Nonce, Digest, and Authorization. For details, see Request Signing.

5. Endpoints

Endpoint	Description
Query MED List	List all MED infraction reports with cursor-based pagination; supports filtering by date range, sub-merchant, status, and infraction report status
Query MED Details	Get the full details of a specific MED, including both account sides, funds freeze status, analysis information, and refund history
Get Evidence Requirements	Get the evidence checklist and its completion state for the industry a MED belongs to
Upload Evidence File	Upload an evidence file (PDF, images, etc.) for a MED under an `evidenceType`
Submit Analysis Result	After submission the MED enters `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 (payloads are full structures, with fields identical to the details endpoint)

6. Enums & Statuses

Analysis Result

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

MED Status

Value	Description
`WAITING`	Pending: the case is waiting to be handled by the partner (upload evidence files and submit the analysis)
`EVIDENCE_REQUIRED`	Additional evidence required: the platform has returned the partner's dispute submission; the partner can supplement files and resubmit the analysis
`UNDER_REVIEW`	Under platform review: the partner 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 partner has submitted an analysis verdict agreeing to the refund
`REJECTED_BY_USER`	The partner 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`	User cancelled: the paying user / complaint initiator withdrew this MED application
`CANCELLED_BY_PSP`	Platform cancelled: the platform cancelled or terminated this 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 both partner and sub-merchant; a partner can only view and operate the MEDs of its own sub-merchants (identified by subMerchantNo).
Cross-partner and cross-sub-merchant visibility is prohibited.

Evidence Requirement Matching

Adopay determines the subMerchantNo a MED belongs to via medId; partners do not need to specify the merchant number separately.
Each MED maps to exactly one industry and merchant type; the checklist 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 verdict, Adopay validates that all REQUIRED evidence has corresponding files uploaded; when the evidence is incomplete the submission is rejected and the MED keeps its current status (WAITING or EVIDENCE_REQUIRED). Submitting an ACCEPTED verdict requires no evidence files. CONDITIONAL evidence is informational only and is not part of the mandatory validation.
Evidence file upload and analysis submission 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 partner's behalf and enter platform review (UNDER_REVIEW); partner 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

Changes to MED status and funds freeze status, 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 per refund executed). All event payloads are full structures: they carry the sub-merchant number (subMerchantNo) the MED belongs to and include the full set of fields identical to the data of Query MED Details. See Webhooks for details.

9. Best Practices

Poll for new MEDs regularly (e.g., every 15 minutes).
Subscribe to webhooks instead of relying solely on polling.
Get the evidence requirements before submitting a rejection, upload files under the corresponding evidenceType, and confirm that data.complete is true (complete counts only REQUIRED evidence); an acceptance requires no evidence files.
Watch dueTime and complete evidence upload and analysis submission before the evidence submission deadline.
Log all analyses and decisions to meet compliance and audit requirements.

10. Compliance (Brazilian Central Bank)

Resolution time: the MED collection-side analysis phase must be completed within 7 calendar days as required by regulation.
Partner non-response: partner 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

Merchant

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)