--- updatedAt: 2026-06-11T16:02:03.000Z --- Fetch the complete documentation index at: https://simpay-prod.readme.io/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version. # List 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. # 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 1. **Date Range Validation:** If you provide `filter_start_date`, you **must** also provide `filter_end_date`, and vice versa. Both parameters are required together. 2. **Date Format:** Use ISO date format (`YYYY-MM-DD`) for date parameters. 3. **Timezone Handling:** The system converts dates to UTC with a +3 hours offset for Brazilian timezone. ## Response ### Success Response (200 OK) ```json { "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": "user@example.com", "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 1. **First Request:** Don't include `id`, `dt`, or `direction` parameters ```http GET /v3/meds/?limit=10 ``` 2. **Next Page:** Use the URL provided in the `next` field ```http GET /v3/meds/?id=med-123-abc&dt=2024-01-15T14:30:00&direction=next&limit=10 ``` 3. **Previous Page:** Use the URL provided in the `previous` field ```http 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) ```http GET /v3/meds/?limit=10 Authorization: Bearer {access_token} ``` ### 2. Filter MEDs by Date Range ```http 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 ```http GET /v3/meds/?status=WAITING&reason=RETURN_REQUEST&limit=15 Authorization: Bearer {access_token} ``` ### 4. Navigate to Next Page ```http 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 ```http 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 ```http 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 ```json { "error": "Both filter_start_date and filter_end_date are required when filtering by date" } ``` ### 401 Unauthorized ```json { "detail": "Invalid authentication credentials" } ``` ### 422 Unprocessable Entity - Invalid Parameters ```json { "limit": ["Ensure this value is less than or equal to 100."] } ``` ## Related Documentation * [MED Details](get_med_details.md) - Get detailed information for a specific MED * [MED API Overview](index.md) - Complete MED API guide # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "version": "3.0.0", "title": "Banking & PIX API", "description": "Complete API documentation for the banking and PIX payment platform." }, "servers": [ { "url": "https://api.somossimpay.com.br/" } ], "security": [], "paths": { "/v3/meds/": { "get": { "operationId": "get_meds_list", "summary": "List MEDs", "description": "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.", "tags": [ "MED-API" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "500": { "description": "Internal server error" } } } } }, "x-readme": { "explorer-enabled": false, "proxy-enabled": true, "samples-languages": [ "curl", "python", "javascript", "java", "go" ] } } ```