# Card Disputes [API Documentation](/api/card-dispute/card-dispute-object) When a cardholder disagrees with a settled card transaction, for example because they didn't authorize it, never received what they paid for, or were charged the wrong amount, your platform can raise a card dispute on their behalf. Column files the dispute with the card network, tracks the merchant's responses, and keeps the dispute object in sync with the network so your platform can respond at each stage and see the final outcome. Card disputes are currently supported for Visa and Interlink card programs only. Disputes on other networks are rejected. Column maps each dispute to the card network's own dispute rules, so your platform works with one set of reasons, stages, and actions. Dispute simulation is not yet available in Sandbox. ## Dispute Lifecycle A dispute moves through the following steps: 1. [Check eligibility](#eligibility) for the transaction, amount, and reason. 2. [Create the dispute](#creating-a-dispute), optionally issuing the cardholder a [provisional credit](#provisional-credit). 3. [Add evidence](#evidence) until the dispute has everything its reason requires. 4. [Submit the dispute](#submitting-a-dispute) to the card network. 5. [Respond](#responding-to-the-network) when the merchant or acquirer contests the dispute. 6. The dispute is [resolved](#resolution) in the cardholder's or the merchant's favor. Each dispute carries `next_actions` and `respond_by` fields describing what is needed next and when, so your platform can drive the dispute from the object itself rather than tracking the network rules on its own. ## Dispute Object The [card dispute object](/api/card-dispute/card-dispute-object) holds the claim, its current state, and what your platform can do next. Amounts are in the smallest unit of the dispute's `currency`. | Field ::min | Description | | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | The ID of the card dispute. | | `card_transaction_id` | The disputed card transaction. | | `card_account_id` | The card account the transaction belongs to. | | `card_program_id` | The card program the transaction belongs to. | | `platform_id` | Your platform's ID. | | `amount` | The disputed amount. Can be less than the transaction amount for a partial dispute. | | `currency` | The cardholder billing currency of the transaction. | | `reason` | The cardholder's claim. See [Dispute Reasons](#dispute-reasons). | | `reason_details` | Reason-specific details, keyed by the reason. | | `reason_for_partial_dispute` | Why the cardholder is disputing less than the full amount. | | `workflow` | How the dispute progresses through the card network, based on its reason. See [Workflows](#workflows). | | `status` | A summary of where the dispute stands. See [Statuses](#statuses). | | `stage` | Where the dispute is in the network process. See [Stages](#stages). | | `submission_status` | Whether the dispute, or its latest response, has been sent to the network. See [Submitting a Dispute](#submitting-a-dispute). | | `submission_error` | The most recent network submission error. Set only when `submission_status` is `failed`. | | `resolution_reason` | Why the dispute was resolved. See [Resolution](#resolution). | | `requested_resolution` | The resolution of a close that is waiting on the network to confirm the recall. See [Closing a Dispute](#closing-a-dispute). | | `provisional_credit` | Whether a provisional credit has been issued. Outside of drafts this records that a credit was issued, not that it's still outstanding. See [Provisional Credit](#provisional-credit). | | `next_actions` | What is needed next to move the dispute forward. See [Next Actions](#next-actions). | | `respond_by` | The date the next network action is due. | | `allowed_response_actions` | The actions currently accepted by [respond to card dispute](/api/card-dispute/respond-to-card-dispute). Empty when no response is possible. | | `allowed_close_resolutions` | The resolutions currently accepted by [close card dispute](/api/card-dispute/close-card-dispute). Empty when the dispute can't be closed. | | `compelling_evidence_certification_required` | Whether a response must include the compelling evidence certifications. See [Responding to the Network](#responding-to-the-network). | | `events` | Each stage change and response on the dispute, with any narrative, evidence document, response action, and accepted amount recorded with it. | | `evidence` | The narratives and documents on the dispute. `direction` is `outbound` for evidence your platform supplied and `inbound` for evidence received from the network, and `submitted_at` shows when it was sent to the network. | | `submitted_at` | When the dispute was submitted to the network. Empty for disputes that have never been sent. | | `last_network_sync_at` | When Column last synchronized the dispute with the network. | | `created_at` | When the dispute was created. | | `updated_at` | When the dispute was last updated. | ## Dispute Reasons The `reason` describes the cardholder's claim. Column maps it to the matching dispute condition on the card network, and it determines the [workflow](#workflows) the dispute follows. | Reason ::min | Description | | ------------------------------------ | ----------------------------------------------------------------------------------------------------- | | `fraud` | The cardholder did not authorize or participate in the transaction. | | `no_authorization` | The transaction was processed without a required authorization. | | `incorrect_transaction_code` | The transaction was processed with the wrong transaction code, such as a credit processed as a debit. | | `incorrect_currency` | The transaction was processed in a different currency than agreed. | | `incorrect_account_number` | The transaction was processed to an incorrect card number. | | `incorrect_amount` | The amount charged differs from the amount on the cardholder's receipt. | | `duplicate_processing` | The same transaction was processed more than once. | | `paid_by_other_means` | The cardholder paid for the same purchase by another method. | | `invalid_data` | The authorization was obtained with invalid data. | | `merchandise_services_not_received` | The cardholder did not receive the merchandise or services. | | `canceled_recurring_transaction` | The merchant charged a recurring transaction after it was canceled. | | `not_as_described` | The merchandise or services did not match their description. | | `damaged_or_defective_merchandise` | The merchandise arrived damaged or defective. | | `quality_of_merchandise_or_services` | The quality of the merchandise or services was unacceptable. | | `terms_of_contract` | The merchant did not follow the terms of the contract (commercial virtual card transactions). | | `counterfeit_merchandise` | The merchandise was counterfeit. | | `misrepresentation` | The merchant misrepresented the terms of the sale. | | `credit_not_processed` | The merchant did not process a promised refund or credit. | | `canceled_merchandise_or_services` | The cardholder canceled or returned the merchandise or services and was not credited. | | `original_credit_not_accepted` | The cardholder did not accept an original credit pushed to the card. | | `non_receipt_cash_at_atm` | The cardholder did not receive some or all of the cash from an ATM withdrawal. | | `other` | Tracked by Column but not filed with the card network. | A fraud dispute certifies that the cardholder denies authorizing or participating in the transaction. If the cardholder was the victim of a scam, file it under a consumer reason such as `misrepresentation` or `not_as_described` instead. ### Requirements by Reason Each reason determines what the dispute needs before it can be submitted: - **Required Details** are the fields every dispute with the reason must include in `reason_details`, under a key matching the reason (for example, `reason_details.fraud.fraud_type`). Many reasons have further fields that become required based on these answers, such as return details when the cardholder returned the merchandise. See [create card dispute](/api/card-dispute/create-card-dispute) for every field and when it's required. - **Narrative** means the dispute needs the cardholder's account of what happened, as `cardholder_narrative` or as narrative [evidence](#evidence). - **Document** means the dispute needs an uploaded [evidence](#evidence) document. For repeat claims, a `cardholder_letter` is required once the card already has two submitted disputes with the same reason against the same merchant within 30 days. A dispute missing any of these has `add_evidence` in its `next_actions` and can't be submitted. Disputes for less than the full transaction amount also need a `reason_for_partial_dispute`, except for `incorrect_amount`. Amounts in `reason_details`, such as `cardholder_receipt_amount`, are in the smallest unit of the dispute's `currency`, which is the cardholder billing currency of the transaction, including for transactions made in a foreign currency. For reasons with `cardholder_attempted_resolution`, the cardholder must have tried to resolve the issue with the merchant first. When `cardholder_attempted_resolution` is `false`, `resolution_prohibited_by_local_law` must be `true`, or the dispute is rejected. ### When Requirements Are Checked | Request ::min | Requirements Checked | | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Check eligibility](/api/card-dispute/check-card-dispute-eligibility) | All requirements, including the filing window and the repeat-claim cardholder letter. | | [Create](/api/card-dispute/create-card-dispute) without `submit` | Eligibility of the transaction, amount, and filing window. Missing details, narrative, and documents are allowed, so evidence can be added to the draft later. | | [Create](/api/card-dispute/create-card-dispute) with `submit` set to `true` | All requirements. | | [Submit](/api/card-dispute/submit-card-dispute) | Details, narrative, documents, partial dispute explanation, and amount. | | Network submission | The same checks again, right before Column sends the dispute. A dispute that no longer meets them moves to `requires_action`. | The filing window is checked when the dispute is created, not when it's submitted. Submit drafts promptly: the network applies its own filing window when it receives the dispute. | Reason ::min | Required Details | Narrative | Document | | ------------------------------------ | ------------------------------------------------------------------------------------------------------ | --------- | ------------------------------------- | | `fraud` | `fraud_type` | — | — | | `no_authorization` | `account_status` | — | — | | `incorrect_transaction_code` | `transaction_code_error` | — | — | | `incorrect_currency` | `currency_error` | — | — | | `incorrect_account_number` | `receipt_account_number_matches` | — | — | | `incorrect_amount` | `cardholder_receipt_amount` | — | Yes | | `duplicate_processing` | `other_transaction_on_same_card` | — | If the proof of payment is a document | | `paid_by_other_means` | `other_transaction_on_same_card`, `cardholder_attempted_resolution` | — | If the proof of payment is a document | | `invalid_data` | `authorization_decline_explanation` | — | — | | `merchandise_services_not_received` | `merchandise_or_services`, `order_details`, `expected_receipt_date`, `cardholder_attempted_resolution` | Yes | For repeat claims | | `canceled_recurring_transaction` | `cancellation_date` or `account_closure_date` | Yes | — | | `not_as_described` | `merchandise_or_services`, `order_details`, `received_date`, `cardholder_attempted_resolution` | Yes | — | | `damaged_or_defective_merchandise` | `order_details`, `received_date`, `cardholder_returned_merchandise`, `cardholder_attempted_resolution` | Yes | — | | `quality_of_merchandise_or_services` | `merchandise_or_services`, `order_details`, `received_date`, `cardholder_attempted_resolution` | Yes | — | | `terms_of_contract` | `terms_not_honored_details` | Yes | — | | `counterfeit_merchandise` | `order_details`, `counterfeit_details`, `counterfeit_discovered_date`, `merchandise_disposition` | Yes | Yes | | `misrepresentation` | `merchandise_or_services`, `order_details`, `received_date`, `misrepresentation_details` | Yes | — | | `credit_not_processed` | `credit_voucher_date`, or `canceled_or_returned_date` for an undated voucher | Yes | Yes | | `canceled_merchandise_or_services` | `merchandise_or_services`, `cardholder_attempted_resolution` | Yes | — | | `original_credit_not_accepted` | `not_accepted_reason`, `explanation` | Yes | — | | `non_receipt_cash_at_atm` | — | Yes | For repeat claims | | `other` | — | Yes | — | ### Workflows The `workflow` field shows how the dispute progresses through the card network, based on its reason. | Workflow ::min | Reasons | Description | | --------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `allocation` | `fraud`, `no_authorization` | Fraud-related claims. The merchant's bank (the acquirer) answers the claim directly, either accepting it or opening pre-arbitration. | | `collaboration` | All other reasons | Your platform and the acquirer negotiate through the merchant's response, pre-arbitration, and arbitration. | ## Eligibility Use [check card dispute eligibility](/api/card-dispute/check-card-dispute-eligibility) with the same body you would send to create a dispute to see whether the dispute would be accepted, without creating it. The response includes `eligible`, the `max_amount` that can currently be disputed, any `existing_card_dispute_id` for the transaction, and the `reasons` the dispute is not eligible. | Reason ::min | Description | | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `transaction_not_found` | The card transaction does not exist. | | `transaction_not_settled` | The transaction has not settled. Only settled transactions can be disputed. | | `currency_mismatch` | The dispute currency is not the cardholder billing currency of the transaction. | | `amount_exceeds_settled_amount` | The dispute amount is more than the transaction's settled amount. | | `amount_exceeds_receipt_difference` | For `incorrect_amount`, the dispute amount is more than the difference between the charged and receipt amounts. | | `amount_not_partial` | The reason only allows disputing part of the transaction amount. Applies to `incorrect_amount` and `incorrect_transaction_code`. | | `active_dispute_exists` | The transaction already has an open dispute. | | `exceeded_filing_window` | The network filing window for the reason has passed. | | `missing_required_evidence` | Required details, documents, or a reason for a partial dispute are missing. | | `reason_not_applicable_to_transaction` | The reason cannot be used for this type of transaction. | A transaction can only have one open dispute at a time. ### Filing Windows Card networks limit how long after a transaction a dispute can be filed, and the window depends on the dispute reason. Windows are counted from the date the card transaction was created, and eligibility reports `exceeded_filing_window` once the window has passed. | Reasons ::min | Filing Window | | ---------------------------------------------------------------------------------- | ------------- | | `no_authorization`, `incorrect_account_number`, `incorrect_amount`, `invalid_data` | 75 days | | All other reasons | 120 days | Windows close at 09:00 UTC on the last day. ## Creating a Dispute [Create a dispute](/api/card-dispute/create-card-dispute) with `POST /issuing/card-disputes`. The `amount` is in the smallest unit of the cardholder billing `currency`, and can be less than the transaction amount for a partial dispute. ```bash curl https://api.column.com/issuing/card-disputes \ -XPOST \ -H 'Content-Type: application/json' \ -u : \ --data '{ "card_transaction_id": "", "amount": 5000, "currency": "USD", "reason": "fraud", "reason_details": { "fraud": { "fraud_type": "card_absent" } }, "cardholder_narrative": "I did not make this purchase and my card has not left my possession.", "issue_provisional_credit": true }' ``` By default the dispute is created as a draft (`submission_status` of `draft`), so your platform can add evidence before it's sent to the network. Set `submit` to `true` to queue it for network submission immediately. When disputing less than the full transaction amount, include `reason_for_partial_dispute` explaining why. It's required at submission, except for `incorrect_amount` disputes, which are partial by nature. ## Evidence Evidence supports the cardholder's claim and is sent to the network with the dispute or with a later response. It can be a narrative, an uploaded document, or both. To attach a document, first [upload it](/api/card-dispute/upload-card-dispute-document) with `POST /issuing/card-disputes/documents` as a `multipart/form-data` request. Only documents uploaded through this endpoint are accepted as dispute evidence; documents uploaded through `POST /documents` are rejected. ```bash curl https://api.column.com/issuing/card-disputes/documents \ -XPOST \ -u : \ -F file=@receipt.pdf \ -F description='Cardholder receipt' ``` Then [add it to the dispute](/api/card-dispute/add-card-dispute-evidence) with an `evidence_type`. The same endpoint also accepts a `narrative`, missing `reason_details`, or a `reason_for_partial_dispute`. ```bash curl https://api.column.com/issuing/card-disputes//evidence \ -XPOST \ -H 'Content-Type: application/json' \ -u : \ --data '{ "document_id": "", "evidence_type": "transaction_receipt" }' ``` See [Dispute Reasons](#dispute-reasons) for the reasons that require an uploaded document. Evidence received from the network, such as documents the merchant provides, appears in the dispute's `evidence` with a `direction` of `inbound`. Retrieve it with [get card dispute document](/api/card-dispute/get-card-dispute-document). ## Submitting a Dispute When `next_actions` contains `submit`, the dispute has everything it needs. [Submit it](/api/card-dispute/submit-card-dispute) with `POST /issuing/card-disputes//submit`. Submission is asynchronous: the dispute moves to `pending_submission` and Column sends it to the network, usually within a few minutes. Responses and recalls are sent the same way. If sending fails with a temporary error, Column records it in `submission_error` and retries while the dispute stays in `pending_submission`. If the network rejects the submission, the dispute moves to `failed` with the reason in `submission_error`. This applies to responses as well as the original submission. | Submission Status ::min | Description | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `draft` | The dispute has not been queued for submission. | | `pending_submission` | The dispute, or a response to it, is queued to be sent to the network. | | `submitted` | The network has received the dispute and Column is waiting on the merchant or acquirer. | | `requires_action` | The network is waiting on a response from your platform. | | `failed` | The network rejected the last submission. See `submission_error` for details. | | `not_required` | Nothing further needs to be sent to the network. Set when the dispute is closed, whether by your platform, by a response your platform sent, or by the network. | A `failed` dispute can be corrected with additional evidence and submitted again. A failed response can be sent again with [respond to card dispute](/api/card-dispute/respond-to-card-dispute). ## Provisional Credit Your platform can credit the cardholder the dispute amount while the dispute is investigated. Set `issue_provisional_credit` to `true` when creating the dispute, or issue the credit later while the dispute is still a draft with [issue card dispute provisional credit](/api/card-dispute/issue-card-dispute-provisional-credit). A draft's credit can be removed with [remove card dispute provisional credit](/api/card-dispute/remove-card-dispute-provisional-credit). The credit is always the full dispute amount, and removing it reverses the full amount. Once a dispute is submitted, the credit can no longer be issued or removed through these endpoints. The credit is funded from the card program's operating account, and the request fails if the operating account has insufficient funds. Provisional credit is not supported for `original_credit_not_accepted` disputes, which return funds the cardholder already received. ### How Credits Are Recorded A provisional credit is not a transfer. It is recorded on the disputed card transaction as a [`dispute_credit` event](/card-issuing/card-transactions#disputes), which moves funds from the operating account to the cardholder's account and fires `issuing.card_transaction.updated`. A reversal is recorded on the same transaction as a `dispute_credit_reversal` event, which moves the funds back. Both appear in the card transaction's events and totals, so they can be shown to the cardholder alongside the original purchase. The dispute's `provisional_credit` is `true` once a credit is issued. Removing a draft's credit sets it back to `false`. After a dispute is submitted, `provisional_credit` stays `true` even if the credit is later reversed, so check the card transaction's events for the current balance of credits and reversals. ### Reversals Column reverses an outstanding provisional credit automatically when a dispute is resolved against the cardholder. | Outcome ::min | Credit | | -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | Your platform removes the credit from a draft | Reversed in full. | | Closed with `cardholder_withdrew`, as a draft or after submission | Reversed in full. | | Resolved in the merchant's favor, for example when your platform accepts the merchant's response or the network rules for the merchant | Reversed in full. | | Your platform partially accepts a pre-arbitration with `accept_partial` | The accepted `amount` is reversed. The rest stays with the cardholder. | | Closed with `accept_cardholder_claim` | Kept, and final, even if the network later closes the dispute. | | Resolved in the cardholder's favor (`dispute_won`) | Kept. | For debit card programs, the cardholder's bank account must hold the funds for the reversal. ## Responding to the Network When the merchant or acquirer contests a dispute, its `submission_status` becomes `requires_action`, `next_actions` shows what is needed, and `respond_by` shows the date your response is due. The `allowed_response_actions` field lists the actions currently accepted by [respond to card dispute](/api/card-dispute/respond-to-card-dispute). | Action ::min | Description | | ---------------- | ----------------------------------------------------------------------------------------------- | | `accept` | Accept the merchant's or acquirer's position. The dispute is resolved in the merchant's favor. | | `accept_partial` | Accept liability for part of the amount, set in `amount`. Available for fraud pre-arbitrations. | | `decline` | Decline a fraud pre-arbitration and continue the dispute. | | `escalate` | Continue a non-fraud dispute to pre-arbitration or arbitration. | A `narrative` explaining your position is required for `accept_partial`, `decline`, and `escalate`, and optional for `accept`. Accepting resolves the dispute in the merchant's favor and reverses any outstanding [provisional credit](#reversals) in full, or the accepted `amount` for `accept_partial`. `next_actions` and `allowed_response_actions` are derived from the same state, so when `next_actions` asks for a response, `allowed_response_actions` lists the actions that can be taken. If the acquirer's pre-arbitration offers a qualified remedy, the card network does not allow it to be declined, and `decline` is left out of `allowed_response_actions`. ```bash curl https://api.column.com/issuing/card-disputes//respond \ -XPOST \ -H 'Content-Type: application/json' \ -u : \ --data '{ "action": "escalate", "narrative": "The tracking number provided by the merchant shows delivery to a different address than the cardholder provided.", "evidence": [ { "document_id": "", "evidence_type": "updated_cardholder_letter" } ] }' ``` When an acquirer presents compelling evidence in a fraud pre-arbitration, `compelling_evidence_certification_required` is `true`. To decline or partially accept it, include `compelling_evidence_reviewed_with_cardholder` and `cardholder_name_and_address_mismatch` to certify that you reviewed the evidence with the cardholder and whether the name and address the acquirer presented match your records. ### Next Actions | Next Action ::min | Description | | ------------------------------ | -------------------------------------------------------------------------------------- | | `add_evidence` | The dispute is missing required details, documents, or a reason for a partial dispute. | | `submit` | The dispute is ready to be submitted to the network. | | `await_network_submission` | The dispute or response is queued to be sent to the network. | | `await_network_response` | Column is waiting on the merchant, acquirer, or network. | | `respond_to_merchant_response` | The merchant responded to a non-fraud dispute. Accept or escalate. | | `respond_to_prearbitration` | A pre-arbitration needs a response from your platform. | | `resolve_required_action` | The dispute needs attention, for example after a failed submission. | | `await_manual_arbitration` | The dispute is in arbitration and the network is reviewing it. | ## Closing a Dispute Your platform can [close a dispute](/api/card-dispute/close-card-dispute) with one of the following resolutions. The `allowed_close_resolutions` field lists the resolutions currently accepted. | Resolution ::min | Description | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `accept_cardholder_claim` | Your platform accepts the cardholder's claim and assumes liability. Use it when your platform resolves the dispute in the cardholder's favor without the card network, for example after its own investigation. The cardholder is credited the dispute amount if they haven't already received a provisional credit, and the credit is final. | | `cardholder_withdrew` | The cardholder withdrew the claim. Any provisional credit is reversed. | `accept_cardholder_claim` is not available for `original_credit_not_accepted` disputes. ### When a Dispute Can Be Closed A dispute can be closed: - **Before it's submitted** (`initiated` stage). The close takes effect immediately. - **After it's submitted, while it's at the `disputed` stage.** Column recalls the dispute from the network first. The dispute moves to `pending_submission`, `requested_resolution` records the resolution, and the dispute is closed once the network confirms the recall. While the recall is pending, the same resolution can be requested again, but it can't be changed. Once the merchant or acquirer has responded (`merchant_responded`, `prearbitration`, or later), the dispute can no longer be closed, and `allowed_close_resolutions` is empty. Use [respond to card dispute](#responding-to-the-network) instead. ### Close Outcomes | Resolution ::min | Stage | Resolution Reason | Provisional Credit | | ------------------------- | --------------- | ----------------------------- | -------------------------- | | `accept_cardholder_claim` | `dispute_won` | `customer_accepted_liability` | Issued if needed, and kept | | `cardholder_withdrew` | `dispute_close` | None | Reversed | The outcome is the same whether the dispute is closed as a draft or recalled after submission. After a close, `submission_status` is `not_required`. ## Resolution A dispute is resolved when it reaches the `dispute_won` or `dispute_close` stage. The `resolution_reason` explains the outcome. | Resolution Reason ::min | Description | | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | `merchant_accepted` | The merchant or acquirer accepted the dispute. | | `rapid_dispute_resolution` | The merchant is enrolled in the card network's rapid dispute resolution program and accepted the dispute automatically. | | `arbitration_network_ruling` | The network ruled on the dispute in arbitration. | | `issuer_liability` | Your platform accepted the merchant's or acquirer's position in full or in part with `accept` or `accept_partial`. | | `exceeded_filing_date` | The dispute was filed after the network filing window. | | `customer_accepted_liability` | Your platform closed the dispute with `accept_cardholder_claim`, taking on the loss instead of pursuing the merchant. | A dispute closed with `cardholder_withdrew` has no `resolution_reason`. ## Stages The `stage` field tracks where the dispute is in the network process. Each stage change is recorded in the dispute's `events`. | Stage ::min | Description | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------ | | `initiated` | The dispute has been created but not yet accepted by the network. | | `disputed` | The network accepted the dispute and is waiting on the merchant or acquirer. | | `merchant_responded` | The merchant contested a non-fraud dispute. | | `merchant_response_recalled` | The merchant recalled their response. | | `prearbitration` | A pre-arbitration is open: filed by your platform for a non-fraud dispute, or by the acquirer for a fraud dispute. | | `prearbitration_responded` | The other party responded to the pre-arbitration. | | `arbitration` | The dispute was escalated to the network for a ruling. | | `dispute_won` | The dispute was resolved in the cardholder's favor. | | `dispute_close` | The dispute was resolved in the merchant's favor, withdrawn, or rejected by the network. | ## Statuses The `status` field summarizes the stage and submission status into a single value. | Status ::min | Description | | ------------------------ | ----------------------------------------------------------------------------------------------- | | `open` | The dispute is in progress and nothing is needed from your platform right now, or it's a draft. | | `requires_action` | The dispute needs a response or correction from your platform. | | `manual_review_required` | The dispute is in arbitration with the network. | | `closed` | The dispute is resolved. | `status` is derived from `stage` and `submission_status`: | Status ::min | Stage | Submission Status | | ------------------------ | ------------------------------------------- | --------------------------------------------- | | `open` | Any non-terminal stage except `arbitration` | `draft`, `pending_submission`, or `submitted` | | `requires_action` | Any non-terminal stage except `arbitration` | `requires_action` or `failed` | | `manual_review_required` | `arbitration` | Any | | `closed` | `dispute_won` or `dispute_close` | Any, usually `not_required` | ## Events Card dispute event payloads contain the [card dispute webhook payload object](/api/card-dispute/card-dispute-webhook-payload-object), which includes the dispute and the dispute event that triggered the webhook. | Event ::min | Description | | ------------------------------ | ----------------------------------------------------------------------------------------------------------------- | | `issuing.card_dispute.created` | A card dispute has been created. | | `issuing.card_dispute.updated` | A card dispute's `stage`, `submission_status`, `next_actions`, `respond_by`, or `provisional_credit` has changed. | `issuing.card_dispute.updated` fires only when one of those fields changes. Adding evidence, or evidence being sent to or received from the network, does not fire a webhook on its own. To pick up new inbound evidence, fetch the dispute when you receive an update. Provisional credits and their reversals also add events to the card transaction, which fire `issuing.card_transaction.updated`. See [Card Transactions](/card-issuing/card-transactions#webhook-events). Dispute webhooks follow the same delivery rules as other Column webhooks. See [Confirmation & Retry](/working-with-the-api/events-and-webhooks#confirmation--retry) and [Event Ordering](/working-with-the-api/events-and-webhooks#event-ordering). Each event has a unique `id` that can be used to skip duplicate deliveries.