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

MED Status Flow

Status Types

Reason Types

Infraction Report Status

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:00Z&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:00Z"
      // ... 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:00Z"
    }
  ]
  // ... more fields
}

Pagination

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

How It Works

1. First Request: Don't include cursor parameters

   Copy

   GET /v3/meds/?limit=10

2. Next Page: Use URL from next field in response

   Copy

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

3. Previous Page: Use URL from previous field in response

   Copy

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

Cursor Parameters

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, interpreted in UTC-0
• Do not send local time or timezone offsets such as -03:00

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

1. Receive Infraction Report - MED created with status WAITING
2. Review Evidence - Analyst examines transaction details
3. Make Decision - Accept (refund) or Reject (no refund)
4. Process Chargeback - If accepted, automatic chargeback initiated
5. 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