Skip to content
Developer portal

dispute.updated

POST

A dispute still being worked changed. It is sent when:

  • the dispute goes under_review;
  • evidence is asked for: evidence_request says what is needed;
  • evidence_due_date is set or moved;
  • evidence is uploaded for it from the Merchant Dashboard.

Compare the dispute with the one you have to see what changed.

Authorizations

Section titled “Authorizations”

Request Body

Section titled “Request Body”
Media typeapplication/json
object
id
required

Deduplicate on this; the same event may arrive more than once.

string
object
required
string
Allowed value: event
type
required
string
created
required

A Unix timestamp.

integer
api_version
required
string
Allowed value: v1
livemode
required
boolean
tenant_id
string
merchant_id
string | null
data
required
object
object

The object as the API shows it, as of this event.

object
data
required
object
object

A customer’s challenge to one of your card payments, as you see it. The payment itself never changes: it stays succeeded, and the dispute is its own object.

object
id
required
string
object
required
string
Allowed value: dispute
amount
required

The amount disputed, in the currency’s minor unit: all of the payment, or part of it. It is taken from the funds due to you when the dispute opens, and returned if you win.

integer
currency
required

A three-letter ISO 4217 code, in lower case.

string
/^[a-z]{3}$/
payment_intent
required

The payment intent disputed.

string
status
required

open when the chargeback arrives; under_review while the operations team work the case; then won, lost or accepted, each final. See Disputes.

string
Allowed values: open under_review won lost accepted
reason
required

What kind of dispute it is, from the network’s reason code. fraud: the cardholder says they did not make the payment. authorization: the payment was not properly authorized. processing_error: it was processed wrongly, such as charged twice, late or in the wrong amount. consumer_dispute: the customer says what they paid for was not received, not as described, or cancelled, or that a refund was not given. other: a code not in these.

string
Allowed values: fraud authorization processing_error consumer_dispute other
network_reason_code
required

The card network’s own reason code for the dispute, as it gave it.

string
case_reference
required

The card network’s reference for the case. Quote it when you talk to the operations team about the dispute.

string
chargeback_cost
required

What the card provider charges for the chargeback, in the dispute’s currency and minor unit, taken from the funds due to you with amount. 0 when it charges nothing.

integer
admin_fee
required

Your platform’s own fee for handling a chargeback, if it sets one for the payment method, taken with amount. Fixed when the dispute opens. 0 when there is none. It is not returned when you win.

integer
cost_returned
required

What a won dispute gave back of chargeback_cost, in the same minor unit: returned to you with amount. 0 until the dispute is won and the card provider returns its cost, and 0 for one that is lost or accepted.

integer
debited
required

What came off your balance for the chargeback: amount, chargeback_cost and admin_fee together. 0 when charged_to is platform. It stays the same once the dispute is decided: what a win returns is amount and cost_returned. In test mode nothing moves, but it says what would have.

integer
charged_to
required

Who bore the chargeback. you: it came off your balance, as debited says. platform: the platform you take payments under bore it, and nothing came off your balance.

string
Allowed values: you platform
evidence_due_date
required

The last day to respond with evidence, as a calendar date (YYYY-MM-DD) in your platform’s time zone. It may be moved while the dispute is worked. null until it is known.

string | null format: date
evidence_request
required

What the operations team asked you to send for the case, if they asked. null otherwise.

string | null
livemode
required
boolean
created
required

When the dispute opened, as a Unix timestamp.

integer
closed
required

When it was decided, as a Unix timestamp. null while it is open or under_review.

integer | null
Example
{
  "id": "evt_0199c8b0d7e24f6a9c13b5e8d2a0",
  "object": "event",
  "type": "dispute.updated",
  "created": 1791515700,
  "api_version": "v1",
  "livemode": false,
  "tenant_id": "7d2e4f61-3a8b-4c95-b0e7-2f1a9c6d8e43",
  "merchant_id": "c4a91e2b-6f37-4d08-9b5c-e0d2f8a17b36",
  "data": {
    "object": {
      "id": "dp_0199c3f2a1b47c1e9a20d4b8f35e",
      "object": "dispute",
      "amount": 10000,
      "currency": "php",
      "payment_intent": "pi_01j9x2p4d6f8h0k2m4n6q8s0t2",
      "status": "under_review",
      "reason": "fraud",
      "network_reason_code": "10.4",
      "case_reference": "CB-2026-0001842",
      "chargeback_cost": 50000,
      "admin_fee": 0,
      "cost_returned": 0,
      "debited": 60000,
      "charged_to": "you",
      "evidence_due_date": "2026-10-18",
      "evidence_request": "Proof of delivery signed by the customer, and the order's invoice.",
      "livemode": false,
      "created": 1791446400,
      "closed": null
    }
  }
}

Responses

Section titled “Responses”

200

Section titled “200”

Received. Answer with any 2xx within 10 seconds.