検索を読み込み中…

検索を読み込み中…

本文へ移動
注文ライフサイクル異議申し立て

異議申し立て

支払いに関する異議申し立てへの対応方法と、TokenzからのWebhook通知について説明します。

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

概要

Tokenzは、異議申し立てに関する以下の機能を提供します:

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

異議申し立ての流れ

異議申し立ては以下の流れで処理されます:

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

異議申し立てのステータス

異議申し立てには以下のステータスがあります:

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

異議申し立ての結果

異議申し立てが終了すると、outcomeフィールドに最終結果が示されます:

  • lost: 銀行が顧客側に有利な判断を下した
  • won: 銀行がマーチャント側に有利な判断を下した
図
図
100%
スクロールで移動・拡大して詳細を確認

異議申し立て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": "v3",
    "data": {
      "dispute": {
        "id": "dispute_2CjCzaPskfh",
        "object": "dispute",
        "orderId": "order_2CjCq5NEAXR",
        "externalOrderId": "ORDER_2024_001",
        "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": "v3",
    "data": {
      "dispute": {
        "id": "dispute_2CjCzaPskfh",
        "object": "dispute",
        "orderId": "order_2CjCq5NEAXR",
        "externalOrderId": "ORDER_2024_001",
        "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
  • externalOrderId: 異議申し立ての対象となる注文の externalOrderId(チェックアウトセッション作成時に指定した値)
  • 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処理が正しく動作することを確認できます。テスト用の異議申し立ては、成功したテストカード決済に対してのみ作成できます。

テスト用の異議申し立ての仕組み

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

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

テスト用の異議申し立てを発生させる

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

テスト用の異議申し立ての結果

必要に応じて横にスクロール
異議申し立てのテスト結果dispute.closedステータスdispute.closed結果説明
勝ち(Won)wonwonマーチャント有利で解決された異議申し立てをシミュレート
負け(Lost)lostlost顧客有利で解決された異議申し立てをシミュレート

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