> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# List refunds

> Returns a paginated list of MED 2.0 Refunds (devoluções) owned by the requesting tenant's organization, newest first by default. Filtering is always scoped to the tenant organization resolved from the authenticated context. requesting_participant / contested_participant are optional accessory filters, not tenant boundaries. status, refund_reason, and sort_order are case-insensitive.



## OpenAPI

````yaml en/openapi/v3-current/pix-lerian-dict.yaml GET /dict/refunds
openapi: 3.1.0
info:
  contact:
    name: Lerian Studio
    url: https://lerian.studio
  description: >-
    Public API for Pix keys, claims, fraud markers, infraction reports, and MED
    funds recovery.
  license:
    name: Elastic License 2.0
    url: https://www.elastic.co/licensing/elastic-license
  title: Pix Lerian — DICT
  version: release-candidate
servers:
  - url: https://api.example.com/dict-hub/v1
    description: >-
      Replace the example host with the URL provided during environment
      onboarding.
security:
  - BearerAuth: []
tags:
  - description: Register, retrieve, list, update, and remove Pix keys.
    name: Entries
  - description: Look up Pix keys and check whether keys exist in the DICT directory.
    name: Keys
  - description: Manage ownership and portability claims for Pix keys.
    name: Claims
  - description: Manage participant-scoped MED 2.0 funds recoveries.
    name: Funds Recoveries
  - description: Manage MED 2.0 infraction reports for the authenticated organization.
    name: Infraction Reports
  - description: Create, query, cancel, and settle MED 2.0 refunds.
    name: Refunds
  - description: Create, query, list, and cancel DICT fraud markers.
    name: Fraud Markers
paths:
  /dict/refunds:
    get:
      tags:
        - Refunds
      summary: List refunds
      description: >-
        Returns a paginated list of MED 2.0 Refunds (devoluções) owned by the
        requesting tenant's organization, newest first by default. Filtering is
        always scoped to the tenant organization resolved from the authenticated
        context. requesting_participant / contested_participant are optional
        accessory filters, not tenant boundaries. status, refund_reason, and
        sort_order are case-insensitive.
      operationId: listRefunds
      parameters:
        - description: Filter by lifecycle status (case-insensitive)
          explode: false
          in: query
          name: status
          schema:
            description: Filter by lifecycle status (case-insensitive)
            examples:
              - OPEN
            type: string
          example: OPEN
        - description: Filter by refund reason (case-insensitive)
          explode: false
          in: query
          name: refund_reason
          schema:
            description: Filter by refund reason (case-insensitive)
            examples:
              - FRAUD
            type: string
          example: FRAUD
        - description: Filter by the contested transaction end-to-end ID (32 chars)
          explode: false
          in: query
          name: transaction_id
          schema:
            description: Filter by the contested transaction end-to-end ID (32 chars)
            examples:
              - E12345678202601011200abcdef01234
            type: string
          example: E12345678202601011200abcdef01234
        - description: Filter by the linked infraction report UUID
          explode: false
          in: query
          name: infraction_report_id
          schema:
            description: Filter by the linked infraction report UUID
            examples:
              - c3d4e5f6-a7b8-4901-abcd-34567890abcd
            type: string
          example: c3d4e5f6-a7b8-4901-abcd-34567890abcd
        - description: Filter by the requesting participant ISPB (8 digits)
          explode: false
          in: query
          name: requesting_participant
          schema:
            description: Filter by the requesting participant ISPB (8 digits)
            examples:
              - '12345678'
            type: string
          example: '12345678'
        - description: Filter by the contested participant ISPB (8 digits)
          explode: false
          in: query
          name: contested_participant
          schema:
            description: Filter by the contested participant ISPB (8 digits)
            examples:
              - '87654321'
            type: string
          example: '87654321'
        - description: 'Page number (default: 1, minimum: 1)'
          explode: false
          in: query
          name: page
          schema:
            description: 'Page number (default: 1, minimum: 1)'
            examples:
              - '1'
            type: string
          example: '1'
        - description: 'Maximum number of items per page (default: 10, max: 100)'
          explode: false
          in: query
          name: limit
          schema:
            description: 'Maximum number of items per page (default: 10, max: 100)'
            examples:
              - '10'
            type: string
          example: '10'
        - description: 'Sort direction by last_modified (default: desc, case-insensitive)'
          explode: false
          in: query
          name: sort_order
          schema:
            description: 'Sort direction by last_modified (default: desc, case-insensitive)'
            examples:
              - desc
            type: string
          example: desc
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListRefundsView'
              examples:
                fictitiousExample:
                  summary: Fictitious example
                  value:
                    hasMore: false
                    items:
                      - alreadySettledAmount: '100.50'
                        analysisDetails: analysisdetails-example
                        analysisResult: TOTALLY_ACCEPTED
                        bacenRefundId: 3d48532f-1a2b-4422-81c3-b7dc852e262b
                        contestedParticipant: '87654321'
                        correlationId: 9f3a8b7e2c1d4e5a8b6f1a2b3c4d5e6f
                        creationTime: '2026-01-01T12:00:00Z'
                        effectiveRefundedAmount: '100.50'
                        fundsRecoveryId: 019606a1-3b4c-7d8e-9f01-234567890abc
                        id: 018f8c1d-1234-7abc-9def-000000000001
                        infractionReportId: 019606a1-3b4c-7d8e-9f01-234567890abc
                        lastModified: '2026-01-01T12:30:00Z'
                        monitorAccount: false
                        refundAccount:
                          accountNumber: '123456'
                          accountType: CACC
                          branch: '0001'
                          participant: '99999011'
                          taxIdNumber: '12345678909'
                        refundAmount: '1000.00'
                        refundDetails: refund due to operational failure
                        refundReason: OPERATIONAL_FLAW
                        refundRejectionReason: NO_BALANCE
                        refundTransactionId: 019606a1-3b4c-7d8e-9f01-234567890abc
                        requestingParticipant: '12345678'
                        settleReason: settlereason-example
                        settleType: REFUND
                        status: OPEN
                        surplusAmount: '100.50'
                        transactionId: E12345678202601011200abcdef01234
                    limit: 10
                    page: 1
                    total: 1
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      x-codeSamples:
        - lang: bash
          label: cURL with fictitious data
          source: |-
            curl --request GET \
              --url https://api.example.com/dict-hub/v1/dict/refunds \
              --header 'Authorization: Bearer demo-access-token'
components:
  schemas:
    ListRefundsView:
      additionalProperties: false
      properties:
        hasMore:
          examples:
            - false
          type: boolean
        items:
          items:
            $ref: '#/components/schemas/RefundView'
          type:
            - array
            - 'null'
        limit:
          examples:
            - 10
          format: int64
          type: integer
        page:
          examples:
            - 1
          format: int64
          type: integer
        total:
          examples:
            - 1
          format: int64
          type: integer
      required:
        - items
        - total
        - page
        - limit
        - hasMore
      type: object
    Detail:
      additionalProperties: false
      properties:
        code:
          description: >-
            Stable, machine-readable domain error code scoped to the emitting
            service (format: <SERVICE>-NNNN).
          examples:
            - ERR-0001
          type: string
        detail:
          description: >-
            A human-readable explanation specific to this occurrence of the
            problem.
          examples:
            - Property foo is required but is missing.
          type: string
        errors:
          description: Optional list of individual error details
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type:
            - array
            - 'null'
        instance:
          description: >-
            A URI reference that identifies the specific occurrence of the
            problem.
          examples:
            - https://example.com/error-log/abc123
          format: uri
          type: string
        status:
          description: HTTP status code
          examples:
            - 400
          format: int64
          type: integer
        title:
          description: >-
            A short, human-readable summary of the problem type. This value
            should not change between occurrences of the error.
          examples:
            - Bad Request
          type: string
        type:
          default: about:blank
          description: A URI reference to human-readable documentation for the error.
          examples:
            - https://example.com/errors/example
          format: uri
          type: string
        upstream:
          $ref: '#/components/schemas/Upstream'
          description: >-
            RFC 9457 extension member: the error a proxied third-party provider
            reported. Absent unless the emitting service explicitly surfaced
            one.
      type: object
    RefundView:
      additionalProperties: false
      properties:
        alreadySettledAmount:
          type: string
        analysisDetails:
          type: string
        analysisResult:
          enum:
            - TOTALLY_ACCEPTED
            - PARTIALLY_ACCEPTED
            - REJECTED
          type: string
        bacenRefundId:
          examples:
            - 3d48532f-1a2b-4422-81c3-b7dc852e262b
          type: string
        contestedParticipant:
          examples:
            - '87654321'
          type: string
        correlationId:
          examples:
            - 9f3a8b7e2c1d4e5a8b6f1a2b3c4d5e6f
          type: string
        creationTime:
          examples:
            - '2026-01-01T12:00:00Z'
          format: date-time
          type: string
        effectiveRefundedAmount:
          type: string
        fundsRecoveryId:
          type: string
        id:
          examples:
            - 018f8c1d-1234-7abc-9def-000000000001
          type: string
        infractionReportId:
          type: string
        lastModified:
          examples:
            - '2026-01-01T12:30:00Z'
          format: date-time
          type: string
        monitorAccount:
          examples:
            - false
          type: boolean
        refundAccount:
          $ref: '#/components/schemas/RefundAccountView'
        refundAmount:
          examples:
            - '1000.00'
          type: string
        refundDetails:
          examples:
            - refund due to operational failure
          type: string
        refundReason:
          enum:
            - FRAUD
            - OPERATIONAL_FLAW
            - PIX_AUTOMATICO
            - REFUND_CANCELLED
          examples:
            - OPERATIONAL_FLAW
          type: string
        refundRejectionReason:
          enum:
            - NO_BALANCE
            - ACCOUNT_CLOSURE
            - INVALID_REQUEST
            - OTHER
            - PARTICIPANT_EXCLUSION
          type: string
        refundTransactionId:
          type: string
        requestingParticipant:
          examples:
            - '12345678'
          type: string
        settleReason:
          type: string
        settleType:
          enum:
            - REFUND
            - MANUAL
          type: string
        status:
          enum:
            - OPEN
            - CLOSED
            - CANCELLED
          examples:
            - OPEN
          type: string
        surplusAmount:
          type: string
        transactionId:
          examples:
            - E12345678202601011200abcdef01234
          type: string
      required:
        - id
        - transactionId
        - refundReason
        - refundAmount
        - status
        - requestingParticipant
        - contestedParticipant
        - monitorAccount
        - creationTime
        - lastModified
      type: object
    ErrorDetail:
      additionalProperties: false
      properties:
        location:
          description: >-
            Where the error occurred, e.g. 'body.items[3].tags' or
            'path.thing-id'
          type: string
        message:
          description: Error message text
          type: string
        value:
          description: The value at the given location
      type: object
    Upstream:
      additionalProperties: false
      properties:
        code:
          description: The upstream provider's own error code, verbatim.
          examples:
            - E4001
          type: string
        message:
          description: >-
            The upstream provider's own error message, verbatim (bounded, never
            its raw response body).
          examples:
            - account not found at provider
          type: string
      type: object
    RefundAccountView:
      additionalProperties: false
      properties:
        accountNumber:
          examples:
            - '123456'
          type: string
        accountType:
          examples:
            - CACC
          type: string
        branch:
          examples:
            - '0001'
          type: string
        participant:
          examples:
            - '99999011'
          type: string
        taxIdNumber:
          examples:
            - '12345678909'
          type: string
      required:
        - taxIdNumber
        - participant
        - branch
        - accountNumber
        - accountType
      type: object
  securitySchemes:
    BearerAuth:
      bearerFormat: JWT
      description: JWT bearer token issued by the identity provider.
      scheme: bearer
      type: http

````