Wallet Dispute Opened

wallet-dispute-opened tells you that one of your wallet holders disputes an entry in their wallet: a load they paid for, or one of your charges.

When it fires

Once, when the holder files the dispute. The dispute is open.

What to do

Pick the dispute up with Pick Up Wallet Dispute so the holder sees that someone is on it.
Read the holder's messages with List Wallet Dispute Messages. Ask for more with Request Wallet Dispute Information.
Decide with Accept Wallet Dispute or Decline Wallet Dispute. Each step fires wallet-dispute-status-changed.

Payload

data is the dispute 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
`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-opened",
  "timestamp": "2026-04-10T16:22:06.384Z",
  "data": {
    "disputeId": "DS-01JD7C3E5G7J9L1N3Q5S7U9W1Y",
    "walletId": "W-01JC2R4T6V8X0Z2B4D6F8H0K2M",
    "status": "open",
    "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-10T16:22:05.000Z"
  }
}