--- title: "異議申し立て" description: "支払いに関する異議申し立てへの対応方法と、TokenzからのWebhook通知について説明します。" source: "https://docs.tokenz.one/ja/v3/disputes" api_version: "v3" locale: "ja" version_status: "current" docs_stage: "prod" --- # 異議申し立て 支払いに関する異議申し立てへの対応方法と、TokenzからのWebhook通知について説明します。 顧客が支払いについて銀行またはカード発行会社に異議を申し立てると、Tokenzは異議申し立てを作成し、webhookで通知します。異議申し立ての流れを理解し、迅速に対応することで、有利な結果を得る可能性が高まります。 ## 概要 Tokenzは、異議申し立てに関する以下の機能を提供します: - **リアルタイム通知**: 異議申し立てが開始または終了したときにwebhookイベントを受信 - **異議申し立ての詳細**: 異議申し立ての対象額、理由、および証拠の期限へのアクセス - **結果追跡**: 異議申し立てが解決されたタイミングと結果の把握 ## 異議申し立ての流れ 異議申し立ては以下の流れで処理されます: 1. **異議申し立ての開始**: 顧客またはその銀行が支払いについて異議を申し立てる 2. **証拠提出期間**: `evidenceDueBy`までの間に[配送登録API](https://docs.tokenz.one/ja/v3/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": "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処理が正しく動作することを確認できます。テスト用の異議申し立ては、[成功したテストカード決済](https://docs.tokenz.one/ja/v3/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)に対してのみ作成できます。 ### テスト用の異議申し立ての仕組み テストカード決済を完了する際に、 **異議申し立てのテスト結果(Test Dispute Result)** を指定することで、その注文に対するシミュレートされた異議申し立てを自動的にトリガーできます。異議申し立てはライフサイクル全体を通じて進行し、設定済みのエンドポイントに実際のwebhookイベントが送信されます: 1. **オーソリ**: 異議申し立てのテスト結果を **勝ち(Won)** または **負け(Lost)** に設定して、**成功した**テストカード決済を完了する 2. **異議申し立ての開始**: 数秒後、注文に対して異議申し立てが作成され、`dispute.created` webhookが送信される。注文に対する異議申し立てのステータスは`disputed`に変更される 3. **異議申し立ての終了**: さらに数秒後、選択した結果で異議申し立てが解決され、`dispute.closed` webhookが送信される。注文に対する異議申し立てのステータスは`disputeWon`または`disputeLost`に変更される ### テスト用の異議申し立てを発生させる 異議申し立ての結果を選択して**成功した**テストチェックアウト決済を完了すると、上記の[異議申し立てWebhook](https://docs.tokenz.one/ja/v3/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エンドポイントが設定されていることを確認してください。