---
title: "紛争"
description: "Tokenzの紛争通知を通じて、支払い紛争の処理方法を説明します。"
source: "https://docs.tokenz.one/ja/v2/disputes"
api_version: "v2"
locale: "ja"
version_status: "current"
docs_stage: "prod"
---

# 紛争

Tokenzの紛争通知を通じて、支払い紛争の処理方法を説明します。

顧客が銀行またはカード発行会社に対して支払いの紛争を申し立てると、Tokenzは紛争を作成し、webhookで通知します。紛争ライフサイクルを理解し、迅速に対応することで、有利な結果を得る可能性が高まります。

## 概要

紛争システムが提供する機能:

- **リアルタイム通知**: 紛争が開始または終了したときにwebhookイベントを受信
- **紛争の詳細**: 紛争金額、理由、および証拠の期限へのアクセス
- **結果追跡**: 紛争が解決されたタイミングと結果の把握

## 紛争ライフサイクル

紛争は定義されたライフサイクルに沿って進行します:

1. **紛争作成**: 顧客またはその銀行が支払いに対して紛争を申し立てる
2. **証拠提出期間**: `evidenceDueBy`までの間に[配送登録API](https://docs.tokenz.one/ja/v2/order#%E9%85%8D%E9%80%81%E8%A8%98%E9%8C%B2%E3%81%AE%E7%99%BB%E9%8C%B2)経由で配送記録を提出できる
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);
```

## 紛争Webhook

紛争イベントの通知を受け取るためにwebhookを設定します。Tokenzは、紛争が作成されたときと終了したときにwebhookイベントを送信します。

### `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`: webhookイベントの一意識別子（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`イベントにのみ存在

## 紛争のテスト

紛争連携をテストするには、テストモードで紛争をシミュレートできます。実際の資金に影響を与えることなくテストが可能です。テスト紛争を利用して、本番稼働前にwebhook処理が正しく動作することを確認できます。テスト紛争は、[成功したテストカード決済](https://docs.tokenz.one/ja/v2/checkout/testing#%E6%88%90%E5%8A%9F%E3%81%97%E3%81%9F%E3%83%86%E3%82%B9%E3%83%88%E3%81%AE%E6%94%AF%E6%89%95%E3%81%84%E3%82%92%E5%AE%8C%E4%BA%86%E3%81%99%E3%82%8B)に対してのみ作成できます。

### テスト紛争の仕組み

テストカード決済を完了する際に、**テスト紛争結果**を指定することで、その注文に対するシミュレートされた紛争を自動的にトリガーできます。紛争はライフサイクル全体を通じて進行し、設定済みのエンドポイントに実際のwebhookイベントが送信されます:

1. **オーソリ**: テスト紛争結果を**勝ち（Won）**または**負け（Lost）**に設定して、**成功した**テストカード決済を完了する
2. **紛争作成**: 数秒後、注文に対して紛争が作成され、`dispute.created` webhookが送信される。注文の紛争ステータスは`disputed`に変更される
3. **紛争終了**: さらに数秒後、選択した結果で紛争が解決され、`dispute.closed` webhookが送信される。注文の紛争ステータスは`disputeWon`または`disputeLost`に変更される

### テスト紛争のトリガー

選択した紛争結果で**成功した**テストチェックアウト決済を完了すると、上記の[紛争Webhook](https://docs.tokenz.one/ja/v2/disputes#%E7%B4%9B%E4%BA%89webhook)セクションの例と一致するwebhookを受信します。これらを使用して、連携が`dispute.created`と`dispute.closed`の両方のイベントを正しく処理することを確認してください。

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

### テスト紛争の結果

| テスト紛争結果 | `dispute.closed`ステータス | `dispute.closed`結果 | 説明 |
| --- | --- | --- | --- |
| **勝ち（Won）** | `won` | `won` | マーチャント有利で解決された紛争をシミュレート |
| **負け（Lost）** | `lost` | `lost` | 顧客有利で解決された紛争をシミュレート |

> テスト紛争のwebhookは、設定された**テスト**用webhookエンドポイントにのみ送信されます。これらのイベントを受信するために、テスト用webhookエンドポイントが設定されていることを確認してください。