---
updatedAt: 2026-04-23T18:12:51.000Z
agentTools:
  siteIndex: https://developers.pismo.io/llms.txt
  projectIndex: https://developers.pismo.io/pismo-docs/llms.txt
---

# List refunds

List DICT refunds for an organization.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Instant payments - Pix management",
    "description": "API responsible for providing Pix operations (related to DICT) via integrating with external providers",
    "contact": {
      "name": "API Support",
      "url": "https://developers.pismo.io/support/"
    },
    "license": {
      "name": "Copyright Pismo"
    },
    "version": "0.0.1"
  },
  "servers": [
    {
      "url": "https://sandbox.pismolabs.io/pix-dict",
      "description": "Sandbox API server for testing."
    }
  ],
  "tags": [
    {
      "name": "Refunds",
      "description": "Manage DICT refunds endpoints"
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "parameters": {
      "CIDheader": {
        "name": "x-cid",
        "in": "header",
        "schema": {
          "type": "string"
        },
        "description": "The Correlation IDentifier UUID field links related API requests and events. The `x-cid` can help the Pismo engineering team track everything related to a call. If not passed, this field is automatically generated.\n",
        "example": "B20220921145635222303062944CA66F"
      },
      "FundsRecoveryIdQuery2": {
        "name": "funds_recovery_id",
        "in": "query",
        "description": "Funds recovery identifier. \n\nReturned from the [Create funds recovery](https://developers.pismo.io/pismo-docs/reference/post-create-funds-recovery) endpoint.\n",
        "schema": {
          "type": "string"
        },
        "example": "53D0F66A-BAB0-49D7-B7DC-807B82AABD8D"
      },
      "IncludeDetailsQuery": {
        "name": "include_details",
        "in": "query",
        "schema": {
          "type": "boolean",
          "default": false
        },
        "description": "Include details in response? Default is `false`.",
        "example": false
      },
      "LimitQuery": {
        "name": "limit",
        "in": "query",
        "schema": {
          "type": "integer",
          "maximum": 200,
          "default": 20
        },
        "description": "Maximum results to return. Default is `20`. Maximum is `200`.",
        "example": 20
      },
      "ModifiedAfterQuery": {
        "name": "modified_after",
        "in": "query",
        "schema": {
          "type": "string",
          "format": "date-time"
        },
        "description": "Return DICT refunds modified after this date.  A RFC 3339 date-time value. For example - `2023-04-12T23:20:50.52Z`.",
        "example": "2023-04-12T23:20:50.52Z"
      },
      "ModifiedBeforeQuery": {
        "name": "modified_before",
        "in": "query",
        "schema": {
          "type": "string"
        },
        "description": "Return DICT refunds modified before this date.  A RFC 3339 date-time value. For example - `2023-04-12T23:20:50.52Z`.",
        "example": "2023-04-12T23:20:50.52Z"
      },
      "OrgIDheader": {
        "name": "x-tenant",
        "in": "header",
        "schema": {
          "type": "string"
        },
        "description": "Organization/tenant ID",
        "required": true,
        "example": "TN-34778262-f4f0-464d-b4c6-a14e2dc6f4be"
      },
      "ParticipantRoleQuery": {
        "name": "participant_role",
        "in": "query",
        "schema": {
          "type": "string",
          "enum": [
            "CONTESTED",
            "REQUESTED"
          ]
        },
        "description": "Participant role filter",
        "required": true,
        "example": "CONTESTED"
      },
      "StatusFilterQuery": {
        "name": "status",
        "in": "query",
        "schema": {
          "type": "string",
          "enum": [
            "OPEN",
            "CLOSED",
            "CANCELLED"
          ]
        },
        "description": "Refund status filter",
        "example": "OPEN"
      }
    },
    "headers": {
      "XCidResponseHeader": {
        "description": "Request tracking identifier.",
        "schema": {
          "type": "string"
        }
      }
    },
    "schemas": {
      "AccountNumber": {
        "type": "string",
        "description": "Account number.",
        "maxLength": 20,
        "example": "98765432"
      },
      "AccountType": {
        "type": "string",
        "enum": [
          "CACC",
          "SLRY",
          "SVGS",
          "TRAN"
        ],
        "maxLength": 4,
        "description": "Account type:  \n  `CACC` - Checking account\n  `SVGS` - Savings account\n  `TRAN` - Transactional account (Brazil only). Also known as \"conta corrente\" in Portuguese, this is a bank account type designed for everyday financial transactions and is the most common type individuals and businesses use for day-to-day banking. \n  `SLRY` - Salary account. Employer deposits a fixed amount every month.\n",
        "example": "TRAN"
      },
      "Branch": {
        "type": "string",
        "description": "Bank-assigned branch ID or ISPB (Identifcador do Sistema de Pagamento Brazil) number - the Brazilian Payment System identifier, an 8-digit value.",
        "example": "011"
      },
      "ContestedParticipant": {
        "type": "string",
        "maxLength": 8,
        "description": "Challenged participant's ISPB (Identifcador do Sistema de Pagamento Brazil) number - the Brazilian Payment System identifier, an 8-digit value.",
        "example": "99999011"
      },
      "CorrelationID": {
        "type": "string",
        "format": "uuid",
        "description": "The correlation identifier is used to link related API requests and events. The Pismo engineering team can use this to track everything related to a call. If one is not passed, it is automatically generated and returned to the client in a response header.\n",
        "example": "ea8bc045-9ff7-439f-a318-2e6f974707a5"
      },
      "EffectiveRefundedAmount": {
        "type": "number",
        "description": "Actual amount refunded to the user.",
        "example": 20.1
      },
      "FundsRecoveryId": {
        "type": "string",
        "description": "Funds recovery identifier. \n\nReturned from the [Create funds recovery](https://developers.pismo.io/pismo-docs/reference/post-create-funds-recovery) endpoint.\n",
        "example": "53D0F66A-BAB0-49D7-B7DC-807B82AABD8D"
      },
      "HasMoreElements": {
        "type": "boolean",
        "description": "Are there more items?",
        "example": true
      },
      "InfractionReportID": {
        "type": "string",
        "format": "uuid",
        "maxLength": 36,
        "description": "Infraction report ID (UUID)",
        "example": "cfdff46e-5d58-45b8-b7aa-591a65f74444"
      },
      "message.DetailMessage": {
        "type": "object",
        "properties": {
          "external": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/message.ExternalMessage"
            }
          },
          "parameters": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/message.ParameterMessage"
            }
          },
          "payload": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/message.PayloadMessage"
            }
          }
        }
      },
      "message.ExternalMessage": {
        "required": [
          "code",
          "message"
        ],
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Error code",
            "example": "PBE315"
          },
          "message": {
            "type": "string",
            "description": "Error message",
            "example": "Generic error"
          }
        }
      },
      "message.Message": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Error code",
            "example": "EPDA0001"
          },
          "details": {
            "$ref": "#/components/schemas/message.DetailMessage"
          },
          "message": {
            "type": "string",
            "description": "Error message",
            "example": "User not found"
          }
        }
      },
      "message.ParameterMessage": {
        "type": "object",
        "required": [
          "field",
          "message"
        ],
        "properties": {
          "field": {
            "type": "string",
            "description": "Parameter in error",
            "example": "query parameter"
          },
          "message": {
            "type": "string",
            "description": "Error message",
            "example": "Generic error"
          }
        }
      },
      "message.PayloadMessage": {
        "type": "object",
        "required": [
          "field",
          "message"
        ],
        "properties": {
          "field": {
            "type": "string",
            "description": "Field in error",
            "example": "Entity.field"
          },
          "message": {
            "type": "string",
            "description": "Error messsage",
            "example": "Generic error"
          }
        }
      },
      "MonitorAccount": {
        "type": "boolean",
        "description": "Should the account be monitored for suspicious activity?",
        "example": false
      },
      "Participant": {
        "type": "string",
        "description": "Participant's ISPB (Identifcador do Sistema de Pagamento Brazil) number - the Brazilian Payment System identifier, an 8-digit value.",
        "maxLength": 8,
        "example": "00115678"
      },
      "Refund": {
        "type": "object",
        "required": [
          "contested_participant",
          "creation_date_time",
          "last_modified",
          "refund_amount",
          "refund_id",
          "refund_reason",
          "requesting_participant",
          "status",
          "transaction_id"
        ],
        "properties": {
          "contested_participant": {
            "$ref": "#/components/schemas/ContestedParticipant"
          },
          "creation_date_time": {
            "type": "string",
            "format": "date-time",
            "description": "Creation date time. RFC 3339 date-time value.",
            "example": "2020-08-13T13:49:03Z"
          },
          "last_modified": {
            "type": "string",
            "format": "date-time",
            "description": "Last modified date time. RFC 3339 date-time value.",
            "example": "2020-08-13T13:49:03Z"
          },
          "refund_amount": {
            "$ref": "#/components/schemas/RefundAmount"
          },
          "refund_id": {
            "type": "string",
            "description": "Refund ID",
            "example": "12345645-9ff7-439f-a318-2e6f974707a5"
          },
          "refund_reason": {
            "$ref": "#/components/schemas/RefundReason"
          },
          "requesting_participant": {
            "$ref": "#/components/schemas/RequestingParticipant"
          },
          "status": {
            "$ref": "#/components/schemas/RefundStatus"
          },
          "transaction_id": {
            "$ref": "#/components/schemas/RefundTransactionID"
          },
          "correlation_id": {
            "$ref": "#/components/schemas/CorrelationID"
          },
          "infraction_report_id": {
            "$ref": "#/components/schemas/InfractionReportID"
          },
          "refund_analysis_details": {
            "$ref": "#/components/schemas/RefundAnalysisDetails"
          },
          "refund_analysis_result": {
            "$ref": "#/components/schemas/RefundAnalysis"
          },
          "refund_details": {
            "$ref": "#/components/schemas/RefundDetails"
          },
          "refund_rejection_reason": {
            "$ref": "#/components/schemas/RefundRejectionReason"
          },
          "refund_account": {
            "$ref": "#/components/schemas/RefundAccount"
          },
          "refund_transaction_id": {
            "$ref": "#/components/schemas/RefundTransactionID"
          },
          "funds_recovery_id": {
            "$ref": "#/components/schemas/FundsRecoveryId"
          },
          "monitor_account": {
            "$ref": "#/components/schemas/MonitorAccount"
          },
          "effective_refunded_amount": {
            "$ref": "#/components/schemas/EffectiveRefundedAmount"
          }
        }
      },
      "RefundAccount": {
        "type": "object",
        "properties": {
          "tax_id_number": {
            "$ref": "#/components/schemas/TaxIdNumber"
          },
          "participant": {
            "$ref": "#/components/schemas/Participant"
          },
          "branch": {
            "$ref": "#/components/schemas/Branch"
          },
          "account_number": {
            "$ref": "#/components/schemas/AccountNumber"
          },
          "account_type": {
            "$ref": "#/components/schemas/AccountType"
          }
        }
      },
      "RefundAmount": {
        "type": "string",
        "description": "Refund amount",
        "example": "20.10"
      },
      "RefundAnalysis": {
        "type": "string",
        "description": "Respondent's refund request analysis result.",
        "example": "PARTIALLY_ACCEPTED",
        "enum": [
          "TOTALLY_ACCEPTED",
          "PARTIALLY_ACCEPTED",
          "REJECTED"
        ]
      },
      "RefundAnalysisDetails": {
        "type": "string",
        "description": "Refund analysis details",
        "example": "Details about the refund analysis."
      },
      "RefundDetails": {
        "type": "string",
        "description": "Details about refund",
        "maxLength": 2000,
        "example": "Details about the refund request"
      },
      "RefundListResponse": {
        "type": "object",
        "required": [
          "has_more_elements"
        ],
        "properties": {
          "has_more_elements": {
            "$ref": "#/components/schemas/HasMoreElements"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Refund"
            }
          }
        }
      },
      "RefundReason": {
        "type": "string",
        "description": "Refund reason. \n\n`PIX_AUTOMATICO` means a refund was requested due to failed Automatic Pix operation.\n",
        "enum": [
          "FRAUD",
          "OPERATIONAL_FLAW",
          "PIX_AUTOMATICO",
          "REFUND_CANCELLED"
        ],
        "example": "OPERATIONAL_FLAW"
      },
      "RefundRejectionReason": {
        "type": "string",
        "description": "Refund rejecton reason. \n\n**REQUIRED** when `refund_analysis_result` is `REJECTED`.\n",
        "enum": [
          "NO_BALANCE",
          "ACCOUNT_CLOSURE",
          "INVALID_REQUEST",
          "OTHER"
        ],
        "example": "NO_BALANCE"
      },
      "RefundStatus": {
        "type": "string",
        "description": "Refund status",
        "enum": [
          "OPEN",
          "CLOSED",
          "CANCELLED"
        ],
        "example": "CLOSED"
      },
      "RefundTransactionID": {
        "type": "string",
        "description": "Refund transaction ID",
        "example": "E9999901012341234123412345678900"
      },
      "RequestingParticipant": {
        "type": "string",
        "maxLength": 8,
        "description": "Requesting participant's ISPB (Identifcador do Sistema de Pagamento Brazil) number - the Brazilian Payment System identifier, an 8-digit value.",
        "example": "99999011"
      },
      "TaxIdNumber": {
        "type": "string",
        "description": "A government document number, such as a Social Security number (US) or Cadastro de Pessoas Físicas number (Brazil). Must be numeric with 11-14 digits.",
        "minLength": 11,
        "maxLength": 14,
        "example": "123412341234"
      }
    },
    "responses": {
      "400BadRequest": {
        "description": "Bad Request",
        "headers": {
          "x-cid": {
            "$ref": "#/components/headers/XCidResponseHeader"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/message.Message"
            }
          }
        }
      },
      "403Forbidden": {
        "description": "Forbidden",
        "headers": {
          "x-cid": {
            "$ref": "#/components/headers/XCidResponseHeader"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/message.Message"
            },
            "examples": {
              "EPDA0009": {
                "summary": "Missing required header 'x-tenant'",
                "value": {
                  "code": "EPDA0009",
                  "message": "Missing required header 'x-tenant'"
                }
              },
              "EPDA0010": {
                "summary": "Missing required header 'x-account-id'",
                "value": {
                  "code": "EPDA0010",
                  "message": "Missing required header 'x-account-id'"
                }
              },
              "EPDA0152": {
                "summary": "Missing required param 'id'",
                "value": {
                  "code": "EPDA0152",
                  "message": "Missing required param 'id'"
                }
              }
            }
          }
        }
      },
      "404NotFound": {
        "description": "Not Found",
        "headers": {
          "x-cid": {
            "$ref": "#/components/headers/XCidResponseHeader"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/message.Message"
            }
          }
        }
      },
      "500InternalServerError": {
        "description": "Internal server errpr",
        "headers": {
          "x-cid": {
            "$ref": "#/components/headers/XCidResponseHeader"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/message.Message"
            }
          }
        }
      },
      "502BadGateway": {
        "description": "Bad Gateway",
        "headers": {
          "x-cid": {
            "$ref": "#/components/headers/XCidResponseHeader"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/message.Message"
            },
            "examples": {
              "Provider authentication service error": {
                "value": {
                  "code": "EPDG0020",
                  "message": "Provider authentication service is unable to complete the request"
                }
              }
            }
          }
        }
      },
      "504GatewayTimeout2": {
        "description": "Gateway Timeout",
        "headers": {
          "x-cid": {
            "$ref": "#/components/headers/XCidResponseHeader"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/message.Message"
            },
            "examples": {
              "Service timeout": {
                "value": {
                  "code": "EPDA0000",
                  "message": "Timeout while executing the request"
                }
              },
              "Provider timeout": {
                "value": {
                  "code": "EPDG0000",
                  "message": "Timeout while executing the request"
                }
              }
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true,
    "samples-enabled": true
  },
  "paths": {
    "/v2/pix/refunds": {
      "get": {
        "summary": "List refunds",
        "description": "List DICT refunds for an organization.",
        "operationId": "get-list-dict-refunds",
        "tags": [
          "Refunds"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/OrgIDheader"
          },
          {
            "$ref": "#/components/parameters/ParticipantRoleQuery"
          },
          {
            "$ref": "#/components/parameters/FundsRecoveryIdQuery2"
          },
          {
            "$ref": "#/components/parameters/CIDheader"
          },
          {
            "$ref": "#/components/parameters/IncludeDetailsQuery"
          },
          {
            "$ref": "#/components/parameters/LimitQuery"
          },
          {
            "$ref": "#/components/parameters/ModifiedAfterQuery"
          },
          {
            "$ref": "#/components/parameters/ModifiedBeforeQuery"
          },
          {
            "$ref": "#/components/parameters/StatusFilterQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "List refunds",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RefundListResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/403Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/404NotFound"
          },
          "500": {
            "$ref": "#/components/responses/500InternalServerError"
          },
          "502": {
            "$ref": "#/components/responses/502BadGateway"
          },
          "504": {
            "$ref": "#/components/responses/504GatewayTimeout2"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    }
  }
}
```