Reading requiredActions

data.requiredActions is the only list you need to act on.

Four rules govern it.

It is a snapshot, not a change log. Each message contains the complete set of outstanding items as of that moment. An entry that was present in an earlier message and is absent from a later one has been satisfied. Do not accumulate entries across messages.

An empty list is omitted. When nothing is outstanding, the requiredActions key is not present in data at all. It is never sent as []. Treat a missing key as an empty list.

Most messages are like this. The event fires on every change to the dispute, and most changes are informational. Common cases where the key is absent:

• A file was uploaded, by the member or by an agent.
• A comment or an internal field changed.
• A provisional credit was already issued and nothing else is owed.
• The dispute is closed and everything owed has been settled.
• The work sits with Casap, for example a chargeback is in flight with the card network.
• The work sits with the member. An information request that is still waiting on their answer keeps its collect entry, so if no entry is present the request has already been satisfied.

See Encoding and whole messages for a worked example of an update with nothing to do.

Notifications are the exception, and they are sent once. Every entry described above is a snapshot: it stays in the list until the work is done. A notifyCustomer entry is not. It is raised in the single message that records the event it announces, and it is gone from the next one whether or not you acted. Treat these as events to process on arrival, not as outstanding work to reconcile. If you drop that message, the notification is not repeated. Store it before you acknowledge the delivery.

Ignore the other action fields. Two older fields appear in the same payload and do not mean the same thing:

• data.dispute.actions is cumulative across the life of the dispute and is de-duplicated. Once a value appears it stays forever. It records that something happened at some point, not that it needs doing now.
• data.dispute.transactions[].requiredActions is a per transaction list that the root level list replaces.

Acting on either of these will cause repeated actions. Read data.requiredActions only.

Action types

• REQUIRED_ACTION_TYPE_COLLECT_CUSTOMER_INFORMATION — read collectCustomerInformation. Collect documents or information from the member.
• REQUIRED_ACTION_TYPE_ISSUE_PROVISIONAL_CREDIT — read issueProvisionalCredit. Issue a provisional credit to the member.
• REQUIRED_ACTION_TYPE_ISSUE_FINAL_CREDIT — read issueFinalCredit. Issue the final credit once the dispute is decided in the member's favour.
• REQUIRED_ACTION_TYPE_REVERSE_PROVISIONAL_CREDIT — read reverseProvisionalCredit. Take back a provisional credit after a decision that did not go the member's way.
• REQUIRED_ACTION_TYPE_REPLACE_CARD — read replaceCard. Replace the member's card.
• REQUIRED_ACTION_TYPE_NOTIFY_CUSTOMER — read notifyCustomer. Tell the member about a dispute event, in your own wording.

Each entry has a type and one details object named after that type. Read the type first, then the matching field.

Entries are ordered: information requests, then provisional credits, then settlements (final credits and reversals), then the card, then notifications. Within each group they follow transaction order.

Fee transactions never produce an entry of any kind. A fee that forms part of a dispute appears in data.dispute but is never something you are asked to credit, reverse, or reissue a card for.