For archived content, access the previous documentation here or the previous API reference here.

Dispute Webhook Notifications

  • Updated on Sep 10, 2026
  • Published on Sep 4, 2026
Prev Next
Post
/your_dispute_webhook_url

Xendit sends a POST request to your configured endpoint whenever a dispute status changes. The payload includes the event name alongside the dispute object.

Security
HTTP
Type basic
Header parameters
x-callback-token
string

Your Xendit unique webhook token to verify the origin of the webhook. It is highly recommended for your integration to verify this value.

Body parameters
dispute_action_required

New Dispute - Action Required

{
  "event": "dispute.action_required",
  "id": "mi-dspt-f44d259f-fd9d-4de9-80de-1eef3f1506b7",
  "channel_code": "CARDS",
  "card_brands": "VISA",
  "status": "ACTION_REQUIRED",
  "currency": "USD",
  "amount": {
    "initial": "1000.00",
    "terminal": null
  },
  "created_at": "2026-03-01T19:50:51.724Z",
  "updated_at": "2026-03-01T19:50:51.724Z",
  "due_date": "2026-03-15T19:50:51.724Z",
  "note": "Please provide evidence of delivery.",
  "category": {
    "name": "fraud",
    "allowed_evidence": [
      {
        "name": "proof_of_delivery",
        "type": "FILE",
        "max_length": 5242880,
        "is_recommended": true,
        "max_evidences": 3
      },
      {
        "name": "explanation",
        "type": "TEXT",
        "max_length": 255,
        "is_recommended": false,
        "max_evidences": 3
      }
    ]
  },
  "related_disputes": [],
  "payment_id": "py-59a3cf39-2a7d-4733-a3e3-8177c78090f7",
  "reference_id": "ref-123456"
}
dispute_under_review

Dispute Under Review

{
  "event": "dispute.under_review",
  "id": "mi-dspt-f44d259f-fd9d-4de9-80de-1eef3f1506b7",
  "channel_code": "CARDS",
  "card_brands": "VISA",
  "status": "UNDER_REVIEW",
  "currency": "USD",
  "amount": {
    "initial": "1000.00",
    "terminal": null
  },
  "created_at": "2026-03-01T19:50:51.724Z",
  "updated_at": "2026-03-05T10:30:00Z",
  "due_date": "2026-03-15T19:50:51.724Z",
  "note": "Please provide evidence of delivery.",
  "category": {
    "name": "fraud",
    "allowed_evidence": [
      {
        "name": "proof_of_delivery",
        "type": "FILE",
        "max_length": 5242880,
        "is_recommended": true,
        "max_evidences": 3
      },
      {
        "name": "explanation",
        "type": "TEXT",
        "max_length": 255,
        "is_recommended": false,
        "max_evidences": 3
      }
    ]
  },
  "evidences": [
    {
      "id": "mi-dspt-evd-12345",
      "type": "FILE",
      "category_slug": "proof_of_delivery",
      "created_at": "2026-03-02T09:15:00Z",
      "filename": "delivery_receipt.pdf",
      "mime_type": "application/pdf"
    }
  ],
  "related_disputes": [],
  "payment_id": "py-59a3cf39-2a7d-4733-a3e3-8177c78090f7",
  "reference_id": "ref-123456"
}
dispute_won

Dispute Won

{
  "event": "dispute.won",
  "id": "mi-dspt-f44d259f-fd9d-4de9-80de-1eef3f1506b7",
  "channel_code": "CARDS",
  "card_brands": "VISA",
  "status": "WON",
  "status_reason": "CHALLENGED",
  "currency": "USD",
  "amount": {
    "initial": "1000.00",
    "terminal": null
  },
  "created_at": "2026-03-01T19:50:51.724Z",
  "updated_at": "2026-03-20T14:00:00Z",
  "due_date": "2026-03-15T19:50:51.724Z",
  "category": {
    "name": "fraud",
    "allowed_evidence": [
      {
        "name": "proof_of_delivery",
        "type": "FILE",
        "max_length": 5242880,
        "is_recommended": true,
        "max_evidences": 3
      },
      {
        "name": "explanation",
        "type": "TEXT",
        "max_length": 255,
        "is_recommended": false,
        "max_evidences": 3
      }
    ]
  },
  "evidences": [
    {
      "id": "mi-dspt-evd-12345",
      "type": "FILE",
      "category_slug": "proof_of_delivery",
      "created_at": "2026-03-02T09:15:00Z",
      "filename": "delivery_receipt.pdf",
      "mime_type": "application/pdf"
    }
  ],
  "related_disputes": [],
  "payment_id": "py-59a3cf39-2a7d-4733-a3e3-8177c78090f7",
  "reference_id": "ref-123456"
}
dispute_lost

Dispute Lost

{
  "event": "dispute.lost",
  "id": "mi-dspt-f44d259f-fd9d-4de9-80de-1eef3f1506b7",
  "channel_code": "CARDS",
  "card_brands": "VISA",
  "status": "LOST",
  "status_reason": "EXCEEDED_DEADLINE",
  "currency": "USD",
  "amount": {
    "initial": "1000.00",
    "terminal": null
  },
  "created_at": "2026-03-01T19:50:51.724Z",
  "updated_at": "2026-03-20T14:00:00Z",
  "due_date": "2026-03-15T19:50:51.724Z",
  "note": "Please provide evidence of delivery.",
  "category": {
    "name": "fraud",
    "allowed_evidence": [
      {
        "name": "proof_of_delivery",
        "type": "FILE",
        "max_length": 5242880,
        "is_recommended": true,
        "max_evidences": 3
      },
      {
        "name": "explanation",
        "type": "TEXT",
        "max_length": 255,
        "is_recommended": false,
        "max_evidences": 3
      }
    ]
  },
  "evidences": [
    {
      "id": "mi-dspt-evd-12345",
      "type": "FILE",
      "category_slug": "proof_of_delivery",
      "created_at": "2026-03-02T09:15:00Z",
      "filename": "delivery_receipt.pdf",
      "mime_type": "application/pdf"
    }
  ],
  "related_disputes": [],
  "payment_id": "py-59a3cf39-2a7d-4733-a3e3-8177c78090f7",
  "reference_id": "ref-123456"
}
dispute_due_date_approaching

Dispute Due Date Approaching

{
  "event": "dispute.due_date_approaching",
  "id": "mi-dspt-f44d259f-fd9d-4de9-80de-1eef3f1506b7",
  "channel_code": "CARDS",
  "card_brands": "VISA",
  "status": "ACTION_REQUIRED",
  "currency": "USD",
  "amount": {
    "initial": "1000.00",
    "terminal": null
  },
  "created_at": "2026-03-01T19:50:51.724Z",
  "updated_at": "2026-03-13T08:00:00Z",
  "due_date": "2026-03-15T19:50:51.724Z",
  "category": {
    "name": "fraud",
    "allowed_evidence": [
      {
        "name": "proof_of_delivery",
        "type": "FILE",
        "max_length": 5242880,
        "is_recommended": true,
        "max_evidences": 3
      },
      {
        "name": "explanation",
        "type": "TEXT",
        "max_length": 255,
        "is_recommended": false,
        "max_evidences": 3
      }
    ]
  },
  "related_disputes": [],
  "payment_id": "py-59a3cf39-2a7d-4733-a3e3-8177c78090f7",
  "reference_id": "ref-123456"
}
Expand All
object
event
string Required

The specific lifecycle event. dispute.action_required: dispute raised, response required. dispute.under_review: challenge submitted. dispute.won: ruled in your favor. dispute.lost: ruled against you. dispute.due_date_approaching: deadline is near.

Valid values[ "dispute.action_required", "dispute.under_review", "dispute.won", "dispute.lost", "dispute.due_date_approaching" ]
Exampledispute.action_required
id
string Required

Unique dispute identifier.

Examplemi-dspt-f44d259f-fd9d-4de9-80de-1eef3f1506b7
channel_code
string Required

Payment channel through which the original transaction was made.

ExampleCARDS
card_brands
string

Card network associated with the dispute. Only present when channel_code is CARDS.

ExampleVISA
status
string Required

Dispute status at the time this webhook was fired.

Valid values[ "ACTION_REQUIRED", "UNDER_REVIEW", "WON", "LOST" ]
ExampleACTION_REQUIRED
status_reason
string
Valid values[ "EXCEEDED_DEADLINE", "ACCEPTED", "CHALLENGED", "WITHDRAWN", "ARBITRATION", "NEED_MORE_INFORMATION" ]
ExampleEXCEEDED_DEADLINE
currency
string Required

Currency of the disputed amount, in ISO-4217 format.

ExampleUSD
amount
object (Merchant_Dispute_API_DisputeAmount) Required
initial
string Required

The amount when the dispute was first raised.

Example1000.00
terminal
string | null Required

The final resolved amount. May differ from initial for partial disputes. Null while unresolved.

Example1000.00
created_at
string (date-time) Required
Example2026-09-03T04:11:58.756Z
updated_at
string (date-time) Required
Example2026-09-03T04:14:53.499Z
due_date
string (date-time) Required

Response deadline for this dispute.

Example2026-09-10T04:11:54.917Z
note
string | null

Optional guidance message from Xendit explaining the dispute.

Example
category
object | null

Dispute category with the evidence categories allowed for it. Null when the category is not set or could not be resolved.

name
string Required

Slug of the dispute category.

Examplefraud
allowed_evidence
Array of object (Merchant_Dispute_API_PublicAllowedEvidenceCategory) Required
object
name
string Required

Evidence category slug. Use this exact value as the multipart form field name when calling POST /v1/disputes//evidences.

Examplereceipt
type
string Required

FILE requires a file upload; TEXT accepts inline text content.

Valid values[ "FILE", "TEXT" ]
ExampleFILE
max_length
integer (int64) Required

Maximum size for this evidence category. For FILE: maximum file size in bytes. For TEXT: maximum character count.

Example10485760
is_recommended
boolean Required

When true, Xendit recommends submitting this evidence type to strengthen your challenge.

Exampletrue
max_evidences
integer Required

Maximum number of evidence items accepted for this evidence category.

Example1
related_disputes
Array of string Required
string
payment_id
string | null

Xendit payment identifier for the original disputed transaction.

Examplepy-59a3cf39-2a7d-4733-a3e3-8177c78090f7
reference_id
string | null

Your reference ID for the original transaction.

Exampledispute-test-1788408708890
evidences
Array of object (Merchant_Dispute_API_EvidenceItem)

Flat list of evidence items (not grouped).

object
id
string Required

Xendit-generated unique identifier for this evidence item. Use in PATCH and DELETE evidence endpoints.

Examplemi-dspt-evd-20d5cc8a-4ba0-4378-b96f-c4bcbb8a1d0e
type
string Required

Evidence type. FILE indicates a file attachment. TEXT indicates inline text content.

Valid values[ "FILE", "TEXT" ]
ExampleFILE
category_slug
string Required

Slug of the evidence category this belongs to.

Exampleproof_of_delivery
text_content
string | null

The text content of this evidence item. Only present when type is TEXT.

ExampleThe customer completed the transaction at our store.
mime_type
string | null

MIME type of the uploaded file (e.g., application/pdf, image/jpeg). Only present when type is FILE.

Exampleapplication/pdf
filename
string | null

Original filename of the uploaded file. Only present when type is FILE.

Examplereceipt.pdf
content_hash
string | null

MD5 hash of the file content, prefixed with md5:. Only present when type is FILE.

Examplemd5:318d5cb8146d90b9f02a9fe5809583aa
created_at
string (date-time) Required

Timestamp when this evidence item was submitted, in ISO 8601 format.

Example2026-09-03T04:14:53.499Z
Responses
200

OK. The webhook was received and processed.