紛争

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

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

概要

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

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

紛争ライフサイクル

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

紛争作成: 顧客またはその銀行が支払いに対して紛争を申し立てる
証拠提出期間: evidenceDueByまでの間に配送登録API経由で配送記録を提出できる
紛争終了: 銀行またはカード発行会社が最終判断を下し、紛争を結果とともに終了する

紛争ステータス値

紛争には以下のステータスがあります:

created: 紛争が開始され、解決を待っている状態
underReview: エビデンスが提出され、銀行またはカード発行会社による審査が行われている状態。この状態で提出された配送記録は、銀行またはカード発行会社には送信されません
lost: 顧客有利の判断が下された状態。資金は顧客に返還済み
won: マーチャント有利の判断が下された状態。資金の控除なし

紛争結果値

紛争が終了すると、outcomeフィールドに最終結果が示されます:

lost: 銀行が顧客側に有利な判断を下した
won: 銀行がマーチャント側に有利な判断を下した

図

紛争Webhook

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

`dispute.created`

注文に対して新しい紛争が開始されたときにトリガーされます:

json

{
  "id": "d4584e9a-2734-4e32-8d3d-3db675ed329a",
  "object": "dispute.created",
  "createdAt": "2026-02-13T14:01:50Z",
  "test": true,
  "eventData": {
    "type": "dispute",
    "version": "v1",
    "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:09Z",
  "test": true,
  "eventData": {
    "type": "dispute",
    "version": "v1",
    "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: イベントが作成されたタイムスタンプ（RFC3339 / 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処理が正しく動作することを確認できます。テスト紛争は、成功したテストカード決済に対してのみ作成できます。

テスト紛争の仕組み

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

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

テスト紛争のトリガー

選択した紛争結果で成功したテストチェックアウト決済を完了すると、上記の紛争Webhookセクションの例と一致するwebhookを受信します。これらを使用して、連携がdispute.createdとdispute.closedの両方のイベントを正しく処理することを確認してください。

テスト紛争の結果

必要に応じて横にスクロール

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

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