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

# List Refunds

`GET /v1/refunds`

## Request

- Base URL: `https://api.xdata.kr` (the document declares no server; this is the origin it was published from)
- URL: `https://api.xdata.kr/v1/refunds`
- Auth: one of:
  - HTTP basic
  - OAuth 2 (authorization code, authorization URL `https://api.xdata.kr/oauth/authorize`, token URL `https://api.xdata.kr/oauth/token`)

환불 목록 조회.

## Query parameters

- `query` RefundListQuery, required: 환불 목록 조회 쿼리. 자동 필터(라우트 강제): - `organization_id`: 본인 조직(ADMIN은 명시 가능) - `env_scope = X-Env-Scope` 명세에 GET 목록 표가 없어 이 DTO 가 그 자리를 대신하며 함께 잠금한다(`InvoiceListQuery`/`PaymentListQuery` 패턴 동형).
  - `organization_id` integer, nullable: 조직 PK. 본인 조직 미지정 가능(라우트 주입).
  - `payment_id` integer, nullable: 결제 ID 필터 (단일 결제의 환불 이력 조회).
  - `status` string[], nullable: 상태 필터(다중). 미지정 시 전체.
  - `limit` integer: 페이지 크기.
  - `cursor` string, nullable: 이전 응답의 next_cursor.
- `env_scope` 'production' | 'real_test' | 'sandbox', nullable: 환경을 고릅니다. 값은 production · real_test · sandbox 중 하나입니다. 경로 접두(/v1/sandbox/... · /v1/test/... · /v1/production/...) · X-Env-Scope 헤더 · env_scope 쿼리 가운데 한 통로로 반드시 보내야 합니다. 빼면 자동으로 채우지 않고 거절하며, 두 통로에 서로 다른 값을 담아도 거절합니다. 거절은 HTTP 422 이고 오류 코드는 VALIDATION_ENV_SCOPE_MISMATCH 입니다.

## Headers

- `Authorization` string, nullable
- `X-Env-Scope` 'production' | 'real_test' | 'sandbox', nullable: 환경을 고릅니다. 값은 production · real_test · sandbox 중 하나입니다. 경로 접두(/v1/sandbox/... · /v1/test/... · /v1/production/...) · X-Env-Scope 헤더 · env_scope 쿼리 가운데 한 통로로 반드시 보내야 합니다. 빼면 자동으로 채우지 않고 거절하며, 두 통로에 서로 다른 값을 담아도 거절합니다. 거절은 HTTP 422 이고 오류 코드는 VALIDATION_ENV_SCOPE_MISMATCH 입니다.

## Response `200`

Successful Response

- PageEnvelopeRefundResponse
  - `items` RefundResponse[]: Page result items. Empty list allowed.
    - `refund_id` integer, required: refunds.id.
    - `organization_id` integer, required: 소유 조직 PK.
    - `payment_id` integer, required: 원 결제 ID.
    - `invoice_id` integer, nullable: 연결된 인보이스 ID. NULL 허용.
    - `env_scope` 'sandbox' | 'real_test' | 'production', required: 환경 스코프.
    - `pg_provider` 'portone' | 'toss' | 'payup' | 'offline', required: PG 사업자.
    - `provider_refund_id` string, nullable: PG 발급 환불 식별자. PG 비동기 처리 중에는 NULL일 수 있다. BFF/관리자/대사 입력용. 외부 사용자 UI 표시 권장 X.
    - `amount_minor` integer, required: 환불 금액 (minor unit). 0 과 음수는 받지 않는다.
    - `currency` 'KRW', required: 통화 코드. v1=KRW.
    - `status` 'PENDING' | 'SUCCEEDED' | 'FAILED' | 'CANCELED', required: 환불 상태 (4값 enum).
    - `reason` 'USER_REQUEST' | 'OPS_DISPUTE_RESOLUTION' | 'DUPLICATE_PAYMENT' | 'PAYMENT_FAILED_REVERSAL' | 'FRAUDULENT_PAYMENT' | 'OTHER', nullable: 환불 사유 enum. SCHEMA 자유 텍스트를 enum으로 정규화 노출 (자유 텍스트 원문은 `audit_logs.billing.refund.transition.payload.reason_raw`로 보존).
    - `requested_at` string, date-time, required: 환불 요청 시각 (aware datetime, naive 입력 시 422).
    - `confirmed_at` string, date-time, nullable: 환불 확정 시각 (SUCCEEDED 진입 시 채워짐).
    - `created_at` string, date-time, required: 환불 행 생성 시각 (aware datetime, naive 입력 시 422).
  - `next_cursor` string, nullable: Opaque cursor for next page, or null on last page.
  - `has_more` boolean: Whether another page exists. False when next_cursor is null.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/xdata/apis/xboss-api.md) · [All operations](https://skmtc.dev/xdata/apis/xboss-api/llms.txt) · [OpenAPI document](https://skmtc.dev/xdata/apis/xboss-api/revisions/816de78950db?raw)