メインコンテンツへスキップ
バージョン: 最新版

Disputes API

Disputes APIを使用すると、顧客がカード発行銀行に申請した支払い異議（チャージバック）を管理できます。顧客が支払いに異議を申し立てた場合、証拠を提出して異議に対応できます。

概要​

異議は、顧客が銀行またはクレジットカード会社に支払いについて疑問を呈した場合に発生します。一般的な理由には以下が含まれます：

  • 不正取引 - 顧客が支払いを承認していない
  • 商品未着 - 顧客が商品/サービスを受け取っていないと主張
  • 商品の問題 - 商品が説明と大きく異なる
  • 重複請求 - 顧客が複数回請求されている
  • 返金未処理 - 返金が約束されたが受け取っていない

異議のライフサイクル​

  1. Open - 顧客が異議を申請、残高から資金が引き出される
  2. Pending - 証拠を提出済み、銀行の決定待ち
  3. Won - 異議が加盟店に有利に解決、資金が返還される
  4. Lost - 異議が顧客に有利に解決、資金が永久に失われる
  5. Closed - 異議がクローズ（won/lost状態を含む）

主要な概念​

異議のステータス​

  • open - 証拠による対応を待機中
  • pending - 証拠を提出済み、発行銀行による審査中
  • won - 異議に勝訴
  • lost - 異議に敗訴

対応期限​

  • 通常、証拠を提出するまでに14〜21日の猶予があります
  • 期限を過ぎると自動的に敗訴となります
  • 異議オブジェクトのcharge_dispute_at日付を確認してください

証拠書類​

証拠はあなたのケースを強化します。以下のような書類をアップロードしてください：

  • 配達証明（追跡番号、署名入り受領書）
  • 顧客とのやり取り（メール、チャットログ）
  • 利用規約
  • 商品の説明/写真
  • 返金/キャンセルポリシー

利用可能なエンドポイント​

証拠書類のアップロードについては、Documents APIを参照してください。

ベストプラクティス​

推奨事項​

  • 異議に迅速に対応 - 期限まで待たないでください
  • 包括的な証拠を提供 - 文書は多い方が良い
  • 詳細な記録を保持 - すべての顧客とのやり取りと配達証明を保存
  • Webhookを設定 - 異議が発生したときにすぐに通知を受け取る
  • 明確な説明を使用 - 混乱を防ぐため請求に明確な説明を記載
  • 優れたカスタマーサービスを提供 - 異議の可能性を減らす

避けるべきこと​

  • 異議を無視しない - 無対応は自動的に敗訴となります
  • 無関係な証拠を提供しない - 異議の理由に対処することに集中
  • 勝訴を前提としない - 銀行は一般的に顧客を優先します
  • メール通知を待たない - リアルタイムアラートにはWebhookを使用

異議のエラーコード​

異議を管理する際に、以下のエラーコードが返される場合があります：

コードメッセージ説明
invalid_dispute"invalid dispute"パラメータ外での異議の変更
documents_locked"documents list cannot be modified"ファイルアップロードのために異議がオープンでなくなった
invalid_file_type"invalid content-type"サポートされていないファイルタイプがアップロードされた
missing_file"missing file or filename"ファイル内容なしでファイルアップロード
dispute_closed"dispute is closed"クローズ済みの異議は変更できない
dispute_not_found"dispute not found"異議IDが存在しない
deadline_passed"response deadline has passed"期限後に証拠を提出できない

Webhookイベント​

異議を監視するためにこれらのイベントを購読してください：

  • charge.dispute.create - 新しい異議が申請された
  • charge.dispute.update - 異議のステータスが変更された
  • charge.dispute.close - 異議がクローズされた（勝訴または敗訴）

関連リソース​

サポートが必要ですか？ 異議に関するサポートは support@omise.co までお問い合わせください。