Chargeback lifecycle

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

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.

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,

• Create: POST /v1/disputes with transaction_id, amount,

• Retrieve: GET /v1/disputes/{dispute_id}.
• Update: PATCH /v1/disputes/{dispute_id} with amount, reason,

• Withdraw: POST /v1/disputes/{dispute_id}/withdraw in NEW,

• Evidence: list, create (presigned upload), retrieve (download_url,

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.