● 支付尝试 · /v1

支付尝试

一笔支付由 N 次尝试组成,每次尝试对应一个渠道。尝试被显式建模,级联过程可查可干预。

列出支付尝试

GET /v1/payments/{uid}/attempts

级联过程全部可见:每次走了哪个渠道、原始拒付码是什么、统一码归到哪类、耗时多少。 排查「为什么这笔没成」只看这个接口就够。

路径参数

uid必填 string

响应 200

uid string
attempt_no integer
is_fallback boolean 是否由级联触发
fallback_reason string
connector_code string
status pending | success | failed | timeout timeout 是独立状态:结果未知,由对账补偿,不可直接当失败重试
provider_code string 渠道原始拒付码
unified_code string Baton 统一拒付码,跨渠道可比。HTTP 仍是 200——调用成功了,是这笔支付没成。全量取值见「错误码自查」
decline_type soft | hard | '' hard 永不重试(挂失、止付、风控拒),重试只会加剧风控
latency_ms integer
started_at string<date-time>
finished_at string<date-time>
action object 需要外部动作时返回,前端据此跳转
└type redirect | qrcode | three_ds_challenge
└url string
└expires_at string<date-time>
请求
curl -X GET https://api.baton.example/v1/payments/{uid}/attempts \
  -H "Authorization: Bearer sk_live_xxx"
响应 · 200
[
  {
    "uid": "ATT16000217A7F31",
    "attempt_no": 1,
    "is_fallback": false,
    "connector_code": "stripe",
    "status": "failed",
    "provider_code": "51",
    "unified_code": "insufficient_funds",
    "decline_type": "soft",
    "latency_ms": 420,
    "started_at": "2026-11-16T08:12:03Z",
    "finished_at": "2026-11-16T08:12:04Z"
  },
  {
    "uid": "ATT16000217A7F32",
    "attempt_no": 2,
    "is_fallback": true,
    "fallback_reason": "soft_decline",
    "connector_code": "adyen",
    "status": "success",
    "unified_code": "",
    "decline_type": "",
    "latency_ms": 610,
    "started_at": "2026-11-16T08:12:04Z",
    "finished_at": "2026-11-16T08:12:05Z"
  }
]

放行尝试

POST /v1/payment-attempts/{uid}/approve

路由规则配置了人工审核时,用它放行一次被挂起的尝试。

路径参数

uid必填 string

请求头

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

响应 200

uid string
attempt_no integer
is_fallback boolean 是否由级联触发
fallback_reason string
connector_code string
status pending | success | failed | timeout timeout 是独立状态:结果未知,由对账补偿,不可直接当失败重试
provider_code string 渠道原始拒付码
unified_code string Baton 统一拒付码,跨渠道可比。HTTP 仍是 200——调用成功了,是这笔支付没成。全量取值见「错误码自查」
decline_type soft | hard | '' hard 永不重试(挂失、止付、风控拒),重试只会加剧风控
latency_ms integer
started_at string<date-time>
finished_at string<date-time>
action object 需要外部动作时返回,前端据此跳转
└type redirect | qrcode | three_ds_challenge
└url string
└expires_at string<date-time>
请求
curl -X POST https://api.baton.example/v1/payment-attempts/{uid}/approve \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..."

终止尝试

POST /v1/payment-attempts/{uid}/abort

终止一次挂起的尝试。若无后续备用渠道,整笔支付转为 failed(终态)。

路径参数

uid必填 string

请求头

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

响应 200

uid string
attempt_no integer
is_fallback boolean 是否由级联触发
fallback_reason string
connector_code string
status pending | success | failed | timeout timeout 是独立状态:结果未知,由对账补偿,不可直接当失败重试
provider_code string 渠道原始拒付码
unified_code string Baton 统一拒付码,跨渠道可比。HTTP 仍是 200——调用成功了,是这笔支付没成。全量取值见「错误码自查」
decline_type soft | hard | '' hard 永不重试(挂失、止付、风控拒),重试只会加剧风控
latency_ms integer
started_at string<date-time>
finished_at string<date-time>
action object 需要外部动作时返回,前端据此跳转
└type redirect | qrcode | three_ds_challenge
└url string
└expires_at string<date-time>
请求
curl -X POST https://api.baton.example/v1/payment-attempts/{uid}/abort \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..."

收敛挂起的尝试

POST /v1/payment-attempts/{uid}/resolve

外部系统(你的风控、人工审核队列)已经有结论时,用它让这次尝试按给定结果收敛, 不用等我们的超时兜底。只能用于 pending 的尝试,已终态的返回 409。

路径参数

uid必填 string

请求头

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

请求体

outcome必填 success | failed
provider_txn_id string outcome=success 时必填,用于对账
reason string

响应 200

uid string
attempt_no integer
is_fallback boolean 是否由级联触发
fallback_reason string
connector_code string
status pending | success | failed | timeout timeout 是独立状态:结果未知,由对账补偿,不可直接当失败重试
provider_code string 渠道原始拒付码
unified_code string Baton 统一拒付码,跨渠道可比。HTTP 仍是 200——调用成功了,是这笔支付没成。全量取值见「错误码自查」
decline_type soft | hard | '' hard 永不重试(挂失、止付、风控拒),重试只会加剧风控
latency_ms integer
started_at string<date-time>
finished_at string<date-time>
action object 需要外部动作时返回,前端据此跳转
└type redirect | qrcode | three_ds_challenge
└url string
└expires_at string<date-time>

错误

409幂等键复用但请求体不同,或对象当前状态不允许该操作
请求
curl -X POST https://api.baton.example/v1/payment-attempts/{uid}/resolve \
  -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 '{
  "outcome": "success",
  "provider_txn_id": "ADY-8820371"
}'