Dispute Webhook Events

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. For an overview of the dispute lifecycle and state definitions, see 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

{
  "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).

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 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

{
  "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).

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 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

{
  "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).

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

{
  "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).

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. 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 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

{
  "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).

​Dispute transaction events

​Dispute transition events

​Regulatory dispute transition events

​Dispute case events

​Dispute case transition events

Dispute transaction events

Dispute transition events

Regulatory dispute transition events

Dispute case events

Dispute case transition events