MED API

Overview

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

What is MED?

MED is the official Brazilian PIX dispute resolution mechanism for handling:

🚨 Fraud (SCAM_FRAUD) - Scams and fraudulent transactions
🔓 Unauthorized Transactions - Account access without permission
⚔️ Coercive Crimes - Transactions under threat or coercion
🔐 Fraudulent Authorization - Unauthorized access and transaction approval
❓ Other Situations - Additional dispute types

Key Concepts

MED Lifecycle

Infraction Report Created (RECEIVED)
    ↓
Under Analysis (OPEN/WAITING)
    ↓
Decision Made
    ├─→ ACCEPTED (Refund approved)
    ├─→ REJECTED (Dispute denied)
    └─→ CANCELLED (Dispute cancelled)

Parties Involved

Creator PSP - Financial institution that created the infraction report
Debited Account - Account that sent the PIX (potential fraud victim)
Credited Account - Account that received the PIX (potential fraudster)
Analyst - User or PSP responsible for analyzing the dispute

Analysis Results

Result	Description
ACCEPTED	Dispute approved - refund will be processed
REJECTED	Dispute denied - no refund will occur
null	Pending analysis - decision not yet made

MED Status Flow

Status Types

Status	Description
WAITING	Awaiting analysis by user or PSP
ACCEPTED_BY_USER	User accepted the dispute (approved refund)
ACCEPTED_BY_PSP	PSP accepted the dispute (approved refund)
REJECTED_BY_USER	User rejected the dispute (denied refund)
REJECTED_BY_PSP	PSP rejected the dispute (denied refund)
CANCELLED_BY_USER	User cancelled the dispute
CANCELLED_BY_PSP	PSP cancelled the dispute

Reason Types

Reason	Description
RETURN_REQUEST	Request for transaction return (initial dispute)
RETURN_CANCELLATION	Cancellation of previous return request

Infraction Report Status

Status	Description
OPEN	Report is open for analysis
RECEIVED	Report has been received and registered
ANALYZED	Report analysis is complete (decision made)
CANCELLED	Report has been cancelled

Authentication

All MED API endpoints require:

Bearer Token - Include in Authorization header
Account Permission - Only view MEDs associated with your account

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Endpoints

1. List MEDs

GET /v3/meds/

List all MED infraction reports for your company with filtering and pagination.

Features:

Cursor-based pagination
Date range filtering
Status filtering
Reason filtering
Infraction report status filtering

Use Cases:

Monitor all ongoing disputes
Review dispute history
Filter by specific date range
Track pending analyses

View Full Documentation →

2. MED Details

GET /v3/meds/{med_id}

Retrieve comprehensive details for a specific MED infraction report.

Features:

Complete account information (debited/credited)
QR Code details (if applicable)
Analysis information (result, analyst, details)
Chargeback history
Timeline tracking

Use Cases:

Deep-dive into specific disputes
Review analysis decisions
Track chargeback processing
Investigate fraud patterns

View Full Documentation →

Common Use Cases

1. Monitor New Disputes

GET /v3/meds/?status=WAITING&infraction_report_status=OPEN&limit=20

List all disputes awaiting analysis.

2. Review Disputed Transactions by Date

GET /v3/meds/?filter_start_date=2024-01-01&filter_end_date=2024-01-31&limit=50

Analyze disputes within a specific period.

3. Track Return Requests

GET /v3/meds/?reason=RETURN_REQUEST&status=WAITING

Focus on active return requests.

4. Investigate Specific Dispute

GET /v3/meds/{med_id}

Get full details including analysis results and chargeback status.

Response Structure

List Response

{
  "worked": true,
  "next": "https://api.somossimpay.com.br/v3/meds/?id=med-123&dt=2024-01-15T14:30:00&direction=next",
  "previous": null,
  "results": [
    {
      "pix_med_id": "med-123-abc-def",
      "origin_situation_type": "SCAM_FRAUD",
      "status": "WAITING",
      "amount": 1000.50,
      "endtoend": "E1234567820240115143000123",
      "created_at": "2024-01-15T14:30:00"
      // ... more fields
    }
  ]
}

Details Response

{
  "pix_med_id": "med-123-abc-def",
  "amount": 1000.50,
  "status": "ACCEPTED_BY_PSP",
  "analysis": {
    "analysis_result": "ACCEPTED",
    "analysis_details_psp": "Confirmed fraudulent transaction",
    "psp_analyzed_by": "Carlos Silva"
  },
  "chargebacks": [
    {
      "status": "SUCCESS",
      "amount": 1000.50,
      "created_at": "2024-01-16T10:00:00"
    }
  ]
  // ... more fields
}

Pagination

MED API uses cursor-based pagination for efficient data retrieval.

How It Works

First Request: Don't include cursor parameters
```
GET /v3/meds/?limit=10
```

Next Page: Use URL from next field in response

GET /v3/meds/?limit=10&id=med-123&dt=2024-01-15T14:30:00&direction=next

Previous Page: Use URL from previous field in response

GET /v3/meds/?limit=10&id=med-456&dt=2024-01-14T10:00:00&direction=previous

Cursor Parameters

Parameter	Type	Description
id	String	MED ID cursor position
dt	String	Datetime cursor position (ISO 8601)
direction	String	`next` or `previous`
limit	Integer	Records per page (Min: 1, Max: 100, Default: 5)

Ordering

Results are ordered by infraction_report_creation_datetime (descending - most recent first), with id as secondary sort for consistency.

Filtering

Date Range Filtering

GET /v3/meds/?filter_start_date=2024-01-01&filter_end_date=2024-01-31

Rules:

Both filter_start_date and filter_end_date are required together
Format: YYYY-MM-DD
System converts to UTC with +3 hours offset (Brazilian timezone)

Status Filtering

GET /v3/meds/?status=WAITING&infraction_report_status=OPEN

Parameters:

status - MED status (WAITING, ACCEPTED_BY_USER, etc.)
infraction_report_status - Report status (OPEN, RECEIVED, ANALYZED, CANCELLED)
reason - Dispute reason (RETURN_REQUEST, RETURN_CANCELLATION)

Complex Filtering

GET /v3/meds/?filter_start_date=2024-01-01&filter_end_date=2024-01-31&status=WAITING&infraction_report_status=OPEN&limit=25

Error Handling

400 Bad Request - Invalid Parameters

{
  "error": "Both filter_start_date and filter_end_date are required when filtering by date"
}

401 Unauthorized

{
  "detail": "Invalid authentication credentials"
}

404 Not Found

{
  "detail": "MED not found"
}

Business Rules

Access Control

MEDs are company-scoped - you can only view MEDs associated with your account
No cross-company MED visibility
All requests validated against authenticated account

Data Privacy

Sensitive information (CPF, account numbers) may be partially masked
Full details available only to authorized analysts
Audit logs maintained for all MED access

Analysis Workflow

Receive Infraction Report - MED created with status WAITING
Review Evidence - Analyst examines transaction details
Make Decision - Accept (refund) or Reject (no refund)
Process Chargeback - If accepted, automatic chargeback initiated
Track Resolution - Monitor chargeback status until completion

Webhooks

MED status changes trigger webhook events:

MED_CREATED - New infraction report received
MED_APPROVED - Dispute approved (refund authorized)
MED_REJECTED - Dispute rejected
MED_CANCELLED - Dispute cancelled

Best Practices

1. Regular Monitoring

// Check for new MEDs every 15 minutes
setInterval(async () => {
  const response = await fetch('/v3/meds/?status=WAITING&limit=20');
  const data = await response.json();
  
  if (data.results.length > 0) {
    // Process new MEDs
    await analyzeNewMEDs(data.results);
  }
}, 15 * 60 * 1000);

2. Implement Webhooks

Instead of polling, subscribe to MED webhook events for real-time notifications.

3. Maintain Audit Trail

Log all MED analyses and decisions for compliance and review purposes.

4. Automate Where Possible

Use business rules to auto-approve/reject obvious cases (e.g., low-value disputes, known fraud patterns).

Compliance

MED API follows Banco Central do Brasil regulations for PIX dispute resolution:

Resolution Time: Maximum 7 days for analysis
Appeal Period: 10 days for dispute appeals
Documentation: All decisions must be documented
Notification: All parties notified of decisions