メインコンテンツへスキップ
あなたのMerchant of Recordとして、Dodo Paymentsはカードネットワークとの紛争やチャージバックのプロセスを代行して管理します。これらのウェブフックは、紛争がライフサイクルを進むに連れてシステムを同期させ、アクセスを取り消し、証拠を集め、記録を調整できるようにします。

紛争ウェブフックイベント

紛争はそのライフサイクルの各段階でイベントを発行します:
Event発生するタイミング通常の意味
dispute.openedカード保有者が支払いに関する紛争を開いたとき資金が保持されるので、対処の準備をする
dispute.challenged紛争に対抗するための証拠が提出されたとき紛争はネットワークによって審査中
dispute.accepted紛争が受け入れられた(対抗しない)資金がカード保有者に返還される
dispute.cancelled紛争が取り下げられたまたはキャンセルされたさらなる行動は不要
dispute.expired解決せずに応答期間が過ぎたとき通常、あなたに不利に解決される
dispute.won紛争があなたに有利に解決されたとき資金が保持される
dispute.lost紛争がカード保有者に有利に解決されたとき資金がカード保有者に返還される
Visa Rapid Dispute Resolution (RDR)を通じて自動解決された紛争は、dispute.lostis_resolved_by_rdr: trueとして表示されます。これは予測されたものであり、正式なチャージバックを防ぐために自動的に返金されました。

紛争イベントの処理

dispute.openedが発生すると、紛争に関する金額が即座に保持されます。このイベントを利用して記録を更新し、対抗するつもりであればダッシュボードで証拠を集めてください。
Handling dispute events
app.post('/webhooks/dodo', async (req, res) => {
  const event = req.body;

  switch (event.type) {
    case 'dispute.opened': {
      const dispute = event.data;
      // Record the dispute and consider revoking access while it is open
      await recordDispute(dispute.dispute_id, dispute.payment_id, dispute.amount);
      // Gather and submit evidence from the Dodo Payments dashboard (within 4 days)
      break;
    }
    case 'dispute.won': {
      // Funds retained — restore normal state in your records
      await markDisputeResolved(event.data.dispute_id, 'won');
      break;
    }
    case 'dispute.lost': {
      // Funds returned to the cardholder — reconcile and keep access revoked
      await markDisputeResolved(event.data.dispute_id, 'lost');
      break;
    }
  }

  res.json({ received: true });
});
処理を開始する前に常にウェブフック署名を確認してください。設定についてはウェブフックガイドを参照してください。上記のハンドラーは簡潔さのために検証を省略しています。
紛争が作成されてから4日以内に応答する必要があります。収集すべき証拠やその形式については、紛争応答のベストプラクティスを参照してください。

紛争のステータスとステージ

紛争オブジェクトは2つのフィールドを通じて進捗を報告します:
FieldValues
dispute_statusdispute_opened, dispute_expired, dispute_accepted, dispute_cancelled, dispute_challenged, dispute_won, dispute_lost
dispute_stagepre_dispute, dispute, pre_arbitration

関連情報

Managing Disputes

紛争への対応方法、証拠の提出方法、およびRDRが紛争率をどのように保護するか。

Handle Payment Failures

失敗した支払いが紛争になる前に検出して回収する。

ウェブフックペイロードスキーマ

amount
string
必須

The amount involved in the dispute, represented as a string to accommodate precision.

business_id
string
必須

The unique identifier of the business involved in the dispute.

created_at
string<date-time>
必須

The timestamp of when the dispute was created, in UTC.

currency
string
必須

The currency of the disputed amount, represented as an ISO 4217 currency code.

dispute_id
string
必須

The unique identifier of the dispute.

dispute_stage
enum<string>
必須

The current stage of the dispute process.

利用可能なオプション:
pre_dispute,
dispute,
pre_arbitration
dispute_status
enum<string>
必須

The current status of the dispute.

利用可能なオプション:
dispute_opened,
dispute_expired,
dispute_accepted,
dispute_cancelled,
dispute_challenged,
dispute_won,
dispute_lost
payment_id
string
必須

The unique identifier of the payment associated with the dispute.

is_resolved_by_rdr
boolean | null

Whether the dispute was resolved by Rapid Dispute Resolution

remarks
string | null

Remarks

最終更新日 2026年6月18日