SimPayDocs

    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.

    GEThttps://api.somossimpay.com.br/v3/meds/
    curl --request GET \
  --url 'https://api.somossimpay.com.br/v3/meds/' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "error": "Both filter_start_date and filter_end_date are required when filtering by date"
}'
    Response200
    {
  "worked": true,
  "next": "https://api.somossimpay.com.br/v3/meds/?id=med-789&dt=2024-01-14T10:00:00Z&direction=next&limit=5",
  "previous": null,
  "results": [
    {
      "pix_med_id": "med-123-abc-def",
      "origin_situation_type": "SCAM_FRAUD",
      "status": "WAITING",
      "amount": 1000.5,
      "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:59Z",
      "infraction_report_creation_datetime": "2024-01-15T14:30:00Z",
      "created_at": "2024-01-15T14:30:00Z"
    }
  ]
}

    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

    HeaderTypeRequiredExample
    AuthorizationStringYesBearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

    Query Parameters

    Send all dates in UTC-0. The cursor dt uses ISO 8601 with the Z suffix (YYYY-MM-DDTHH:MM:SSZ); date-only filters (filter_start_date, filter_end_date) are interpreted in UTC-0. Do not send local time or timezone offsets such as -03:00.

    Pagination Parameters

    ParameterTypeRequiredDescriptionExample
    limitIntegerNoNumber of records per page (Min: 1, Max: 100, Default: 5)limit=20
    idStringNoCursor ID for pagination navigationid=med-123-abc
    dtStringNoCursor datetime for pagination (ISO 8601 in UTC-0, with the Z suffix)dt=2024-01-15T14:30:00Z
    directionStringNoPagination direction: next or previous (Default: next)direction=next

    Filter Parameters

    ParameterTypeRequiredDescriptionExample
    filter_start_dateDateNoStart date for filtering MEDs (YYYY-MM-DD format)filter_start_date=2024-01-01
    filter_end_dateDateNoEnd date for filtering MEDs (YYYY-MM-DD format)filter_end_date=2024-01-31
    statusEnumNoFilter by MED statusstatus=WAITING
    reasonEnumNoFilter by MED reasonreason=RETURN_REQUEST
    infraction_report_statusEnumNoFilter by infraction report statusinfraction_report_status=OPEN

    Filter Enums

    MED Status (status)

    ValueDescription
    WAITINGAwaiting analysis
    CANCELLED_BY_USERCancelled by the user
    CANCELLED_BY_PSPCancelled by the PSP (Payment Service Provider)
    ACCEPTED_BY_USERAccepted by the user
    ACCEPTED_BY_PSPAccepted by the PSP
    REJECTED_BY_USERRejected by the user
    REJECTED_BY_PSPRejected by the PSP

    MED Reason (reason)

    ValueDescription
    RETURN_REQUESTRequest for transaction return
    RETURN_CANCELLATIONCancellation of return request

    Infraction Report Status (infraction_report_status)

    ValueDescription
    OPENReport is open for analysis
    RECEIVEDReport has been received
    CANCELLEDReport has been cancelled
    ANALYZEDReport 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: All dates are interpreted in UTC-0. Send date-only filters as YYYY-MM-DD and datetime cursors with the Z suffix; do not send local time or offsets such as -03:00.

    Response

    Success Response (200 OK)

    {
  "worked": true,
  "next": "https://api.somossimpay.com.br/v3/meds/?id=med-789&dt=2024-01-14T10:00:00Z&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:59Z",
      "infraction_report_creation_datetime": "2024-01-15T14:30:00Z",
      "created_at": "2024-01-15T14:30:00Z"
    }
  ]
}

    Response Fields

    Main Response

    FieldTypeDescription
    workedBooleanIndicates if the request was processed successfully
    nextString | nullURL for the next page of results (null if no more pages)
    previousString | nullURL for the previous page of results (null if on first page)
    resultsArrayList of MED records

    MED Record Fields

    FieldTypeDescription
    pix_med_idStringUnique MED identifier
    origin_situation_typeEnumType of situation that originated the MED
    statusEnumCurrent status of the MED
    amountDecimalTransaction amount involved in the dispute
    user_documentString | nullCPF/CNPJ of the transaction user
    emailStringContact email for the dispute
    phoneStringContact phone for the dispute
    analysis_resultEnum | nullResult of the analysis (ACCEPTED, REJECTED, or null)
    creator_pspStringPSP that created the MED
    user_nameString | nullName of the user involved
    receiver_documentString | nullCPF/CNPJ of the receiver
    receiver_nameString | nullName of the receiver
    receiver_agencyString | nullAgency of the receiver account
    receiver_accountString | nullAccount number of the receiver
    infraction_report_idString | nullIdentifier of the infraction report
    endtoendStringPIX end-to-end transaction identifier (E2E ID)
    due_dateDatetime | nullDue date for the MED resolution
    infraction_report_creation_datetimeDatetime | nullWhen the infraction report was created
    created_atDatetimeWhen the MED record was created

    Origin Situation Types

    ValueDescription
    SCAM_FRAUDScam or fraud situation
    UNAUTHORIZED_TRANSACTIONUnauthorized transaction
    COERCIVE_CRIMETransaction under coercion
    FRAUDULENT_ACCESS_AND_AUTHORIZATIONFraudulent access and authorization
    OTHEROther type of situation
    UNKNOWNUnknown situation type

    Analysis Results

    ValueDescription
    ACCEPTEDMED analysis accepted the dispute
    REJECTEDMED 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.

    1. First Request: Don't include id, dt, or direction parameters

      GET /v3/meds/?limit=10

    2. Next Page: Use the URL provided in the next field

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

    3. Previous Page: Use the URL provided in the previous field

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

    Cursor Parameters

    • id: The MED ID of the cursor position
    • dt: The datetime of the cursor position (ISO 8601 in UTC-0, with the Z suffix)
    • 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:00Z&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:00Z&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."]
}