Wallet Dispute Message Added

wallet-dispute-message-added tells you that someone wrote on a wallet dispute's thread. The holder and your team share one thread per dispute.

When it fires

The holder posts a message.
You post a message with Create Wallet Dispute Message.

When the holder answers a dispute that is needs-more-info, you also receive wallet-dispute-status-changed, because the dispute goes back to under-review. The two events can arrive in either order.

The event is sent as soon as the message is saved. Files attached to the message appear on the thread only once they finish uploading, which can be after the event arrives.

What to do

Read the thread with List Wallet Dispute Messages and find the message whose ID is messageId.
Ignore messages your own team posted, if you do not need them.

Payload

data is the dispute plus the new messageId. The dispute is as Get Wallet Dispute returns it, without holderId and takenOver, read when the webhook is sent. Fields with no value are omitted. Amounts use the Money object.

Field	Type	Description
`messageId`	string	ID of the message that was added, for example `DM-01JD8E5G7J9L1N3Q5S7U9W1Y3A`. Only on this event.
`disputeId`	string	Dispute ID, for example `DS-01JD7C3E5G7J9L1N3Q5S7U9W1Y`.
`walletId`	string	ID of the wallet the dispute is about.
`status`	string	Where the dispute stands. See Dispute statuses.
`reasonCode`	string	Why the holder disputes the entry. See Reason codes.
`disputedAmount`	Money	Amount the holder claims. Never more than what could still be claimed when the dispute was filed.
`subjectEntryId`	string	ID of the wallet entry being disputed.
`subjectEntryType`	string	Kind of entry disputed: `deposit` (a card load) or `charge` (a spend from the wallet). Absent on older disputes, which are all deposits.
`transactionId`	string	ID of the checkout transaction that paid for the load. Set for `deposit` disputes only.
`holderStatement`	string	The holder's own explanation. Always set when `reasonCode` is `other`.
`responseDueAt`	string	Deadline for the holder to answer, in ISO 8601 UTC. Set while `status` is `needs-more-info`.
`outcome`	string	What was agreed. Set when `status` is `accepted`. See Outcomes.
`agreedAmount`	Money	Amount agreed, which can be less than `disputedAmount`. Set when `status` is `accepted`.
`declineReason`	string	Why the dispute was declined. The holder sees this text. Set when `status` is `declined`.
`createdAt`	string	When the holder filed the dispute, in ISO 8601 UTC.
`updatedAt`	string	When the dispute last changed, in ISO 8601 UTC.

Dispute statuses

Status	Meaning
`open`	Filed. Nobody has picked it up yet.
`under-review`	Being reviewed, by you or by Payment Labs.
`needs-more-info`	Waiting for the holder to answer, before `responseDueAt`.
`accepted`	Final. Decided in the holder's favour, with an `outcome` and `agreedAmount`.
`declined`	Final. Decided against the holder, with a `declineReason`.
`withdrawn`	Final. The holder cancelled the dispute.
`expired`	Final. The holder did not answer before `responseDueAt`.
`superseded-by-chargeback`	Final. The card issuer reversed the payment first, so the dispute no longer applies.

New statuses may be added. Treat a value you do not recognise as "in progress" and fetch the dispute.

Reason codes

Code	Meaning
`unauthorized`	The holder says they did not make the transaction.
`duplicate-charge`	The holder says they were charged twice.
`incorrect-amount`	The holder says the amount is wrong.
`not-credited`	The holder paid for a load, but the wallet was never credited.
`other`	Anything else. `holderStatement` explains it.

Outcomes

Outcome	Meaning
`card-refund`	Refund the card that paid for the load. Deposits only.
`wallet-credit`	Credit the wallet from your funds. Does not reverse the card.
`complete-credit`	Credit the wallet with the load it never received. Deposits only.

Accepting a dispute records the outcome only. Money moves when the dispute is resolved with Resolve Wallet Dispute.

Example

The full request body Payment Labs sends:

{
  "payorId": "6f1c2a7e-4b8d-4e0f-9a3c-2d5b7e9f1a04",
  "event": "wallet-dispute-message-added",
  "timestamp": "2026-04-11T08:40:52.517Z",
  "data": {
    "disputeId": "DS-01JD7C3E5G7J9L1N3Q5S7U9W1Y",
    "walletId": "W-01JC2R4T6V8X0Z2B4D6F8H0K2M",
    "status": "under-review",
    "reasonCode": "incorrect-amount",
    "disputedAmount": {
      "value": 40,
      "wholeValue": 4000,
      "currency": "USD",
      "formattedValue": "$40.00",
      "digits": 2
    },
    "subjectEntryId": "WE-01JD7B1C3E5G7J9L1N3Q5S7U9W",
    "subjectEntryType": "deposit",
    "transactionId": "ST-01JD7A9B1D3F5H7K9M1P3R5T7V",
    "holderStatement": "I loaded $60 but my card was charged $100.",
    "createdAt": "2026-04-10T16:22:05.000Z",
    "updatedAt": "2026-04-11T08:40:51.000Z",
    "messageId": "DM-01JD8E5G7J9L1N3Q5S7U9W1Y3A"
  }
}