> ## 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.

# 환불 및 분쟁

> 환불을 발행하고, 증거와 함께 분쟁에 대응하며, 차지백 이벤트를 수신하세요.

결제가 완료된 후에는 두 가지 일이 발생할 수 있습니다. **환불**은 여러분(또는 지원팀)이 의도적으로 발행하는 취소입니다. **분쟁**은 구매자가 은행에 제기하는 차지백입니다. 분쟁의 결과를 항상 통제할 수는 없지만, 증거를 제출하여 대응할 수 있습니다.

> [!TIP]
>
> `refund.created`, `refund.updated`, `dispute.created`, `dispute.updated`, `dispute_alert.created`에 대한 [웹훅](https://docs.whop.com/ko/developer/guides/webhooks.md)을 구독하면 폴링 없이 상태 변경을 조정할 수 있습니다.

## 환불

환불은 성공한 결제를 되돌립니다. Whop은 원래의 결제 프로세서를 통해 환불을 처리합니다. 해당 멤버십 상태는 자동으로 업데이트됩니다.

### 환불 발행

환불은 refunds 리소스에서 직접 생성하는 것이 아니라 결제에 대해 생성합니다. `payments.refund({ id })`를 호출하세요. 전액 환불이면 `partial_amount`를 생략하고, 부분 환불이면 이 값을 전달하세요.

```typescript TypeScript theme={null}
import { WhopClient } from "@whop/sdk";

const client = new WhopClient({ token: process.env.WHOP_API_KEY });

// Full refund
const fullRefund = await client.payments.refund({ id: "pay_xxxxxxxxxxxxx" });

// Partial refund
const partialRefund = await client.payments.refund({
  id: "pay_xxxxxxxxxxxxx",
  partial_amount: 5.0, // in payment currency, e.g. 5 USD
});
```

```python Python theme={null}
import os
from whop_sdk import Whop

client = Whop(token=os.environ["WHOP_API_KEY"])

# Full refund
full_refund = client.payments.refund("pay_xxxxxxxxxxxxx")

# Partial refund
partial_refund = client.payments.refund(
    "pay_xxxxxxxxxxxxx",
    partial_amount=5.0,
)
```

```ruby Ruby theme={null}
require "whop_sdk"

client = Whop_sdk::Client.new(token: ENV.fetch("WHOP_API_KEY"))

# Full refund
full_refund = client.payments.refund(id: "pay_xxxxxxxxxxxxx")

# Partial refund
partial_refund = client.payments.refund(
  id: "pay_xxxxxxxxxxxxx",
  partial_amount: 5.0,
)
```

```rust Rust theme={null}
use whop_sdk::prelude::*;

let config = ClientConfig {
    token: Some(std::env::var("WHOP_API_KEY").unwrap()),
    ..Default::default()
};
let client = Whop::new(config).expect("Failed to build client");

// Full refund
let full_refund = client
    .payments
    .refund(&"pay_xxxxxxxxxxxxx".to_string(), &RefundPaymentsRequest::default(), None)
    .await?;

// Partial refund
let partial_refund = client
    .payments
    .refund(
        &"pay_xxxxxxxxxxxxx".to_string(),
        &RefundPaymentsRequest {
            partial_amount: Some(5.0), // in payment currency, e.g. 5 USD
        },
        None,
    )
    .await?;
```

```go Go theme={null}
import (
    "context"
    "log"
    "os"

    whopsdk "github.com/whopio/whopsdk-go/v2"
    "github.com/whopio/whopsdk-go/v2/client"
    "github.com/whopio/whopsdk-go/v2/option"
)

client := client.NewWhop(option.WithToken(os.Getenv("WHOP_API_KEY")))

// Full refund
_, err := client.Payments.Refund(context.TODO(), &whopsdk.RefundPaymentsRequest{
    ID: "pay_xxxxxxxxxxxxx",
})
if err != nil {
    log.Fatal(err)
}

// Partial refund
_, err = client.Payments.Refund(context.TODO(), &whopsdk.RefundPaymentsRequest{
    ID:            "pay_xxxxxxxxxxxxx",
    PartialAmount: whopsdk.Float64(5.0), // in payment currency, e.g. 5 USD
})
if err != nil {
    log.Fatal(err)
}
```

응답은 업데이트된 `Payment` 객체입니다. `refunded_amount` 필드는 누적 환불 총액을 반영합니다. 하나의 결제에 대해 전체 금액까지 `refund`를 여러 번 호출할 수 있습니다.

> [!NOTE]
>
> 필요한 권한: `payment:manage`. 앱을 게시하기 전에 [권한 가이드](https://docs.whop.com/ko/developer/guides/permissions.md)에서 추가하세요.

### 환불 조회

나중에 환불을 조회해야 하는 경우를 위해 환불에는 별도의 리소스가 있습니다.

```typescript TypeScript theme={null}
const refund = await client.refunds.retrieve({ id: "ref_xxxxxxxxxxxxx" });

const refunds = await client.refunds.list({
  account_id: "biz_xxxxxxxxxxxxx",
});

for await (const item of refunds) {
  console.log(item);
}
```

```python Python theme={null}
refund = client.refunds.retrieve("ref_xxxxxxxxxxxxx")

for item in client.refunds.list(account_id="biz_xxxxxxxxxxxxx"):
    print(item)
```

```ruby Ruby theme={null}
refund = client.refunds.retrieve(id: "ref_xxxxxxxxxxxxx")

client.refunds.list(account_id: "biz_xxxxxxxxxxxxx").each do |item|
  puts item
end
```

```rust Rust theme={null}
let refund = client
    .refunds
    .retrieve(&"ref_xxxxxxxxxxxxx".to_string(), None)
    .await?;

let refunds = client
    .refunds
    .list(
        &RefundsListQueryRequest {
            account_id: Some("biz_xxxxxxxxxxxxx".to_string()),
            ..Default::default()
        },
        None,
    )
    .await?;

for item in refunds.data {
    println!("{item:?}");
}
```

```go Go theme={null}
refund, err := client.Refunds.Retrieve(context.TODO(), &whopsdk.RetrieveRefundsRequest{
    ID: "ref_xxxxxxxxxxxxx",
})
if err != nil {
    log.Fatal(err)
}
fmt.Println(refund)

page, err := client.Refunds.List(context.TODO(), &whopsdk.ListRefundsRequest{
    AccountID: whopsdk.String("biz_xxxxxxxxxxxxx"),
})
if err != nil {
    log.Fatal(err)
}

iter := page.Iterator()
for iter.Next(context.TODO()) {
    fmt.Println(iter.Current())
}
if err := iter.Err(); err != nil {
    log.Fatal(err)
}
```

## 분쟁

분쟁(차지백)은 구매자의 은행이 결제에 이의를 제기할 때 시작됩니다. 은행이 결정을 내리기 전에 증거로 대응할 수 있는 기간이 주어집니다. Whop이 분쟁을 여러분에게 전달하면, 여러분이 증거를 제출하고, 은행이 판정을 내린 뒤 분쟁이 종료됩니다.

### 수신되는 분쟁 확인

구독해야 할 세 가지 이벤트:

| 이벤트 | 의미 |
| - | - |
| [`dispute_alert.created`](https://docs.whop.com/ko/api-reference/dispute-alerts/dispute-alert-created) | 정식 분쟁 이전의 분쟁 알림입니다. 일부 프로세서는 사전 알림을 제공합니다. 모든 알림이 분쟁으로 이어지지는 않습니다. |
| [`dispute.created`](https://docs.whop.com/ko/api-reference/disputes/dispute-created) | 정식 분쟁이 시작되었습니다. 대응 기간이 시작됩니다. |
| [`dispute.updated`](https://docs.whop.com/ko/api-reference/disputes/dispute-updated) | 상태 변경(예: `needs_response`에서 `under_review`로, 이후 `won` 또는 `lost`로). |

### 목록 조회 및 단건 조회

```typescript TypeScript theme={null}
const disputes = await client.disputes.list({
  account_id: "biz_xxxxxxxxxxxxx",
});

for await (const item of disputes) {
  console.log(item);
}

const dispute = await client.disputes.retrieve({ id: "dspt_xxxxxxxxxxxxx" });
```

```python Python theme={null}
for item in client.disputes.list(account_id="biz_xxxxxxxxxxxxx"):
    print(item)

dispute = client.disputes.retrieve("dspt_xxxxxxxxxxxxx")
```

```ruby Ruby theme={null}
client.disputes.list(account_id: "biz_xxxxxxxxxxxxx").each do |item|
  puts item
end

dispute = client.disputes.retrieve(id: "dspt_xxxxxxxxxxxxx")
```

```rust Rust theme={null}
let disputes = client
    .disputes
    .list(
        &DisputesListQueryRequest {
            account_id: Some("biz_xxxxxxxxxxxxx".to_string()),
            ..Default::default()
        },
        None,
    )
    .await?;

for item in disputes.data {
    println!("{item:?}");
}

let dispute = client
    .disputes
    .retrieve(&"dspt_xxxxxxxxxxxxx".to_string(), None)
    .await?;
```

```go Go theme={null}
page, err := client.Disputes.List(context.TODO(), &whopsdk.ListDisputesRequest{
    AccountID: whopsdk.String("biz_xxxxxxxxxxxxx"),
})
if err != nil {
    log.Fatal(err)
}

iter := page.Iterator()
for iter.Next(context.TODO()) {
    fmt.Println(iter.Current())
}
if err := iter.Err(); err != nil {
    log.Fatal(err)
}

dispute, err := client.Disputes.Retrieve(context.TODO(), &whopsdk.RetrieveDisputesRequest{
    ID: "dspt_xxxxxxxxxxxxx",
})
if err != nil {
    log.Fatal(err)
}
fmt.Println(dispute)
```

### 증거로 대응

분쟁 대응은 두 단계로 이루어집니다. `disputes.update`로 증거를 준비한 다음 `disputes.submit`으로 제출합니다. update는 멱등적입니다. 제출하기 전까지 필드를 수정할 수 있습니다.

```typescript TypeScript theme={null}
// Stage evidence (call as many times as needed)
await client.disputes.update({
  id: "dspt_xxxxxxxxxxxxx",
  evidence: {
    customer_name: "Jane Doe",
    customer_email_address: "jane@example.com",
    product_description: "Annual subscription to Acme Pro, purchased 2026-01-15.",
    service_date: "2026-01-15",
    refund_policy_disclosure: "Customer agreed to no-refunds policy at checkout.",
    notes: "Customer used the product 47 times across 8 sessions before disputing.",
  },
});

// Submit evidence to the processor. After this, you can no longer edit.
await client.disputes.submit({ id: "dspt_xxxxxxxxxxxxx" });
```

```python Python theme={null}
client.disputes.update(
    "dspt_xxxxxxxxxxxxx",
    evidence={
        "customer_name": "Jane Doe",
        "customer_email_address": "jane@example.com",
        "product_description": "Annual subscription to Acme Pro, purchased 2026-01-15.",
        "service_date": "2026-01-15",
        "refund_policy_disclosure": "Customer agreed to no-refunds policy at checkout.",
        "notes": "Customer used the product 47 times across 8 sessions before disputing.",
    },
)

client.disputes.submit("dspt_xxxxxxxxxxxxx")
```

```ruby Ruby theme={null}
# Stage evidence (call as many times as needed)
client.disputes.update(
  id: "dspt_xxxxxxxxxxxxx",
  evidence: {
    customer_name: "Jane Doe",
    customer_email_address: "jane@example.com",
    product_description: "Annual subscription to Acme Pro, purchased 2026-01-15.",
    service_date: "2026-01-15",
    refund_policy_disclosure: "Customer agreed to no-refunds policy at checkout.",
    notes: "Customer used the product 47 times across 8 sessions before disputing.",
  },
)

# Submit evidence to the processor. After this, you can no longer edit.
client.disputes.submit(id: "dspt_xxxxxxxxxxxxx")
```

```rust Rust theme={null}
// Stage evidence (call as many times as needed)
client
    .disputes
    .update(
        &"dspt_xxxxxxxxxxxxx".to_string(),
        &UpdateDisputesRequest {
            evidence: Some(DisputesUpdateDisputesRequestEvidence {
                customer_name: Some("Jane Doe".to_string()),
                customer_email_address: Some("jane@example.com".to_string()),
                product_description: Some(
                    "Annual subscription to Acme Pro, purchased 2026-01-15.".to_string(),
                ),
                service_date: Some("2026-01-15".to_string()),
                refund_policy_disclosure: Some(
                    "Customer agreed to no-refunds policy at checkout.".to_string(),
                ),
                notes: Some(
                    "Customer used the product 47 times across 8 sessions before disputing.".to_string(),
                ),
                ..Default::default()
            }),
        },
        None,
    )
    .await?;

// Submit evidence to the processor. After this, you can no longer edit.
client
    .disputes
    .submit(&"dspt_xxxxxxxxxxxxx".to_string(), None)
    .await?;
```

```go Go theme={null}
// Stage evidence (call as many times as needed)
_, err := client.Disputes.Update(context.TODO(), &whopsdk.UpdateDisputesRequest{
    ID: "dspt_xxxxxxxxxxxxx",
    Evidence: &whopsdk.UpdateDisputesRequestEvidence{
        CustomerName:           whopsdk.String("Jane Doe"),
        CustomerEmailAddress:   whopsdk.String("jane@example.com"),
        ProductDescription:     whopsdk.String("Annual subscription to Acme Pro, purchased 2026-01-15."),
        ServiceDate:            whopsdk.String("2026-01-15"),
        RefundPolicyDisclosure: whopsdk.String("Customer agreed to no-refunds policy at checkout."),
        Notes:                  whopsdk.String("Customer used the product 47 times across 8 sessions before disputing."),
    },
})
if err != nil {
    log.Fatal(err)
}

// Submit evidence to the processor. After this, you can no longer edit.
if _, err := client.Disputes.Submit(context.TODO(), &whopsdk.SubmitDisputesRequest{
    ID: "dspt_xxxxxxxxxxxxx",
}); err != nil {
    log.Fatal(err)
}
```

### 증거 필드

모든 필드는 선택 사항이지만, 더 많이 제공할수록 대응이 강력해집니다. 자주 사용하는 필드:

| 필드 | 입력할 내용 |
| - | - |
| `customer_name` / `customer_email_address` | 보유하고 있는 고객 식별 정보 |
| `product_description` | 고객이 구매한 항목을 쉬운 말로 설명 |
| `service_date` | 서비스를 제공한 날짜(국제표준화기구(ISO) 8601) |
| `billing_address` | 결제 시 사용된 주소 |
| `customer_communication_attachment` | 고객이 참여했음을 보여주는 이메일 또는 채팅 스레드 |
| `cancellation_policy_attachment` / `cancellation_policy_disclosure` | 취소 정책 및 고객이 이에 동의했다는 증거 |
| `refund_policy_attachment` / `refund_policy_disclosure` | 환불에 대해 동일 |
| `refund_refusal_explanation` | 환불하지 않은 이유(예: 반품 기간 이후의 사용) |
| `access_activity_log` | 고객이 상품을 사용했음을 증명하는 로그인 또는 사용 로그 |
| `uncategorized_attachment` | 그 밖의 관련 자료 |

첨부 파일 필드는 업로드된 파일을 `{ id: file.id }` 형식으로 받습니다. 먼저 [Files API](https://docs.whop.com/ko/developer/guides/upload-files.md)를 통해 업로드하세요.

### 분쟁 상태

분쟁은 상태 머신을 따라 진행됩니다. 두 단계가 있습니다: 조기 경고 단계(`warning_` 접두사가 붙은 상태로, `dispute_alert.created`를 통해 표시됨)와 정식 분쟁 단계입니다. SDK가 반환할 수 있는 모든 상태:

| 상태 | 단계 | 의미 |
| - | - | - |
| `warning_needs_response` | 알림 | 분쟁 알림이 열려 있습니다. 확대되기 전에 환불이나 대응으로 선제 조치할 수 있습니다. |
| `warning_under_review` | 알림 | 알림에 대응했으며, 프로세서가 확대 여부를 결정하는 중입니다. |
| `warning_closed` | 알림 | 정식 분쟁으로 이어지지 않고 알림이 해결되었습니다. |
| `needs_response` | 분쟁 | 정식 분쟁이 열려 있습니다. 대응 기간이 끝나기 전에 증거를 제출하세요. |
| `under_review` | 분쟁 | 증거를 제출했으며, 프로세서가 결정하는 중입니다. |
| `won` | 분쟁 | 자금이 여러분에게 남습니다. |
| `lost` | 분쟁 | 자금이 구매자에게 반환됩니다. Whop이 원래 결제를 취소합니다. |
| `prevented` | 분쟁 | 판정 전에 고객에게 환불되었습니다. `lost`와 동일하게 정산됩니다. |

> [!NOTE]
>
> 분쟁에서 **패소**하면 Whop은 Refund 레코드를 자동으로 생성하지 않으며, 직접 생성할 수도 없습니다. `payments.refund`는 분쟁 중인 결제에 대한 호출을 `This payment has been disputed. Therefore, it cannot be refunded.` 메시지와 함께 거부합니다. 패소한 분쟁을 기준 정보로 추적하고, `refund.created` 이벤트를 기대하지 마세요.

## 권한

| 작업 | 필요한 권한 |
| - | - |
| 환불 생성 | `payment:manage` |
| 환불 조회 / 목록 조회 | `payment:basic:read` |
| 분쟁 조회 / 목록 조회 | `payment:dispute:read` |
| 증거 업데이트 또는 제출 | `payment:dispute` |

[권한 가이드](https://docs.whop.com/ko/developer/guides/permissions.md)에서 이 권한들을 추가하세요.

## 다음 단계

> [card] [결제 받기](https://docs.whop.com/ko/developer/guides/accept-payments.md)
>
> 나중에 환불하거나 방어하게 될 결제를 생성하는 흐름입니다.

> [card] [웹훅 수신](https://docs.whop.com/ko/developer/guides/webhooks.md)
>
> 서버 측에서 환불 및 분쟁 이벤트에 대응하세요.

> [card] [파일 업로드](https://docs.whop.com/ko/developer/guides/upload-files.md)
>
> 분쟁 대응을 위한 증거 첨부 파일을 업로드하세요.

> [card] [Disputes API 레퍼런스](https://docs.whop.com/ko/api-reference/disputes/dispute)
>
> 전체 리소스: 필드, 상태 및 모든 엔드포인트.


## Related topics

- [선호 정산 통화](https://docs.whop.com/ko/developer/payouts/preferred-settlement-currency.md)
- [Stats API 레퍼런스](https://docs.whop.com/ko/api-reference/stats/stats.md)
- [결제 개요](https://docs.whop.com/ko/developer/payments/overview.md)
