Raise a dispute

Create a draft dispute against the transaction your customer contests. Nothing is sent to the card network yet, so you can still edit the dispute or add evidence before submitting it.

Create the dispute

Call Raise a chargeback dispute with the transaction and a reason code:

Sample request

{
  "original_transaction_id": "830cde24-7c70-461b-a3e4-1d6ad2aa34dc",
  "reason_code": "goods_not_received",
  "reason": "Customer states the item was never delivered."
}

Sample response

{
  "dispute_id": "b16a7072-3deb-46d3-aad0-5b95da03e8e4",
  "status": "draft",
  "original_transaction_id": "830cde24-7c70-461b-a3e4-1d6ad2aa34dc",
  "original_clearing_record_id": "CLR-9911002",
  "chargeback_system": "mastercom",
  "reason_code": "goods_not_received",
  "network_reason_code": "4853",
  "reason": "Customer states the item was never delivered.",
  "amount": "49.99",
  "currency": "USD",
  "filing_window_days": 120,
  "required_documents": [],
  "recommended_documents": ["expected_delivery_date", "proof_merchant_contacted"],
  "documents": [],
  "checklist": { "satisfied": true, "missing_required": [] },
  "created_at": "2026-07-08T13:00:00Z",
  "updated_at": "2026-07-08T13:00:00Z"
}

A dispute is always raised against one cleared record of the transaction. If the transaction has more than one, pass original_clearing_record_id to pick it; otherwise the sole (or most recent) clearing record is used.

amount defaults to the cleared amount — pass it explicitly only for a partial chargeback. currency must match the clearing record's currency; it defaults to it if omitted, and is rejected with 400 if you pass a different one. filing_window_days is the deadline for the reason code, counted from the clearing date; disputes created past that window are rejected.

Every Open Fabric reason_code maps to a reason code of the card network. The mapped value is returned as network_reason_code from draft onward, before anything is filed, so you can reconcile against network reporting.

Idempotency

Pass an Idempotency-Key header to safely retry a create call after a network timeout. See Idempotency for the general mechanism.

Reason codes

reason_code	Use when
fraud_unauthorized_card_not_present	The cardholder didn't authorize the transaction.
goods_not_received	Goods or services were paid for but never received.
defective_not_as_described	What arrived doesn't match what was ordered.
digital_goods_not_received	A digital purchase (subscription, download, in-app) was never delivered.
refund_not_processed	A promised refund was never credited.
recurring_after_cancellation	A subscription charged after the cardholder canceled it.
duplicate_processing	The same purchase was charged more than once.
incorrect_amount	The charged amount doesn't match the amount agreed at the point of interaction.

Each reason code comes with its own filing window and evidence checklist. See Manage evidence.

These codes cover the disputes you see most often, and each one carries the network's reason code and evidence rules for you: you pick what happened, not which network code applies. Cases outside this set, such as chip liability shift and other physical-card fraud, ATM disputes, no-show hotel charges, or installment billing, are raised directly with the card network using their tools.

Error cases

Status	Meaning
400	currency was supplied and doesn't match the clearing record's currency.
404	original_transaction_id cannot be found, or the transaction has no disputable clearing record.
409	A dispute that is not closed already exists on this clearing record.

Update a draft

While the dispute is still in draft, call Update a draft dispute to change amount, currency, reason_code, or reason:

Sample request

{
  "amount": "24.99",
  "reason": "Customer received only half the order."
}

Once the dispute has been submitted this returns 409. The case is with the card network at that point, so raise a new dispute if it needs different terms.

Next: Manage evidence.