Submit and track

Once the evidence checklist is satisfied, file the dispute with the card network. From here the evidence is locked and the case proceeds on the network's timeline.

Submit

Call Submit a dispute:

curl -X POST "https://api.openfabric.co/v1/disputes/b16a7072-3deb-46d3-aad0-5b95da03e8e4/submit" \
  -H "Authorization: Bearer <access_token>" \
  -H "Idempotency-Key: 40709949-0712-487c-a2fe-1dd2e64af506"

Sample response

{
  "dispute_id": "b16a7072-3deb-46d3-aad0-5b95da03e8e4",
  "status": "submitted",
  "network_reason_code": "4853",
  "network_chargeback_claim_ref": "CLM-4471982",
  "is_open": true,
  "network_chargeback_details": {
    "amount": "49.99",
    "currency": "USD",
    "network_reason_code": "4853",
    "is_partial_chargeback": false,
    "message_text": "Customer states the item was never delivered.",
    "document_indicator": true
  }
}

network_chargeback_details is the snapshot of what was filed, and network_chargeback_claim_ref is the reference of the case at the card network. Quote it in any follow-up with your network contacts.

Idempotency

Pass an Idempotency-Key header. A retry with the same key returns the original response; a duplicate that arrives while the first is still in flight returns 409. See Idempotency for the general mechanism.

Why submit can fail

Status	Meaning
409	The dispute is not in draft status: it was already submitted, or it is closed.
422	The required evidence is not complete yet, or the filing window of the reason code has passed.

A 422 returns a different shape than other errors: error (not error_code) plus missing_required:

{
  "error": "evidence_incomplete",
  "missing_required": ["fraud_attestation"]
}

Track the outcome

Read the current state with Get a dispute, or work across disputes with List/search disputes, filterable by transaction, status, reason code, and customer.

status moves through the lifecycle described in the Overview as the card network resolves the case, and is_open tells you whether the case is still active at the network, independent of status.

Collaboration: the merchant can settle first

Submitting does not always raise the chargeback straight away. The card network typically first tells the merchant that a chargeback is coming and gives them a window, 72 hours by default, to settle it themselves. Three things can happen:

The merchant	Status	What it means
Refunds your customer	refunded	The refund runs through the normal refund flow, and no chargeback is raised.
Offers a credit voucher	voucher_offered, then voucher_accepted	Accepting or declining the voucher is done directly in the card network's portal; the dispute reports the result.
Does not respond in time	chargeback	The chargeback is raised and the disputed amount is provisionally credited to you.

A case that ends in collaboration avoids the chargeback fees, so a dispute sitting in submitted for a while is expected. Wait out the window before chasing it.

After the chargeback is raised

If the merchant challenges the chargeback, the dispute moves to chargeback_challenged and the credit is taken back. Deciding to escalate the case to pre-arbitration or arbitration is done directly with the card network. The API reports the outcome, but does not raise the escalation. See The dispute lifecycle.

Settled amounts

Once a refund or chargeback settles, the dispute also carries a settlement rollup (state, latest_clearing_type, net_amount, currency, last_settled_at) and the underlying network_settlement[] entries, one per matched clearing record. Both stay empty until the first settlement clears and can lag the status by a clearing cycle or two, so treat status as the state of the case and settlement as the state of the money. See How the case is reflected in clearing and settlement.

Get notified on status changes

Rather than polling, subscribe to the Dispute updated notification, sent to your configured webhook whenever the status of a dispute changes (filed, network outcome synced, or closed):

{
  "notification_id": "3e6dd7ab-3360-4269-821e-a591bc94232c",
  "type": "v1:pba:dispute:updated",
  "created_at": "2026-07-15T09:12:00Z",
  "data": {
    "dispute_id": "b16a7072-3deb-46d3-aad0-5b95da03e8e4",
    "original_transaction_id": "830cde24-7c70-461b-a3e4-1d6ad2aa34dc",
    "original_clearing_record_id": "CLR-9911002",
    "status": "chargeback",
    "is_open": true,
    "reason_code": "goods_not_received",
    "network_chargeback_claim_ref": "CLM-4471982",
    "chargeback_id": "25859113",
    "updated_at": "2026-07-15T09:12:00Z"
  }
}

Treat the notification as a signal rather than the source of truth: call Get a dispute to read the current state. See Notifications for how notifications are delivered and retried.