Card Disputes

API Documentation

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 for the transaction, amount, and reason.
2. Create the dispute, optionally issuing the cardholder a provisional credit.
3. Add evidence until the dispute has everything its reason requires.
4. Submit the dispute to the card network.
5. Respond when the merchant or acquirer contests the dispute.
6. The dispute is resolved 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 holds the claim, its current state, and what your platform can do next. Amounts are in the smallest unit of the dispute's currency.

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 the dispute follows.

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 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.
• Document means the dispute needs an uploaded 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

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.

Workflows

The workflow field shows how the dispute progresses through the card network, based on its reason.

Eligibility

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

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.

Windows close at 09:00 UTC on the last day.

Creating a Dispute

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

curl https://api.column.com/issuing/card-disputes \
  -XPOST \
  -H 'Content-Type: application/json' \
  -u :<YOUR API KEY> \
  --data '{
      "card_transaction_id": "<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 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.

curl https://api.column.com/issuing/card-disputes/documents \
  -XPOST \
  -u :<YOUR API KEY> \
  -F file=@receipt.pdf \
  -F description='Cardholder receipt'

Then add it to the dispute with an evidence_type. The same endpoint also accepts a narrative, missing reason_details, or a reason_for_partial_dispute.

curl https://api.column.com/issuing/card-disputes/<card_dispute_id>/evidence \
  -XPOST \
  -H 'Content-Type: application/json' \
  -u :<YOUR API KEY> \
  --data '{
      "document_id": "<document_id>",
      "evidence_type": "transaction_receipt"
  }'

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

Submitting a Dispute

When next_actions contains submit, the dispute has everything it needs. Submit it with POST /issuing/card-disputes/<card_dispute_id>/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.

A failed dispute can be corrected with additional evidence and submitted again. A failed response can be sent again with 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. A draft's credit can be removed with 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, 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.

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.

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

curl https://api.column.com/issuing/card-disputes/<card_dispute_id>/respond \
  -XPOST \
  -H 'Content-Type: application/json' \
  -u :<YOUR API KEY> \
  --data '{
      "action": "escalate",
      "narrative": "The tracking number provided by the merchant shows delivery to a different address than the cardholder provided.",
      "evidence": [
        {
          "document_id": "<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

Closing a Dispute

Your platform can close a dispute with one of the following resolutions. The allowed_close_resolutions field lists the resolutions currently accepted.

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

Close Outcomes

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.

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.

Statuses

The status field summarizes the stage and submission status into a single value.

status is derived from stage and submission_status:

Events

Card dispute event payloads contain the card dispute webhook payload object, which includes the dispute and the dispute event that triggered the webhook.

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.

Dispute webhooks follow the same delivery rules as other Column webhooks. See Confirmation & Retry and Event Ordering. Each event has a unique id that can be used to skip duplicate deliveries.