Skip to main content
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.
TypeDescription
authorization.clearing.chargebackSent when a dispute is created.
authorization.clearing.chargeback.provisional.creditA provisional credit has been granted to the cardholder.
authorization.clearing.chargeback.provisional.debitA previously issued provisional credit has been reversed.
authorization.clearing.chargeback.completedThe chargeback has been completed successfully. Sent when a case is won without provisional credit.
authorization.clearing.chargeback.reversalThe chargeback has been reversed. Sent when a case is lost or network rejected.
authorization.clearing.chargeback.representmentA representment has been received from the acquiring bank.
pindebit.chargebackA PIN debit chargeback has been initiated.
pindebit.chargeback.provisional.creditA provisional credit has been granted for a PIN debit chargeback.
pindebit.chargeback.reversalA PIN debit chargeback has been reversed.
chargeback.pfs.pending.debitInternal accounting event sent when a Reg E dispute case is created. No program action is required.
chargeback.pfs.debitInternal 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.
TypeDescription
initiatedThe chargeback has been initiated with the card network. The dispute case transitions to the CHARGEBACK_INITIATED state.
representmentThe acquiring bank has submitted a representment challenging the chargeback. The dispute case remains in the CHARGEBACK_INITIATED state.
prearbitrationPre-arbitration received from acquiring bank. The dispute case remains in the CHARGEBACK_INITIATED state.
prearbitration.respondedMarqeta has submitted a response to prearbitration. Specific to fraud and authorization reason codes only.
arbitrationThe dispute has been escalated to the card network for a final decision.
case.wonThe dispute was resolved in the cardholder’s favor. The dispute case transitions to the CLOSED state.
case.lostThe dispute was resolved in the issuer’s favor. The dispute case transitions to the CLOSED state.
network.rejectedThe card network rejected the chargeback submission. The dispute case transitions to the CLOSED state.
withdrawnThe 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).
TypeDescription
regulation.pre.initiatedDispute created.
regulation.initiatedDispute initiated.
regulation.case.wonThe dispute was resolved in the cardholder’s favor. The dispute case transitions to the CLOSED state.
regulation.case.lost.action.requiredThe 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.rejectedThe card network rejected the dispute submission. The dispute case transitions to the CLOSED state.
regulation.written.off.programThe dispute has been written off by the program. The provisional credit is made permanent.
regulation.prearbitrationPre-arbitration received or sent.
regulation.prearbitration.respondedMarqeta has submitted a response to prearbitration.
regulation.arbitrationThe dispute has been escalated to the card network for a final decision.
regulation.withdrawnThe 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.
TypeDescription
regulation.provisional.credit.permanentThe 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).
TypeDescription
openA dispute case has been created and is in the OPEN Marqeta state.
open_with_action_requiredA dispute case has been created and requires merchant action or an ATR response. The case is in the OPEN_WITH_ACTION_REQUIRED Marqeta state.
readyThe dispute case has been reviewed and is ready for submission to the card network. The case is in the READY Marqeta state.
chargeback.initiatedThe dispute has been submitted to the card network. The case transitions to the CHARGEBACK_INITIATED Marqeta state.
pending_closeA regulatory dispute has entered a temporary state before final closure.
closedThe 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).

Related topics

Merchant CollaborationSet Up a Webhook HandlerWebhooksEvent TypesCreate, Submit, and Manage a Dispute