Encoding and whole messages

64 bit integers are strings. Timestamps and deadlines are quoted.
amountInCents is a number, not a string.
Enums are sent as their full name, for example REQUIRED_ACTION_TYPE_ISSUE_PROVISIONAL_CREDIT.
Fields with no value are omitted. Do not expect empty strings, zeros, or empty arrays.

Whole-message examples

Two cases that are about the message as a whole rather than one action type.

Nothing outstanding

No work is outstanding, so the requiredActions key is absent from data. A bare example first:

{
  "type": "dispute.updated",
  "disputeUuid": "3f8e2c1a-9b47-4d6e-a1f0-7c2d5b8e4a91",
  "occurredAt": "2026-08-03T12:00:00Z",
  "data": {
    "dispute": {
      "uuid": "3f8e2c1a-9b47-4d6e-a1f0-7c2d5b8e4a91",
      "resolutionDeadline": "1788393600",
      "status": "DISPUTE_STATUS_OPEN",
      "transactions": [
        {
          "uuid": "txn-1",
          "settledTimestamp": "1783641600",
          "amount": {
            "amountInCents": 4500,
            "currency": "USD"
          },
          "merchant": "Acme Online Store",
          "status": "DISPUTED_TRANSACTION_STATUS_INVESTIGATING",
          "transactionStatus": "TRANSACTION_STATUS_SETTLED"
        }
      ],
      "shortId": "D-1042",
      "reason": "DISPUTE_REASON_MERCHANT_ISSUE",
      "disputeReason": {
        "reason": "DISPUTE_REASON_MERCHANT_ISSUE",
        "displayMessage": "Merchant Issue"
      }
    },
    "statusMessage": "Your dispute is under review.",
    "timeline": [
      {
        "eventType": "TIMELINE_EVENT_TYPE_CREATED",
        "message": "Dispute created",
        "timestamp": "1783728000"
      }
    ]
  }
}

The same thing in a realistic case. The member uploaded a receipt, which is what produced this message. A provisional credit was issued earlier, so nothing is owed, and the dispute is a merchant issue rather than an unauthorised charge, so there is no card to replace. Nothing is required, so the key is absent. Most of the traffic you receive looks like this.

{
  "type": "dispute.updated",
  "disputeUuid": "3f8e2c1a-9b47-4d6e-a1f0-7c2d5b8e4a91",
  "occurredAt": "2026-08-03T12:00:00Z",
  "data": {
    "dispute": {
      "uuid": "3f8e2c1a-9b47-4d6e-a1f0-7c2d5b8e4a91",
      "resolutionDeadline": "1788393600",
      "status": "DISPUTE_STATUS_OPEN",
      "transactions": [
        {
          "uuid": "txn-1",
          "settledTimestamp": "1783641600",
          "amount": {
            "amountInCents": 4500,
            "currency": "USD"
          },
          "merchant": "Acme Online Store",
          "status": "DISPUTED_TRANSACTION_STATUS_INVESTIGATING",
          "auditLog": [
            {
              "timestamp": "1784721600",
              "eventType": "TRANSACTION_EVENT_TYPE_ISSUE_PROVISIONAL_CREDIT",
              "agentEmail": "sam.rivera@example.com",
              "issueProvisionalCredit": {
                "amount": {
                  "amountInCents": 4500,
                  "currency": "USD"
                },
                "actions": [
                  "ACTION_ISSUE_PROVISIONAL_CREDIT"
                ]
              }
            }
          ],
          "transactionStatus": "TRANSACTION_STATUS_SETTLED",
          "provisionalCreditAmount": {
            "amountInCents": 4500,
            "currency": "USD"
          }
        }
      ],
      "shortId": "D-1042",
      "reason": "DISPUTE_REASON_MERCHANT_ISSUE",
      "actions": [
        "ACTION_ISSUE_PROVISIONAL_CREDIT"
      ],
      "files": [
        {
          "fileUuid": "b7e4d2a9-6c1f-4e83-a5d0-9f2c8b1e7a34",
          "filename": "order-confirmation.pdf",
          "contentType": "application/pdf",
          "uploadedAt": "1785250800",
          "size": "184320"
        }
      ],
      "disputeReason": {
        "reason": "DISPUTE_REASON_MERCHANT_ISSUE",
        "displayMessage": "Merchant Issue"
      }
    },
    "statusMessage": "Your dispute is under review.",
    "timeline": [
      {
        "eventType": "TIMELINE_EVENT_TYPE_PROVISIONAL_CREDIT",
        "message": "Provisional credit issued",
        "subMessage": "$45.00",
        "timestamp": "1784721600",
        "transactions": [
          {
            "uuid": "txn-1",
            "merchant": "Acme Online Store",
            "amount": {
              "amountInCents": 4500,
              "currency": "USD"
            },
            "settledTimestamp": "1783641600"
          }
        ]
      },
      {
        "eventType": "TIMELINE_EVENT_TYPE_CREATED",
        "message": "Dispute created",
        "timestamp": "1783728000"
      }
    ]
  }
}

The files array is how an upload shows up. It lists every file on the dispute, not just the new one, and it carries no action of its own.

Several entries at once

Two information requests on one transaction and a credit owed on another. Information requests come first, then credits. This example uses txn-1001 and txn-1002 because it is reproduced verbatim from the payload the service is tested against.

{
  "type": "dispute.updated",
  "disputeUuid": "3f8e2c1a-9b47-4d6e-a1f0-7c2d5b8e4a91",
  "occurredAt": "2026-08-03T12:00:00Z",
  "data": {
    "dispute": {
      "uuid": "3f8e2c1a-9b47-4d6e-a1f0-7c2d5b8e4a91",
      "resolutionDeadline": "1788393600",
      "status": "DISPUTE_STATUS_OPEN",
      "transactions": [
        {
          "uuid": "txn-1001",
          "settledTimestamp": "1783641600",
          "amount": {"amountInCents": 4500, "currency": "USD"},
          "merchant": "Acme Online Store",
          "status": "DISPUTED_TRANSACTION_STATUS_INVESTIGATING",
          "auditLog": [
            {
              "timestamp": "1785412800",
              "eventType": "TRANSACTION_EVENT_TYPE_REQUEST_MORE_INFO",
              "agentEmail": "sam.rivera@example.com"
            },
            {
              "timestamp": "1785416400",
              "eventType": "TRANSACTION_EVENT_TYPE_REQUEST_MORE_INFO",
              "agentEmail": "sam.rivera@example.com"
            }
          ],
          "transactionStatus": "TRANSACTION_STATUS_SETTLED",
          "requiredActions": ["REQUIRED_ACTION_PROVIDE_MORE_INFO"]
        },
        {
          "uuid": "txn-1002",
          "settledTimestamp": "1783641600",
          "amount": {"amountInCents": 8999, "currency": "USD"},
          "merchant": "Northwind Books",
          "status": "DISPUTED_TRANSACTION_STATUS_INVESTIGATING",
          "transactionStatus": "TRANSACTION_STATUS_SETTLED"
        }
      ],
      "shortId": "D-1042",
      "reason": "DISPUTE_REASON_MERCHANT_ISSUE",
      "disputeReason": {"reason": "DISPUTE_REASON_MERCHANT_ISSUE", "displayMessage": "Merchant Issue"}
    },
    "statusMessage": "Your dispute is under review.",
    "timeline": [
      {
        "eventType": "TIMELINE_EVENT_TYPE_INFORMATION_REQUESTED",
        "message": "We requested more information from you",
        "timestamp": "1785416400",
        "transactions": [
          {
            "uuid": "txn-1001",
            "merchant": "Acme Online Store",
            "amount": {"amountInCents": 4500, "currency": "USD"},
            "settledTimestamp": "1783641600"
          }
        ]
      },
      {
        "eventType": "TIMELINE_EVENT_TYPE_INFORMATION_REQUESTED",
        "message": "We requested more information from you",
        "timestamp": "1785412800",
        "transactions": [
          {
            "uuid": "txn-1001",
            "merchant": "Acme Online Store",
            "amount": {"amountInCents": 4500, "currency": "USD"},
            "settledTimestamp": "1783641600"
          }
        ]
      }
    ],
    "requiredActions": [
      {
        "type": "REQUIRED_ACTION_TYPE_COLLECT_CUSTOMER_INFORMATION",
        "collectCustomerInformation": {"transactionUuid": "txn-1001", "requestedItemKey": "PoliceReport", "deadlineTimestamp": "1785974400"}
      },
      {
        "type": "REQUIRED_ACTION_TYPE_COLLECT_CUSTOMER_INFORMATION",
        "collectCustomerInformation": {
          "transactionUuid": "txn-1001",
          "customRequestedItems": ["A screenshot of your order confirmation email", "Your last message to the merchant"],
          "deadlineTimestamp": "1785974400"
        }
      },
      {
        "type": "REQUIRED_ACTION_TYPE_ISSUE_PROVISIONAL_CREDIT",
        "issueProvisionalCredit": {
          "transactionUuid": "txn-1002",
          "amount": {"amountInCents": 8999, "currency": "USD"},
          "deadlineTimestamp": "1785211199"
        }
      }
    ]
  }
}

Notification keys

Delivery and ordering