---
title: "분쟁"
description: "Tokenz의 분쟁 알림으로 분쟁을 처리하는 방법을 알아봅니다."
source: "https://docs.tokenz.one/ko-KR/v2/disputes"
api_version: "v2"
locale: "ko-KR"
version_status: "current"
docs_stage: "prod"
---

# 분쟁

Tokenz의 분쟁 알림으로 분쟁을 처리하는 방법을 알아봅니다.

고객이 은행이나 카드사에 결제 이의를 제기하면 Tokenz가 분쟁을 생성하고 웹훅으로 알립니다. 분쟁 수명 주기를 이해하고 신속하게 대응하면 유리한 결과를 얻을 가능성을 높일 수 있습니다.

## 개요

분쟁 시스템은 다음 기능을 제공합니다.

- **실시간 알림**: 분쟁이 시작되거나 종료되면 웹훅 이벤트를 수신합니다.
- **분쟁 상세 정보**: 이의 제기된 금액, 사유, 증빙 제출 기한을 확인합니다.
- **결과 추적**: 분쟁 해결 시점과 최종 결과를 확인합니다.

## 분쟁 수명 주기

분쟁은 다음 절차를 거칩니다.

1. **분쟁 생성**: 고객이나 은행이 결제에 이의를 제기합니다.
2. **증빙 제출 기간**: `evidenceDueBy`까지 [아이템 지급 기록 등록 API](https://docs.tokenz.one/ko-KR/v2/order#delivery-registration-api)로 아이템 지급 기록을 제출할 수 있습니다.
3. **분쟁 종료**: 은행이나 카드사가 최종 결정을 내리고 결과와 함께 분쟁을 종료합니다.

### 분쟁 상태 값

분쟁은 다음 상태를 가집니다.

- `created`: 분쟁이 시작되어 해결을 기다리고 있습니다.
- `underReview`: 증빙이 제출되어 은행이나 카드사가 검토 중입니다. 이 상태에서 제출한 아이템 지급 기록은 은행이나 카드사에 전달되지 않습니다.
- `lost`: 고객에게 유리한 결정이 내려져 금액이 고객에게 반환되었습니다.
- `won`: 판매자에게 유리한 결정이 내려져 금액이 차감되지 않았습니다.

### 분쟁 결과 값

분쟁이 종료되면 `outcome` 필드가 최종 결과를 나타냅니다.

- `lost`: 은행이 고객에게 유리한 결정을 내렸습니다.
- `won`: 은행이 판매자에게 유리한 결정을 내렸습니다.

```mermaid
sequenceDiagram;
autonumber;
participant C as 은행/카드사;
participant T as Tokenz;
participant M as 판매자 앱;
C->>T: 고객 이의 제기;
T->>M: Webhook: dispute.created;
Note over T: 주문 금액 보류;
Note over M: 분쟁 상세 확인;
Note over M: 아이템 지급 기록 제출;
C->>T: 은행의 최종 결정;
T->>M: Webhook: dispute.closed;
Note over T: 금액 보류 해제;
Note over T: 패소 시 정산액 조정;
Note over M: 결과 확인 (won/lost);
```

## 분쟁 웹훅

분쟁 이벤트 알림을 받도록 웹훅을 설정하세요. Tokenz는 분쟁 생성 및 종료 시 웹훅 이벤트를 전송합니다.

### `dispute.created`

주문에 대한 새 분쟁이 시작되면 발생합니다.

```json
{
  "id": "d4584e9a-2734-4e32-8d3d-3db675ed329a",
  "object": "dispute.created",
  "createdAt": "2026-02-13T14:01:50.158Z",
  "test": true,
  "eventData": {
    "type": "dispute",
    "version": "v2",
    "data": {
      "dispute": {
        "id": "dispute_2CjCzaPskfh",
        "object": "dispute",
        "orderId": "order_2CjCq5NEAXR",
        "orderReference": "test-1770991267025",
        "amount": {
          "amount": 1000,
          "currency": "USD"
        },
        "reason": "fraudulent",
        "status": "created",
        "createdAt": "2026-02-13T14:01:50.158Z",
        "evidenceDueBy": "2026-02-13T14:02:50.158Z",
        "updatedAt": "2026-02-13T14:01:50.158Z"
      }
    }
  }
}
```

### `dispute.closed`

분쟁이 해결되면 발생합니다. `outcome` 필드로 승소 또는 패소 여부를 확인하세요.

```json
{
  "id": "aa8ac3b5-6021-4d32-8fde-da600bcf3374",
  "object": "dispute.closed",
  "createdAt": "2026-02-13T14:03:09.220Z",
  "test": true,
  "eventData": {
    "type": "dispute",
    "version": "v2",
    "data": {
      "dispute": {
        "id": "dispute_2CjCzaPskfh",
        "object": "dispute",
        "orderId": "order_2CjCq5NEAXR",
        "orderReference": "test-1770991267025",
        "amount": {
          "amount": 1000,
          "currency": "USD"
        },
        "reason": "fraudulent",
        "status": "lost",
        "outcome": "lost",
        "createdAt": "2026-02-13T14:01:50.158Z",
        "evidenceDueBy": "2026-02-13T14:02:50.158Z",
        "updatedAt": "2026-02-13T14:03:09.220Z",
        "closedAt": "2026-02-13T14:03:09.220Z"
      }
    }
  }
}
```

## 분쟁 이벤트 필드

### 최상위 필드

- `id`: 웹훅 이벤트의 고유 식별자(UUID)
- `object`: 이벤트 유형(`dispute.created` 또는 `dispute.closed`)
- `createdAt`: 이벤트 생성 시각(ISO 8601)
- `test`: 테스트 모드에서 생성된 이벤트인지 여부

### 분쟁 객체 필드

- `id`: 분쟁의 고유 식별자
- `object`: 항상 `"dispute"`
- `orderId`: 분쟁이 발생한 주문의 ID
- `orderReference`: 분쟁이 발생한 주문의 판매자 측 참조 값
- `amount`: 소비자 통화 기준 분쟁 금액


    - `amount`: 통화의 최소 단위 값(예: 센트)
    - `currency`: ISO 4217 통화 코드(예: `USD`, `JPY`)
- `reason`: 분쟁 사유입니다. 예시는 다음과 같습니다.


    - `fraudulent`: 고객이 승인하지 않은 거래라고 주장합니다.
    - `duplicate`: 고객이 중복 청구되었다고 주장합니다.
    - `product_not_received`: 고객이 상품이나 서비스를 받지 못했다고 주장합니다.
    - `product_unacceptable`: 고객이 상품이나 서비스에 결함이 있거나 설명과 다르다고 주장합니다.
    - `unrecognized`: 고객이 해당 청구를 인지하지 못합니다.
    - `general`: 일반적이거나 분류되지 않은 분쟁 사유입니다.
- `status`: 현재 분쟁 상태(`created`, `underReview`, `lost`, `won`)
- `outcome`: 종료된 분쟁의 최종 결과(`lost` 또는 `won`). `dispute.closed` 이벤트에만 포함됩니다.
- `createdAt`: 분쟁 시작 시각(ISO 8601)
- `evidenceDueBy`: 증빙 제출 기한(ISO 8601)
- `updatedAt`: 마지막 업데이트 시각(ISO 8601)
- `closedAt`: 분쟁 종료 시각(ISO 8601). `dispute.closed` 이벤트에만 포함됩니다.

## 분쟁 테스트

실제 자금에 영향 없이 테스트 모드에서 분쟁을 시뮬레이션하여 운영 전 웹훅 처리를 확인할 수 있습니다. 테스트 분쟁은 [성공한 테스트 카드 결제](https://docs.tokenz.one/ko-KR/v2/checkout/testing#complete-a-successful-test-payment)에 대해서만 생성할 수 있습니다.

### 테스트 분쟁 동작 방식

테스트 카드 결제 시 **테스트 분쟁 결과**(Test Dispute Result)를 지정하면 해당 주문에 모의 분쟁이 자동 생성됩니다. 분쟁은 전체 수명 주기를 거치며 설정된 엔드포인트로 실제 웹훅 이벤트를 전송합니다.

1. **결제 승인**: **테스트 분쟁 결과**(Test Dispute Result)를 **승소**(Won) 또는 **패소**(Lost)로 설정하고 테스트 카드 결제를 **성공**시키세요.
2. **분쟁 생성**: 몇 초 후 주문에 분쟁이 생성되고 `dispute.created` 웹훅이 전송됩니다. 주문의 분쟁 상태가 `disputed`로 변경됩니다.
3. **분쟁 종료**: 다시 몇 초 후 선택한 결과로 분쟁이 해결되고 `dispute.closed` 웹훅이 전송됩니다. 주문의 분쟁 상태가 `disputeWon` 또는 `disputeLost`로 변경됩니다.

### 테스트 분쟁 발생시키기

분쟁 결과를 선택한 후 테스트 결제를 **성공**시키면 위 [분쟁 웹훅](https://docs.tokenz.one/ko-KR/v2/disputes#dispute-webhooks) 예제와 같은 웹훅을 받습니다. `dispute.created`와 `dispute.closed`를 모두 올바르게 처리하는지 확인하세요.

|   |   |
| --- | --- |
| ![](https://docs.tokenz.one/docs/dispute_result_won.png) | ![](https://docs.tokenz.one/docs/dispute_result_lost.png) |

### 테스트 분쟁 결과

| **테스트 분쟁 결과**(Test Dispute Result) | `dispute.closed` 상태 | `dispute.closed` 결과 | 설명 |
| --- | --- | --- | --- |
| **승소**(Won) | `won` | `won` | 판매자 승소 시뮬레이션 |
| **패소**(Lost) | `lost` | `lost` | 고객 승소 시뮬레이션 |

> 테스트 분쟁 웹훅은 설정된 **테스트** 웹훅 엔드포인트로만 전송됩니다. 이벤트 수신을 위한 테스트 엔드포인트를 설정하세요.