---
title: "List Refunds"
method: GET
path: "/v1/refunds"
tags: ["PIX Refunds"]
---

# List Refunds

`GET /v1/refunds`

Retrieves a paginated list of PIX refunds for the authenticated account. Supports filtering by external_reference_id, original_transaction_id, and cursor-based pagination for efficient data retrieval.

## Query parameters

- `external_reference_id` string, nullable
- `original_transaction_id` integer, nullable
- `limit` integer, nullable
- `cursor` string, nullable

## Response `200`

Refunds retrieved successfully

- GetRefundsResponse
  - `next_cursor` string, nullable — Cursor for the next page of results. If null, there are no more results.
  - `refunds` RefundItemResponse[], required — List of refunds
    - `beneficiary` union
      - object
        - `pix_key` string, required
        - `resolved_account_number` string, nullable
        - `resolved_account_type` 'checking_account' | 'savings_account' | 'payment_account' | 'other_account' — Account types allowed in the Public API. checking_account, savings_account, payment_account, and other_account are supported.
        - `resolved_branch` string, nullable
        - `resolved_ispb` string, nullable
        - `name` string, nullable
        - `tax_id` string, nullable
      - object
        - `account_number` string, required
        - `account_type` 'checking_account' | 'savings_account' | 'payment_account' | 'other_account' — Account types allowed in the Public API. checking_account, savings_account, payment_account, and other_account are supported.
        - `branch_code` string, required
        - `ispb` string, required
        - `resolved_account_number` string, nullable
        - `resolved_account_type` 'checking_account' | 'savings_account' | 'payment_account' | 'other_account' — Account types allowed in the Public API. checking_account, savings_account, payment_account, and other_account are supported.
        - `resolved_branch` string, nullable
        - `resolved_ispb` string, nullable
        - `name` string, nullable
        - `tax_id` string, nullable
    - `cancelled_at` string, date-time, nullable — Cancellation timestamp (UTC, RFC 3339), if cancelled.
    - `created_at` string, date-time, required — Refund creation timestamp (UTC, RFC 3339).
    - `details` RefundDetailsResponse, required
      - `amount_in_cents` integer, required — Refund amount in cents
      - `message_to_payer` string, nullable — Optional message to the payer
    - `external_reference_id` string, nullable — External reference identifier provided by the client
    - `failed_message` string, nullable — Error message if the refund failed
    - `id` integer, required — Refund identifier
    - `status` 'pending' | 'processing' | 'success' | 'cancelled' | 'failed', required
    - `transaction_id` integer, required — Original transaction identifier
    - `updated_at` string, date-time, required — Last update timestamp (UTC, RFC 3339).

## Other responses

- `400` — Invalid query parameters. Error code: INVALID_REQUEST (invalid cursor format or limit out of range 1–100)
- `401` — Authentication failed
- `403` — Access denied - requires ViewTransactions permission
- `500` — Internal server error

---

[API](https://skmtc.net/kiwify/apis/conta-digital-api.md) · [All operations](https://skmtc.net/kiwify/apis/conta-digital-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/kiwify/conta-digital-api/revisions/5e009b25c245/schema)