> ## Documentation Index
> Fetch the complete documentation index at: https://www.marqeta.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Dispute Webhook Events
> Learn about the webhook event types available for monitoring dispute case transitions, chargeback transitions, and regulatory disputes.
As a dispute case progress through its lifecycle, the Marqeta platform sends webhook notifications to your endpoint in real time.
Subscribing to these events eliminates the need to request the API for status updates and allows you to automate your dispute workflows.
For information on configuring a webhook endpoint, see [Webhooks](/core-api/webhooks/).
For an overview of the dispute lifecycle and state definitions, see [About Disputes](/developer-guides/about-disputes/).
Dispute transaction events
Dispute transaction events include activities such as chargeback creation, provisional credit grants, and chargeback reversals.
These activities move the money between the card network, Marqeta, the program, and the cardholder.
Dispute transaction notifications are sent as dispute transaction events occur and contain detailed information about the events.
Each notification contains a `type` field that categorizes the dispute transaction event.
The following table describes each dispute transaction event type.
| Type | Description |
| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| `authorization.clearing.chargeback` | Sent when a dispute is created. |
| `authorization.clearing.chargeback.provisional.credit` | A provisional credit has been granted to the cardholder. |
| `authorization.clearing.chargeback.provisional.debit` | A previously issued provisional credit has been reversed. |
| `authorization.clearing.chargeback.completed` | The chargeback has been completed successfully. Sent when a case is won without provisional credit. |
| `authorization.clearing.chargeback.reversal` | The chargeback has been reversed. Sent when a case is lost or network rejected. |
| `authorization.clearing.chargeback.representment` | A representment has been received from the acquiring bank. |
| `pindebit.chargeback` | A PIN debit chargeback has been initiated. |
| `pindebit.chargeback.provisional.credit` | A provisional credit has been granted for a PIN debit chargeback. |
| `pindebit.chargeback.reversal` | A PIN debit chargeback has been reversed. |
| `chargeback.pfs.pending.debit` | Internal accounting event sent when a Reg E dispute case is created. No program action is required. |
| `chargeback.pfs.debit` | Internal accounting event sent when provisional credit is granted on a Reg E dispute. No program action is required. |
Dispute transaction notifications are structured as an array within a `transactions` element.
Multiple notifications can be included in a single notification message.
The following example shows an `authorization.clearing.chargeback` notification, sent when a dispute is created.
```json JSON expandable lines wrap theme={null}
{
"transactions": [
{
"type": "authorization.clearing.chargeback",
"state": "COMPLETION",
"token": "my_transaction_token_01",
"user_token": "my_user_token_01",
"acting_user_token": "my_user_token_01",
"card_token": "my_card_token_01",
"card_product_token": "my_card_product_token_01",
"preceding_related_transaction_token": "my_transaction_token_00",
"gpa": {
"currency_code": "USD",
"ledger_balance": 0.00,
"available_balance": 0.00,
"credit_balance": 0.00,
"pending_credits": 123.48,
"impacted_amount": 123.48
},
"created_time": "2024-06-17T12:29:18Z",
"user_transaction_time": "2024-06-17T12:29:18Z",
"request_amount": 123.48,
"amount": 123.48,
"currency_code": "USD",
"response": {
"code": "0000",
"memo": "Approved or completed successfully"
},
"chargeback": {
"token": "my_chargeback_token_01",
"transaction_token": "my_transaction_token_00",
"amount": 123.48,
"reason_code": "10.4",
"state": "PRE_INITIATED",
"channel": "ISSUER_AUTOMATED",
"network": "VISA",
"credit_user": false
},
"network": "VISA",
"card_acceptor": {
"mid": "my_merchant_id",
"mcc": "5411",
"name": "My Merchant",
"country_code": "USA"
}
}
]
}
```
For more information, see [Disputes (Visa)](/core-api/disputes-visa/).
Dispute transition events
Dispute transition events mark the progress of a chargeback through the network states.
These activities cause the transition of a dispute's `state` field.
Dispute transition notifications are sent as chargeback state transitions occur and contain detailed information about the events.
Each notification contains a `type` field that categorizes the dispute transition event.
The following table describes each dispute transition event type.
The values in the Type column are the literal values of the notification's `type` field.
When [configuring a webhook](/core-api/webhooks/) to capture these events, you must prefix this type with `chargebacktransitions.`.
For example, `chargebacktransitions.initiated`.
| Type | Description |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `initiated` | The chargeback has been initiated with the card network. The dispute case transitions to the `CHARGEBACK_INITIATED` state. |
| `representment` | The acquiring bank has submitted a representment challenging the chargeback. The dispute case remains in the `CHARGEBACK_INITIATED` state. |
| `prearbitration` | Pre-arbitration received from acquiring bank. The dispute case remains in the `CHARGEBACK_INITIATED` state. |
| `prearbitration.responded` | Marqeta has submitted a response to prearbitration. Specific to fraud and authorization reason codes only. |
| `arbitration` | The dispute has been escalated to the card network for a final decision. |
| `case.won` | The dispute was resolved in the cardholder's favor. The dispute case transitions to the `CLOSED` state. |
| `case.lost` | The dispute was resolved in the issuer's favor. The dispute case transitions to the `CLOSED` state. |
| `network.rejected` | The card network rejected the chargeback submission. The dispute case transitions to the `CLOSED` state. |
| `withdrawn` | The chargeback was withdrawn. |
Dispute transition notifications are structured as an array within a `chargebacktransitions` element.
Multiple notifications can be included in a single notification message.
The following example shows a `prearbitration` notification, sent when Marqeta resubmits the dispute to the acquiring bank after receiving a representment.
```json JSON expandable lines wrap theme={null}
{
"chargebacktransitions": [
{
"token": "my_chargeback_transition_token_01",
"state": "PREARBITRATION",
"previous_state": "INITIATED",
"channel": "ISSUER_AUTOMATED",
"chargeback_token": "my_chargeback_token_01",
"reason": "PREARB_RECEIVED",
"transaction_token": "my_transaction_token_01",
"created_time": "2024-06-17T16:54:47Z",
"last_modified_time": "2024-06-17T16:54:47Z",
"type": "prearbitration"
}
]
}
```
For more information, see [Disputes (Visa)](/core-api/disputes-visa/).
Regulatory dispute transition events
Regulatory dispute transition events include activities specific to Regulation E, Payment Services Directive (PSD2), and Regulation Z disputes, such as dispute initiation, case resolution, and pre-arbitration.
These activities cause the transition of a regulatory chargeback's `state` field.
Regulatory dispute transition notifications are sent as regulatory chargeback state transitions occur and contain detailed information about the events.
Each notification contains a `type` field that categorizes the regulatory dispute transition event.
The following table describes each regulatory dispute transition event type.
The values in the Type column are the literal values of the notification's `type` field.
When [configuring a webhook](/core-api/webhooks/) to capture these events, you must prefix this type with `chargebacktransitions` (for example, `chargebacktransitions.regulation.initiated`).
| Type | Description |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `regulation.pre.initiated` | Dispute created. |
| `regulation.initiated` | Dispute initiated. |
| `regulation.case.won` | The dispute was resolved in the cardholder's favor. The dispute case transitions to the `CLOSED` state. |
| `regulation.case.lost.action.required` | The dispute was resolved in the issuer's favor. You must notify the cardholder before the provisional credit is reversed. The dispute case transitions to the `CLOSED` state. |
| `regulation.network.rejected` | The card network rejected the dispute submission. The dispute case transitions to the `CLOSED` state. |
| `regulation.written.off.program` | The dispute has been written off by the program. The provisional credit is made permanent. |
| `regulation.prearbitration` | Pre-arbitration received or sent. |
| `regulation.prearbitration.responded` | Marqeta has submitted a response to prearbitration. |
| `regulation.arbitration` | The dispute has been escalated to the card network for a final decision. |
| `regulation.withdrawn` | The chargeback was withdrawn. |
Regulatory dispute transition notifications are structured as an array within a `chargebacktransitions` element.
Multiple notifications can be included in a single notification message.
The following example shows a `regulation.case.won` notification, sent when a regulatory dispute is resolved in the cardholder's favor.
```json JSON expandable lines wrap theme={null}
{
"chargebacktransitions": [
{
"token": "my_chargeback_transition_token_02",
"state": "CASE_WON",
"previous_state": "PREARB_RESPONDED",
"channel": "ISSUER_AUTOMATED",
"chargeback_token": "my_chargeback_token_02",
"created_time": "2024-06-17T16:59:32Z",
"last_modified_time": "2024-06-17T16:59:32Z",
"type": "regulation.case.won"
}
]
}
```
For more information, see [Disputes (Visa)](/core-api/disputes-visa/).
Dispute case events
Dispute case events include activities that do not cause money movement or a chargeback state change, such as a provisional credit becoming permanent for regulatory disputes.
Dispute case event notifications are sent as dispute case events occur and contain detailed information about the events.
Each notification contains a `type` field that categorizes the dispute case event.
The following table describes the dispute case event type.
The values in the Type column are the literal values of the notification's `type` field.
| Type | Description |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `regulation.provisional.credit.permanent` | The provisional credit has been made permanent, either because the dispute case was won or because the 45-day regulatory clock has expired. Applies to regulatory disputes only. |
The following example shows a `regulation.provisional.credit.permanent` notification.
```json JSON expandable lines wrap theme={null}
{
"token": "my_chargeback_transition_token_03",
"type": "regulation.provisional.credit.permanent",
"name": "ProvisionalCreditPerm",
"category": "REG_E",
"event_date": "2024-06-17T09:25:10Z",
"created_by": "Automated By System",
"created_time": "2024-06-17T09:25:10Z",
"case": {
"token": "my_case_token_01",
"type": "DISPUTE",
"user_token": "my_user_token_01",
"state": "CHARGEBACK_INITIATED",
"dispute_summary": {
"original_transaction_token": "my_transaction_token_01",
"original_transaction_type": "authorization.clearing",
"dispute_amount": 34.99,
"currency_code": "USD",
"dispute_reason": "NOT_AUTHORIZED_CARD_ABSENT",
"dispute_state": "CASE_WON",
"chargeback_token": "my_chargeback_token_01",
"network": "VISA",
"card_token": "my_card_token_01",
"provisional_credit_granted": true,
"regulation_type": "REG_E"
}
}
}
```
For more information, see [Disputes (Visa)](/core-api/disputes-visa/).
Dispute case transition events
Dispute case transition events notify you when a dispute case moves from one Marqeta case state to another.
Unlike dispute transition events, which track chargeback-level network state changes, case transition events track the higher-level case lifecycle, starting from creation through closure.
For a full description of dispute case states and how they relate to network dispute states, see [About Disputes](/developer-guides/about-disputes/#_states_and_transitions).
Each notification contains a `type` field that categorizes the case transition event.
The following table describes each dispute case transition event type.
The values in the Type column are the literal values of the notification's `type` field.
When [configuring a webhook](/core-api/webhooks/) to capture these events, you must prefix this type with `casetransition` (for example, `casetransition.open`).
| Type | Description |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `open` | A dispute case has been created and is in the `OPEN` Marqeta state. |
| `open_with_action_required` | A dispute case has been created and requires merchant action or an ATR response. The case is in the `OPEN_WITH_ACTION_REQUIRED` Marqeta state. |
| `ready` | The dispute case has been reviewed and is ready for submission to the card network. The case is in the `READY` Marqeta state. |
| `chargeback.initiated` | The dispute has been submitted to the card network. The case transitions to the `CHARGEBACK_INITIATED` Marqeta state. |
| `pending_close` | A regulatory dispute has entered a temporary state before final closure. |
| `closed` | The dispute case has been closed and transitions to the `CLOSED` Marqeta state. |
Dispute case transition notifications are structured as an array within a `casetransitions` element.
Multiple notifications can be included in a single notification message.
The following example shows a `closed` notification, sent when a non-regulated dispute is withdrawn and closed.
```json JSON expandable lines wrap theme={null}
{
"casetransitions": [
{
"type": "closed",
"action": "WITHDRAW_AND_CLOSE",
"token": "47abcf12-aa2b-407d-bf98-907465e51abb",
"memo": "Program requested a writeoff",
"assignee": "mqd-testing admin1",
"case_token": "deqa-69171",
"previous_state": "OPEN_WITH_ACTION_REQUIRED",
"current_state": "CLOSED",
"created_by": "kmu@marqeta.com",
"created_time": "2026-01-30 20:26:43+0000"
}
]
}
```
The `memo` field is optional and appears only when an agent enters a memo during the action.
For more information, see [Disputes (Visa)](/core-api/disputes-visa/).
## Related topics
- [Merchant Collaboration](/docs/developer-guides/disputes-merchant-collaboration.md)
- [Set Up a Webhook Handler](/docs/developer-guides/disputes-sandbox/disputes-webhook-handler.md)
- [Webhooks](/docs/core-api/webhooks.md)
- [Event Types](/docs/core-api/event-types.md)
- [Create, Submit, and Manage a Dispute](/docs/developer-guides/disputes-sandbox/disputes-sandbox-submit-manage.md)