● Disputes · /v1

Disputes

Pull chargebacks and disputes, upload evidence. The evidence window is set by the card networks and cannot be extended once it closes.

List disputes

GET /v1/disputes

Query parameters

status string
payment_uid string
cursor string The page.next_cursor returned by the previous page
limit integer

Response 200

data object[]
└uid string
└payment_uid string
└status opened | under_review | won | lost | expired
└reason_code string
└amount integer
└currency string
└evidence_due_at string<date-time> Evidence deadline; cannot be extended once passed
└opened_at string<date-time>
page object
└next_cursor string
└has_more boolean
Request
curl -X GET https://api.baton.example/v1/disputes \
  -H "Authorization: Bearer sk_live_xxx"

Submit evidence

POST /v1/disputes/{uid}/evidence

Submit before evidence_due_at; later returns 409. A submission cannot be withdrawn — to add material, resubmit the complete set.

Path parameters

uidrequired string

Headers

Idempotency-Keyrequired string A unique string you generate (UUID/ULID recommended). Replaying the same key within 24 hours returns the original result and never creates a second payment.

Body

narrative string
file_ids string[]

Response 200

uid string
payment_uid string
status opened | under_review | won | lost | expired
reason_code string
amount integer
currency string
evidence_due_at string<date-time> Evidence deadline; cannot be extended once passed
opened_at string<date-time>

Errors

409The idempotency key was reused with a different body, or the object's state does not allow this operation
Request
curl -X POST https://api.baton.example/v1/disputes/{uid}/evidence \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..." \
  -H "Content-Type: application/json" \
  -d '{
  "narrative": "Shipment delivered and signed on 2026-11-02.",
  "file_ids": [
    "file_9a21",
    "file_9a22"
  ]
}'