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

> ## Agent Instructions
> Treat these docs and the Whop MCP server as the source of truth for Whop API behavior. Don't infer endpoint behavior from marketing pages.
> MCP server: connect https://mcp.whop.com/mcp (streamable HTTP, browser sign-in, no API key in the client config) to search these docs and read or change live Whop data. Setup: https://docs.whop.com/developer/guides/ai_and_mcp.md
> Whop CLI: install with `curl -fsSL https://whop.com/install.sh | sh` to scaffold, run, and deploy Whop apps and websites. It acts on production, not the sandbox. Overview: https://docs.whop.com/cli/overview.md Agent mode: https://docs.whop.com/cli/agent-mode.md
> Hosting: Whop serves a site or app from the build `whop apps deploy` uploads, with rollbacks, secrets, and server logs. Guide: https://docs.whop.com/developer/websites/hosting.md
> Plugins: in Claude Code, run `/plugin marketplace add whopio/plugins`, then `/plugin install whop@whop`. Guide: https://docs.whop.com/developer/guides/plugins/claude-code.md Every agent tool: https://docs.whop.com/developer/ai/overview.md
> Environments: build and test in the sandbox (API `https://sandbox-api.whop.com/api/v1`, keys at https://sandbox.whop.com/dashboard/developer, SDK environment `Sandbox`; no real money). Production (API `https://api.whop.com/api/v1`, keys at https://whop.com/dashboard/developer, SDK environment `Production`, the SDK default) moves real money, so use it only at launch. The two share no accounts, keys, products, or webhooks, and their keys look identical: never mix them. Sandbox guide: https://docs.whop.com/developer/guides/sandbox.md Comparison: https://docs.whop.com/developer/quickstart.md
> API: send `Authorization: Bearer <API_KEY>` from your server only, and pin a dated version with the `Api-Version-Date` header. OpenAPI spec: https://api.whop.com/api/v1/openapi.json
> Which API: build on the Current API, whose pages live under https://docs.whop.com/api-reference/ (start at https://docs.whop.com/api-reference/overview.md). Pages under /api-reference/legacy/ are the Legacy API. Use one only when https://docs.whop.com/api-reference/stability.md lists the resource as Legacy-only.

# Dispute Alerts API

> 분쟁 알림(Dispute alert)은 정산된 결제에 이의가 제기되고 있음을 카드 발급사가 차지백 이전에 미리 알리는 조기 경고입니다.

`type`은 사기 신고(`early_fraud_warning`), 분쟁 전 통지(`dispute_alert`), 네트워크가 환불로 이미 종결한 Visa RDR 사례(`rapid_dispute_resolution`)를 구분합니다.

Dispute alerts API를 사용하여 계정의 알림을 조회하고, 유형 또는 결제별로 필터링하고, `actionable`을 확인하여 환불로 아직 차지백을 피할 수 있는지 알아볼 수 있습니다.

## 엔드포인트

| 엔드포인트 | 요청 |
| - | - |
| [분쟁 알림 목록 조회](https://docs.whop.com/ko/api-reference/dispute-alerts/list-dispute-alerts.md) | GET `/dispute_alerts` |
| [분쟁 알림 조회](https://docs.whop.com/ko/api-reference/dispute-alerts/retrieve-dispute-alert.md) | GET `/dispute_alerts/{id}` |

## 속성

**id** `string` *required*

분쟁 알림 ID이며, 접두사는 `dspa_`입니다.

**account\_id** `string | null` *required*

알림이 발생한 결제가 속한 계정으로, 접두사는 `biz_`입니다. 알림이 매칭되지 않은 동안에는 `null`입니다.

**amount** `number` *required*

알림 대상 금액으로, `currency`의 정수 단위입니다. 발급사가 보고한 금액이며, 결제 자체 금액과 다를 수 있습니다.

**auto\_refunded** `boolean` *required*

Whop이 알림 대상 결제를 자동으로 환불했는지 여부입니다. 결제 기준으로 반영되므로, 같은 결제에 대해 다른 흐름(RDR, 해결)으로 발행된 환불의 경우에도 `true`일 수 있습니다.

**card\_brand** `string | null` *required*

발급사가 보고한 카드 네트워크로, 소문자입니다(예: `visa` 또는 `mastercard`). 보고서에 네트워크나 인식 가능한 BIN이 없으면 `unknown`입니다.

**category** `string | null` *required*

카드 소지자의 주장입니다. 결제를 하지 않았다고 주장하는 경우 `fraud`이며, `early_fraud_warning`은 항상 이 값이고, 사기 사유로 접수된 Ethoca 사기 알림과 Visa RDR 사례도 해당합니다. 결제는 했지만 이의를 제기하는 경우(예: 상품 미수령 또는 구독 취소) `customer_dispute`입니다. 발급사의 거래 문서 요청처럼 알림에 주장이 없으면 `null`입니다.

사용 가능한 옵션: `fraud`, `customer_dispute`

**created\_at** `string` *required*

Whop이 알림을 받은 시점으로, ISO 8601 타임스탬프입니다.

**currency** `string` *required*

알림 대상 금액의 세 글자 ISO 통화 코드입니다.

**fee** `object | null` *required*

계정에 청구된 알림 수수료로, 징수된 통화 기준입니다. `fee_charged`가 false이면 `null`입니다.

> [accordion] 속성
>
> **amount** `string` *required*
>
> 주요 단위 금액으로, 정확한 십진수 문자열입니다. 예를 들어 `"10.00"`은 10달러입니다. 전송 중에 부동소수점으로 반올림되지 않도록 문자열로 제공됩니다.
>
> **currency** `string` *required*
>
> 세 글자 ISO 4217 통화 코드로, 소문자입니다.
>
> **decimals** `integer` *required*
>
> 금액의 소수점 자릿수입니다. 청구 자체가 처리되는 정밀도입니다.
>
> **display\_decimals** `integer` *required*
>
> 표시할 소수점 자릿수입니다. 일반적으로 `decimals`와 같지만 항상 같은 것은 아닙니다. 예를 들어 COP는 센타보 단위로 청구되지만 페소 단위로 표기되므로 각각 `2`와 `0`입니다. 이 값을 사용하여 자신의 로캘에 맞게 숫자를 포맷하세요.

**fee\_charged** `boolean` *required*

Whop이 이 알림에 대해 계정에 알림 수수료를 청구했는지 여부입니다. `early_fraud_warning`의 경우 Whop이 비용을 청구받지 않으며 전가하지도 않으므로 항상 `false`입니다.

**issuer** `string | null` *required*

지원 중단됨: Whop 자체 대시보드 외에서는 항상 `null`입니다. 카드를 발급하고 보고서를 접수한 은행의 이름입니다. 지원 중단됨: Whop 자체 대시보드 외에서는 항상 null입니다.

**payment\_id** `string | null` *required*

발급사가 보고한 결제로, 접두사는 `pay_`입니다. Whop이 보고서를 결제와 매칭하지 못한 경우 `null`입니다.

**product\_id** `string | null` *required*

알림 대상 결제의 상품으로, 접두사는 `prod_`입니다.

**reported\_at** `string` *required*

발급사가 보고서를 접수한 시점으로, ISO 8601 타임스탬프입니다. Whop이 보고서를 받은 시점인 `created_at`보다 이전입니다.

**source** `string | null` *required*

알림을 보낸 네트워크 프로그램으로, `type`만으로는 구분되지 않습니다. Mastercard Ethoca는 `ethoca`, Visa Verifi CDRN은 `cdrn`, Visa RDR은 `rdr`, Visa / Mastercard 사기 신고는 `tc40` / `safe`, PayPal 알림은 `paypal`입니다. 네트워크가 알려주지 않은 경우 `null`입니다.

사용 가능한 옵션: `ethoca`, `cdrn`, `rdr`, `tc40`, `safe`, `paypal`

**transaction\_at** `string | null` *required*

보고된 거래가 이루어진 시점으로, ISO 8601 타임스탬프입니다. 발급사의 보고서에 시점이 없으면 매칭된 결제가 이루어진 시점으로 대체됩니다. 실제로는 `null`이 아니어야 하며, `null`인 경우 예상된 동작이 아니라 데이터 문제로 간주하세요.

**type** `string` *required*

발급사가 보낸 내용입니다. `early_fraud_warning`은 정산된 결제에 대한 사기 신고(Visa TC40 / Mastercard SAFE)로, 환불하면 여전히 차지백을 피할 수 있으며 Whop은 이에 대해 수수료를 청구하지 않습니다. `dispute_alert`는 발급사의 알림 네트워크에서 보낸 분쟁 전 통지로, Whop이 비용을 지불하고 수수료로 전가합니다. `rapid_dispute_resolution`은 네트워크가 결제를 환불하여 이미 종결한 Visa RDR 사례로, 더 이상 조치할 것이 없습니다.

사용 가능한 옵션: `early_fraud_warning`, `dispute_alert`, `rapid_dispute_resolution`

**updated\_at** `string` *required*

알림이 마지막으로 변경된 시점으로, ISO 8601 타임스탬프입니다.

```json DisputeAlert theme={null}
{
	"id": "dspa_xxxxxxxxxxxxx",
	"type": "dispute_alert",
	"source": "ethoca",
	"category": "fraud",
	"amount": 69.95,
	"currency": "usd",
	"card_brand": "visa",
	"issuer": null,
	"account_id": "biz_xxxxxxxxxxxxxx",
	"payment_id": "pay_xxxxxxxxxxxxxx",
	"product_id": "prod_xxxxxxxxxxxxx",
	"fee_charged": true,
	"fee": {
		"amount": "20.00",
		"currency": "usd",
		"decimals": 2,
		"display_decimals": 2
	},
	"auto_refunded": false,
	"reported_at": "2026-08-10T17:37:09.000Z",
	"transaction_at": "2026-08-02T00:00:00.000Z",
	"created_at": "2026-08-10T21:39:26.668Z",
	"updated_at": "2026-08-10T21:39:28.137Z"
}
```
