Disputes & Chargeback Operations

A dispute is a chargeback on a settled CARD transaction. The provisional credit, its reversal, and the final award are themselves transactions of type DISPUTE (each with dispute_id and disputed_transaction_id), so they appear on GET /v1/transactions, in the activity feed, and on statements like any other money movement. Status is the lifecycle of the whole object; events[] is the log. Discriminate each event on type. Amounts are integer minor units plus an ISO 4217 currency. amount is always non-negative.

Create a case, attach evidence, and withdraw while the window is open. Rook files with the card network and records representment, pre-arbitration, and arbitration as the merchant and network respond.

Every creating or lifecycle POST accepts an optional Idempotency-Key. Replay of the same method, path, and body within 24 hours returns the original status and payload. All operations are program-scoped: send X-Program-ID when the API key can access more than one program.

Status

Status	Meaning
`NEW`	Opened and still editable.
`PENDING_CUSTOMER`	Waiting for cardholder evidence.
`SUBMITTED`	Filed with the card network.
`REPRESENTMENT`	Merchant represented.
`PREARBITRATION`	Pre-arbitration with the network.
`ARBITRATION`	Network arbitration.
`CASE_WON`	Terminal. The cardholder prevailed.
`CASE_CLOSED`	Terminal. The merchant prevailed, the award split, or a window expired.
`WITHDRAWN`	Terminal. The integrator withdrew the case.

Allowed transitions:

From	To
`NEW`	`PENDING_CUSTOMER`, `SUBMITTED`, `WITHDRAWN`
`PENDING_CUSTOMER`	`SUBMITTED`, `WITHDRAWN`
`SUBMITTED`	`REPRESENTMENT`, `CASE_WON`, `CASE_CLOSED`, `WITHDRAWN`
`REPRESENTMENT`	`PREARBITRATION`, `CASE_WON`, `CASE_CLOSED`
`PREARBITRATION`	`ARBITRATION`, `CASE_WON`, `CASE_CLOSED`
`ARBITRATION`	`CASE_WON`, `CASE_CLOSED`
`CASE_WON`, `CASE_CLOSED`, `WITHDRAWN`	(terminal)

The integrator moves a case only with POST /v1/disputes/{dispute_id}/withdraw (NEW, PENDING_CUSTOMER, or SUBMITTED → WITHDRAWN). Every other transition is recorded by Rook. PATCH of amount, reason, and note is accepted only in NEW and PENDING_CUSTOMER. Evidence create and delete are accepted only in those same two statuses.

stateDiagram-v2
  [*] --> NEW: create
  NEW --> PENDING_CUSTOMER: evidence requested
  NEW --> SUBMITTED: filed with network
  NEW --> WITHDRAWN: withdraw
  PENDING_CUSTOMER --> SUBMITTED: filed with network
  PENDING_CUSTOMER --> WITHDRAWN: withdraw
  SUBMITTED --> REPRESENTMENT: merchant represented
  SUBMITTED --> CASE_WON: cardholder prevailed
  SUBMITTED --> CASE_CLOSED: merchant prevailed or expired
  SUBMITTED --> WITHDRAWN: withdraw
  REPRESENTMENT --> PREARBITRATION: pre-arbitration
  REPRESENTMENT --> CASE_WON: cardholder prevailed
  REPRESENTMENT --> CASE_CLOSED: merchant prevailed
  PREARBITRATION --> ARBITRATION: arbitration
  PREARBITRATION --> CASE_WON: cardholder prevailed
  PREARBITRATION --> CASE_CLOSED: merchant prevailed
  ARBITRATION --> CASE_WON: cardholder prevailed
  ARBITRATION --> CASE_CLOSED: merchant prevailed

                    ┌─────────────────────────────────┐
  create ──────────►│              NEW                │
                    └───┬──────────┬──────────┬───────┘
                        │          │          │
              evidence  │          │          │ withdraw
              requested │          │ filed    │
                        v          v          v
              PENDING_CUSTOMER  SUBMITTED  WITHDRAWN
                        │          │
                        │ filed    ├── representment ──► REPRESENTMENT
                        v          ├── cardholder win ─► CASE_WON
                    SUBMITTED      └── merchant / expiry ► CASE_CLOSED
                                       │
                                       ├── pre-arbitration ► PREARBITRATION
                                       │                      │
                                       │                      ├── arbitration ► ARBITRATION
                                       │                      ├── CASE_WON
                                       │                      └── CASE_CLOSED
                                       └── CASE_WON / CASE_CLOSED

Deadlines

Windows are calendar days in UTC.

Window	Limit	Clock starts
Cardholder filing	120 days	The disputed `CARD` transaction’s `created_at`
Evidence	10 days	Entering `PENDING_CUSTOMER`, or create when the case stays `NEW` without files
First presentment	45 days	`customer_filed_date`
Representment	45 days	Entering `SUBMITTED`
Pre-arbitration	30 days	Entering `REPRESENTMENT`
Arbitration	30 days	Entering `PREARBITRATION`

customer_filed_date must fall inside the filing window. Missed evidence deadlines do not delete the case: Rook files with the files already uploaded (or with none) and status becomes SUBMITTED. Missed network response windows close the case (CASE_WON or CASE_CLOSED) and set resolution.reason to EXPIRED when that is why it ended.

Evidence

POST /v1/disputes/{dispute_id}/evidence with filename and content_type (application/pdf, image/jpeg, image/png, image/heic, or image/webp). The response includes id and a presigned upload_url. PUT the file bytes to that URL before upload_url_expires_at.

GET /v1/disputes/{dispute_id}/evidence/{evidence_id} returns upload_status (PENDING, UPLOADED, or FAILED) and a time-limited download_url once the file is UPLOADED. List does not include presigned URLs. Delete a file only while the dispute is NEW or PENDING_CUSTOMER.

Provisional credit and resolution

provisional_credit tracks the credit on the issuing wallet. Typical create posts it (POSTED). CASE_WON keeps it. CASE_CLOSED with no cardholder award, and WITHDRAWN, reverse it (REVERSED).

resolution is null until CASE_WON or CASE_CLOSED. It then has amount (integer minor units awarded to the cardholder), reason (CARDHOLDER_WON, MERCHANT_WON, SPLIT, or EXPIRED), and date. network_claim_ids is empty until SUBMITTED.

Operations

List: GET /v1/disputes with transaction_id, wallet_id, status, and offset pagination (page / page_size).
Create: POST /v1/disputes with transaction_id, amount, reason, customer_filed_date, and optional customer_note. Status is NEW. Send Idempotency-Key.
Retrieve: GET /v1/disputes/{dispute_id}.
Update: PATCH /v1/disputes/{dispute_id} with amount, reason, and/or note in NEW or PENDING_CUSTOMER.
Withdraw: POST /v1/disputes/{dispute_id}/withdraw in NEW, PENDING_CUSTOMER, or SUBMITTED. Send Idempotency-Key.
Evidence: list, create (presigned upload), retrieve (download_url, upload_status), and delete under /v1/disputes/{dispute_id}/evidence.

reason on create and update is FRAUD_CARD_NOT_PRESENT, FRAUD_CARD_PRESENT, GOODS_SERVICES_NOT_RECEIVED, DEFECTIVE, DUPLICATE, INCORRECT_AMOUNT, CANCELLED_RECURRING, or OTHER.