Time	Status	User Agent
Retrieving recent requests…

List MEDs Endpoint

GET /v3/meds/

List all PIX MED (Mecanismo Especial de Devolução) infraction reports for your company using cursor-based pagination. Provides filtering capabilities by date range, status, reason, and infraction report status.

Authentication

Header	Type	Required	Example
Authorization	String	Yes	`Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`

Query Parameters

Pagination Parameters

Parameter	Type	Required	Description	Example
limit	Integer	No	Number of records per page (Min: 1, Max: 100, Default: 5)	`limit=20`
id	String	No	Cursor ID for pagination navigation	`id=med-123-abc`
dt	String	No	Cursor datetime for pagination (ISO 8601)	`dt=2024-01-15T14:30:00`
direction	String	No	Pagination direction: `next` or `previous` (Default: `next`)	`direction=next`

Filter Parameters

Parameter	Type	Required	Description	Example
filter_start_date	Date	No	Start date for filtering MEDs (YYYY-MM-DD format)	`filter_start_date=2024-01-01`
filter_end_date	Date	No	End date for filtering MEDs (YYYY-MM-DD format)	`filter_end_date=2024-01-31`
status	Enum	No	Filter by MED status	`status=WAITING`
reason	Enum	No	Filter by MED reason	`reason=RETURN_REQUEST`
infraction_report_status	Enum	No	Filter by infraction report status	`infraction_report_status=OPEN`

Filter Enums

MED Status (`status`)

Value	Description
WAITING	Awaiting analysis
CANCELLED_BY_USER	Cancelled by the user
CANCELLED_BY_PSP	Cancelled by the PSP (Payment Service Provider)
ACCEPTED_BY_USER	Accepted by the user
ACCEPTED_BY_PSP	Accepted by the PSP
REJECTED_BY_USER	Rejected by the user
REJECTED_BY_PSP	Rejected by the PSP

MED Reason (`reason`)

Value	Description
RETURN_REQUEST	Request for transaction return
RETURN_CANCELLATION	Cancellation of return request

Infraction Report Status (`infraction_report_status`)

Value	Description
OPEN	Report is open for analysis
RECEIVED	Report has been received
CANCELLED	Report has been cancelled
ANALYZED	Report has been analyzed

Important Filter Rules

Date Range Validation: If you provide filter_start_date, you must also provide filter_end_date, and vice versa. Both parameters are required together.
Date Format: Use ISO date format (YYYY-MM-DD) for date parameters.
Timezone Handling: The system converts dates to UTC with a +3 hours offset for Brazilian timezone.

Response

Success Response (200 OK)

{
  "worked": true,
  "next": "https://api.somossimpay.com.br/v3/meds/?id=med-789&dt=2024-01-14T10:00:00&direction=next&limit=5",
  "previous": null,
  "results": [
    {
      "pix_med_id": "med-123-abc-def",
      "origin_situation_type": "SCAM_FRAUD",
      "status": "WAITING",
      "amount": 1000.50,
      "user_document": "12345678901",
      "email": "[email protected]",
      "phone": "+5511999999999",
      "analysis_result": null,
      "creator_psp": "12345678",
      "user_name": "João Silva",
      "receiver_document": "98765432000123",
      "receiver_name": "John Doe",
      "receiver_agency": "0001",
      "receiver_account": "123456",
      "infraction_report_id": "report-456",
      "endtoend": "E1234567820240115143000123",
      "due_date": "2024-01-30T23:59:59",
      "infraction_report_creation_datetime": "2024-01-15T14:30:00",
      "created_at": "2024-01-15T14:30:00"
    }
  ]
}

Response Fields

Main Response

Field	Type	Description
worked	Boolean	Indicates if the request was processed successfully
next	String \| null	URL for the next page of results (null if no more pages)
previous	String \| null	URL for the previous page of results (null if on first page)
results	Array	List of MED records

MED Record Fields

Field	Type	Description
pix_med_id	String	Unique MED identifier
origin_situation_type	Enum	Type of situation that originated the MED
status	Enum	Current status of the MED
amount	Decimal	Transaction amount involved in the dispute
user_document	String \| null	CPF/CNPJ of the transaction user
email	String	Contact email for the dispute
phone	String	Contact phone for the dispute
analysis_result	Enum \| null	Result of the analysis (ACCEPTED, REJECTED, or null)
creator_psp	String	PSP that created the MED
user_name	String \| null	Name of the user involved
receiver_document	String \| null	CPF/CNPJ of the receiver
receiver_name	String \| null	Name of the receiver
receiver_agency	String \| null	Agency of the receiver account
receiver_account	String \| null	Account number of the receiver
infraction_report_id	String \| null	Identifier of the infraction report
endtoend	String	PIX end-to-end transaction identifier (E2E ID)
due_date	Datetime \| null	Due date for the MED resolution
infraction_report_creation_datetime	Datetime \| null	When the infraction report was created
created_at	Datetime	When the MED record was created

Origin Situation Types

Value	Description
SCAM_FRAUD	Scam or fraud situation
UNAUTHORIZED_TRANSACTION	Unauthorized transaction
COERCIVE_CRIME	Transaction under coercion
FRAUDULENT_ACCESS_AND_AUTHORIZATION	Fraudulent access and authorization
OTHER	Other type of situation
UNKNOWN	Unknown situation type

Analysis Results

Value	Description
ACCEPTED	MED analysis accepted the dispute
REJECTED	MED analysis rejected the dispute

Cursor Pagination

How It Works

The API uses cursor-based pagination, which is more efficient and consistent than offset-based pagination, especially for large datasets that may change during navigation.

Navigation Process

First Request: Don't include id, dt, or direction parameters
```
GET /v3/meds/?limit=10
```

Next Page: Use the URL provided in the next field

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

Previous Page: Use the URL provided in the previous field

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

Cursor Parameters

id: The MED ID of the cursor position
dt: The datetime of the cursor position (ISO 8601 format)
direction: Either next or previous

Ordering

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

Usage Examples

1. List All MEDs (First Page)

GET /v3/meds/?limit=10
Authorization: Bearer {access_token}

2. Filter MEDs by Date Range

GET /v3/meds/?filter_start_date=2024-01-01&filter_end_date=2024-01-31&limit=20
Authorization: Bearer {access_token}

3. Filter by Status and Reason

GET /v3/meds/?status=WAITING&reason=RETURN_REQUEST&limit=15
Authorization: Bearer {access_token}

4. Navigate to Next Page

GET /v3/meds/?limit=10&id=med-123-abc&dt=2024-01-15T14:30:00&direction=next
Authorization: Bearer {access_token}

5. Navigate to Previous Page

GET /v3/meds/?limit=10&id=med-456-def&dt=2024-01-14T10:00:00&direction=previous
Authorization: Bearer {access_token}

6. Complex Filter Example

GET /v3/meds/?filter_start_date=2024-01-01&filter_end_date=2024-01-31&status=WAITING&infraction_report_status=OPEN&limit=25
Authorization: Bearer {access_token}

Error Responses

400 Bad Request - Missing Date Parameters

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

401 Unauthorized

{
  "detail": "Invalid authentication credentials"
}

422 Unprocessable Entity - Invalid Parameters

{
  "limit": ["Ensure this value is less than or equal to 100."]
}