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

# List Refunds

> Retrieve a paginated list of refunds that have been issued



## OpenAPI

````yaml get /v1/aggregators/{raast-aggregator-id}/refunds
openapi: 3.1.0
info:
  title: Raast Wire
  version: 1.0.0
  description: ''
servers:
  - url: https://api.getsafepay.com/raastwire
security: []
tags:
  - name: Aggregators
  - name: Access Keys
  - name: Merchants
  - name: Raast Merchants
  - name: Payments
  - name: Refunds
  - name: QRs
  - name: Utilities
  - name: Aliases
  - name: Ledgers
  - name: Webhooks
paths:
  /v1/aggregators/{raast-aggregator-id}/refunds:
    parameters:
      - $ref: '#/components/parameters/AggregatorIdParam'
    get:
      tags:
        - Refunds
      summary: List Refunds
      description: Retrieve a paginated list of refunds that have been issued
      parameters:
        - name: limit
          in: query
          required: false
          example: 10
          schema:
            type: string
        - name: offset
          in: query
          required: false
          example: 0
          schema:
            type: string
        - name: payment_id
          in: query
          required: false
          description: Filter refunds by one or more payment identifiers.
          example:
            - pm_2288490a
          schema:
            type: array
            items:
              type: string
        - name: status
          in: query
          required: false
          description: Filter refunds by one or more statuses.
          example:
            - R_COMPLETED
            - R_FAILED
            - R_INITIATED
            - R_CANCELED
          schema:
            type: array
            items:
              type: string
        - name: trace_reference
          in: query
          required: false
          description: Filter refunds by one or more trace references.
          example:
            - 90c4831d-e6d7-491e-a5f9-5f92c7cd1073
          schema:
            type: array
            items:
              type: string
        - name: msg_id
          in: query
          required: false
          description: Filter refunds by one or more Raast message identifiers.
          example:
            - H1KMBBKXMARBF3EEP5HATG27BHIAZ3GIH2J
          schema:
            type: array
            items:
              type: string
        - name: return_id
          in: query
          required: false
          description: Filter refunds by one or more return identifiers.
          example:
            - rtn_12345
          schema:
            type: array
            items:
              type: string
        - name: request_id
          in: query
          required: false
          description: Filter refunds by one or more client request identifiers.
          example:
            - 6a049190-3595-47cb-8603-7e310c3adb15
          schema:
            type: array
            items:
              type: string
        - name: refund_id
          in: query
          required: false
          description: Filter refunds by one or more refund identifiers.
          example:
            - rfd_7e26f9be-f59d-4025-8e17-9fc398d16230
          schema:
            type: array
            items:
              type: string
        - name: start_date
          in: query
          required: false
          description: Filter refunds created on or after this UNIX timestamp.
          example: 1735689600
          schema:
            type: integer
        - name: end_date
          in: query
          required: false
          description: Filter refunds created on or before this UNIX timestamp.
          example: 1767225600
          schema:
            type: integer
        - name: direction
          in: query
          required: false
          example: DESC
          schema:
            type: string
            enum:
              - ASC
              - DESC
      responses:
        '200':
          $ref: '#/components/responses/ListRefundsResponse'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
        - apiKey: []
components:
  parameters:
    AggregatorIdParam:
      name: raast-aggregator-id
      in: path
      required: true
      schema:
        type: string
        example: agg_2288490a-2176-4de5-b373-0ffb6f8e2e6e
      description: The unique identifier for the aggregator
  responses:
    ListRefundsResponse:
      description: This response contains a paginated list of refunds linked to a payment
      headers:
        Content-Length:
          $ref: '#/components/headers/ContentLengthHeader'
        Date:
          $ref: '#/components/headers/DateHeader'
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/StandardResponse'
              - type: object
                properties:
                  data:
                    type: object
                    properties:
                      count:
                        type: integer
                        example: 1
                        description: Total number of refunds
                      keys:
                        type: array
                        description: List of refunds
                        items:
                          $ref: '#/components/schemas/Refund'
    InternalError:
      description: Internal server error response
      headers:
        Content-Length:
          $ref: '#/components/headers/ContentLengthHeader'
        Date:
          $ref: '#/components/headers/DateHeader'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorEnvelope'
          examples:
            InternalServerError:
              value:
                api_version: v1
                error:
                  code: error.internal_server_error
                  message: rpc error code Internal desc = something went wrong
  headers:
    ContentLengthHeader:
      schema:
        type: string
        example: '256'
    DateHeader:
      schema:
        type: string
        example: Sat, 12 Aug 2023 08:55:04 GMT
  schemas:
    StandardResponse:
      type: object
      description: Standard response structure for successful operations
      properties:
        api_version:
          type: string
          example: v1
          description: The current version of the API spec
        data:
          type: object
          description: Contains the response data
    Refund:
      type: object
      properties:
        token:
          type: string
        payment_id:
          type: string
        amount:
          type: string
        type:
          type: string
        reason:
          type: string
        addtl_info:
          type: string
        status:
          type: string
        trace_reference:
          type: string
        msg_id:
          type: string
        return_id:
          type: string
        request_id:
          type: string
        msg_created_at:
          $ref: '#/components/schemas/Timestamp'
        settle_at:
          nullable: true
        created_at:
          $ref: '#/components/schemas/Timestamp'
        updated_at:
          $ref: '#/components/schemas/Timestamp'
    ApiErrorEnvelope:
      type: object
      description: Error wrapper that includes the API version and error metadata
      properties:
        api_version:
          type: string
          description: Indicates the API version associated with the response
          example: v1
        error:
          description: Structured error details describing why the request failed
          allOf:
            - $ref: '#/components/schemas/ErrorResponse'
          example:
            code: error.unauthorized_access
            message: partner access key is required in request header
    Timestamp:
      type: string
      format: date-time
      description: ISO 8601 timestamp in UTC
      example: '2025-03-13T09:12:34.000Z'
    ErrorResponse:
      type: object
      description: Standard error response structure
      properties:
        code:
          type: string
          description: Error code identifying the type of error
        message:
          type: string
          description: Human-readable error message
  securitySchemes:
    apiKey:
      type: apiKey
      name: X-SFPY-AGGREGATOR-SECRET-KEY
      in: header

````