● 争议 · /v1

争议

拉取拒付与争议,上传举证材料。举证窗口由卡组织规定,过期不可补。

争议列表

GET /v1/disputes

Query 参数

status string
payment_uid string
cursor string 上一页返回的 page.next_cursor
limit integer

响应 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> 举证截止,过期不可补
└opened_at string<date-time>
page object
└next_cursor string
└has_more boolean
请求
curl -X GET https://api.baton.example/v1/disputes \
  -H "Authorization: Bearer sk_live_xxx"

提交举证

POST /v1/disputes/{uid}/evidence

在 evidence_due_at 之前提交,过期返回 409。一次提交后不可撤回,补充需重新提交全量材料。

路径参数

uid必填 string

请求头

Idempotency-Key必填 string 商户生成的唯一串(建议 UUID/ULID)。24 小时内重放同一 key 返回首次结果,不会产生第二笔。

请求体

narrative string
file_ids string[]

响应 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> 举证截止,过期不可补
opened_at string<date-time>

错误

409幂等键复用但请求体不同,或对象当前状态不允许该操作
请求
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"
  ]
}'