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

# List refunds

`GET /refunds`

## Request

- Base URL: `https://api.natural.com`
- URL: `https://api.natural.com/refunds`
- Auth: HTTP bearer

List refunds, newest first

## Query parameters

- `customerPartyId` string: Customer party to act for (pty_*). Omit for your own account. Requires authorization from that customer.
- `paymentIntentId` string: Only refunds of this payment intent.
- `cardPaymentId` string: Only refunds of this card payment. If paymentIntentId is also supplied, both filters must match.
- `limit` integer: Maximum results per page.
- `cursor` string: Cursor from the previous page.

## Headers

- `X-Instance-ID` string, nullable

## Response `200`

Successful Response

- object
  - `data` Refund[], required
    - `id` string, required: Refund ID (rfd_*).
    - `type` 'refund', required: Resource type. Always `refund`.
    - `attributes` object, required
      - `amount` integer, required: Amount in US cents.
      - `currency` 'USD', required: Currency code.
      - `reason` 'duplicate' | 'fraudulent' | 'requestedByPayer', nullable, required: Why the refund was requested.
      - `status` 'pending' | 'succeeded' | 'failed', required: Refund status. Succeeded means the refund was processed, but the cardholder’s bank may not have posted the credit yet.
      - `failure` object, nullable, required: Failure details. Null unless the refund failed.
        - `code` string, nullable, required: Failure code, when known. New codes may be added.
        - `reason` string, nullable, required: Explanation of the failure.
      - `receiptUrl` string, nullable, required: The refunded payment's hosted receipt page, which lists this refund.
      - `createdAt` string, required: RFC 3339 timestamp when the refund was created.
      - `updatedAt` string, required: RFC 3339 timestamp when the refund was last updated.
    - `relationships` object, required
      - `paymentIntent` object, required: The intent whose payment is refunded.
        - `data` object, required: Related resource identifier.
          - `type` 'paymentIntent', required: Resource type. Always `paymentIntent`.
          - `id` string, required
      - `cardPayment` object, required: The card payment refunded.
        - `data` object, required: Related resource identifier.
          - `type` 'cardPayment', required: Resource type. Always `cardPayment`.
          - `id` string, required
      - `customerParty` object, required: The party that received the original payment.
        - `data` object, required: Related resource identifier.
          - `type` 'party', required: Resource type. Always `party`.
          - `id` string, required
  - `meta` object, required
    - `pagination` object, required
      - `hasMore` boolean, required: Whether more results are available.
      - `nextCursor` string, nullable, required: Cursor for the next page, or null when there are no more results.

## Other responses

- `400`: Validation Error
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found. Returned when the resource does not exist, or when it exists but is not accessible to your account. The two cases are intentionally indistinguishable, so that resource IDs cannot be enumerated by probing.
- `409`: Conflict
- `422`: Validation Error. The response contains one error object for each invalid request value.
- `428`: Precondition Required
- `429`: Too Many Requests
- `500`: Internal Server Error
- `501`: Not Implemented
- `502`: Bad Gateway
- `503`: Service Unavailable

## Changes

- **2026-09-29** `4fab756be152`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/natural/apis/natural-api/changes/refunds/get.md)

---

[API](https://skmtc.dev/natural/apis/natural-api.md) - [All operations](https://skmtc.dev/natural/apis/natural-api/llms.txt) - [OpenAPI document](https://skmtc.dev/natural/apis/natural-api/revisions/59c1208fa5dc?raw)