● 支付 · /v1

支付

一个接口覆盖全部渠道。创建后由路由引擎决定走哪条通道,软拒自动级联到备用渠道。

支付列表

GET /v1/payments

游标分页,不返回总数——深翻页在交易表上做 count 会拖垮库。要全量导出请用控制台的导出任务。

Query 参数

status created | pending | authorized | captured | settled | failed | cancelled | refunded | partially_refunded
reference_id string
customer_uid string
created_from string<date-time>
created_to string<date-time>
cursor string 上一页返回的 page.next_cursor
limit integer

响应 200

data object[]
└uid string Baton 支付单号:PY + yyyymmdd + 6 位序号 + 4 位校验段
└reference_id string 商户侧订单号,同商户同环境唯一
└amount integer 最小币种单位整数,USD 8900 = $89.00
└currency string
└currency_exponent integer 小数位数。JPY=0、USD=2、KWD=3;展示时用它换算
└status created | pending | authorized | captured | settled | failed | cancelled | refunded | partially_refunded created 已创建未发起 · pending 渠道处理中 · authorized 已授权待扣 · captured 已扣款 · settled 已结算 · failed 终态失败 · cancelled 终态取消 · refunded / partially_refunded 已退。 failed 与 cancelled 是终态,迟到的成功回调不会把它们翻回成功。
└is_terminal boolean 后端算好的终态标记,不要自己用 status 枚举判断
└payment_method_type string
└card_brand string
└card_last4 string
└connector_code string 最终成功(或最后一次失败)的渠道
└attempt_count integer 级联了几次
└three_ds_status string
└customer_uid string
└authorized_amount integer
└captured_amount integer
└refunded_amount integer
└created_at string<date-time>
└available_actions string[] 当前允许的操作,由后端计算。前端据此渲染按钮,不要自己推。
page object
└next_cursor string
└has_more boolean
请求
curl -X GET https://api.baton.example/v1/payments \
  -H "Authorization: Bearer sk_live_xxx"

创建支付

POST /v1/payments

一个接口覆盖全部渠道。Baton 按你配置的路由规则选通道,软拒(余额不足、风控抖动、渠道超时) 自动级联到备用渠道;硬拒(挂失、止付)直接终止,不会重试。

同步返回的是「此刻的状态」,不是最终结果。最终结果以 payment.status_changed 回调为准。

请求头

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

请求体

reference_id必填 string 你的订单号,同商户同环境唯一。重复提交返回已有支付单。
amount必填 integer
currency必填 string
capture_mode automatic | manual manual 先授权后扣款,适合发货后再扣
payment_method object 二选一:传金库 token,或传 client_session_uid 让收银台收集。
└token string
└client_session_uid string
customer_uid string
three_ds auto | force | skip auto 由规则决定;强制 3DS 会降低转化但转移拒付责任
return_url string 需要跳转时买家付完回到哪里
metadata object

响应 201

uid string Baton 支付单号:PY + yyyymmdd + 6 位序号 + 4 位校验段
reference_id string 商户侧订单号,同商户同环境唯一
amount integer 最小币种单位整数,USD 8900 = $89.00
currency string
currency_exponent integer 小数位数。JPY=0、USD=2、KWD=3;展示时用它换算
status created | pending | authorized | captured | settled | failed | cancelled | refunded | partially_refunded created 已创建未发起 · pending 渠道处理中 · authorized 已授权待扣 · captured 已扣款 · settled 已结算 · failed 终态失败 · cancelled 终态取消 · refunded / partially_refunded 已退。 failed 与 cancelled 是终态,迟到的成功回调不会把它们翻回成功。
is_terminal boolean 后端算好的终态标记,不要自己用 status 枚举判断
payment_method_type string
card_brand string
card_last4 string
connector_code string 最终成功(或最后一次失败)的渠道
attempt_count integer 级联了几次
three_ds_status string
customer_uid string
authorized_amount integer
captured_amount integer
refunded_amount integer
created_at string<date-time>
available_actions string[] 当前允许的操作,由后端计算。前端据此渲染按钮,不要自己推。

错误

400参数不合法
401密钥缺失、无效、与环境不匹配,或签名校验失败
409幂等键复用但请求体不同,或对象当前状态不允许该操作
请求
curl -X POST https://api.baton.example/v1/payments \
  -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 '{
  "reference_id": "OR20261116000104",
  "amount": 8900,
  "currency": "USD",
  "capture_mode": "automatic",
  "payment_method": {
    "token": "pm_7c2a91f4"
  },
  "customer_uid": "CUS20261116000041"
}'
响应 · 201
{
  "uid": "PY20261116000217A7F3",
  "reference_id": "OR20261116000104",
  "amount": 8900,
  "currency": "USD",
  "currency_exponent": 2,
  "status": "authorized",
  "is_terminal": false,
  "payment_method_type": "card",
  "card_brand": "visa",
  "card_last4": "4242",
  "connector_code": "adyen",
  "attempt_count": 2,
  "authorized_amount": 8900,
  "captured_amount": 0,
  "refunded_amount": 0,
  "created_at": "2026-11-16T08:12:03Z",
  "available_actions": [
    "capture",
    "void"
  ]
}

查询支付

GET /v1/payments/{uid}

回调迟迟没来、或你的状态机与我们不一致时,以这个接口为准。超时状态只能靠它收敛。

路径参数

uid必填 string

响应 200

uid string Baton 支付单号:PY + yyyymmdd + 6 位序号 + 4 位校验段
reference_id string 商户侧订单号,同商户同环境唯一
amount integer 最小币种单位整数,USD 8900 = $89.00
currency string
currency_exponent integer 小数位数。JPY=0、USD=2、KWD=3;展示时用它换算
status created | pending | authorized | captured | settled | failed | cancelled | refunded | partially_refunded created 已创建未发起 · pending 渠道处理中 · authorized 已授权待扣 · captured 已扣款 · settled 已结算 · failed 终态失败 · cancelled 终态取消 · refunded / partially_refunded 已退。 failed 与 cancelled 是终态,迟到的成功回调不会把它们翻回成功。
is_terminal boolean 后端算好的终态标记,不要自己用 status 枚举判断
payment_method_type string
card_brand string
card_last4 string
connector_code string 最终成功(或最后一次失败)的渠道
attempt_count integer 级联了几次
three_ds_status string
customer_uid string
authorized_amount integer
captured_amount integer
refunded_amount integer
created_at string<date-time>
available_actions string[] 当前允许的操作,由后端计算。前端据此渲染按钮,不要自己推。
请求
curl -X GET https://api.baton.example/v1/payments/{uid} \
  -H "Authorization: Bearer sk_live_xxx"

扣款

POST /v1/payments/{uid}/capture

仅 capture_mode=manual 且状态为 authorized 时可用。可部分扣款,剩余授权自动释放。

路径参数

uid必填 string

请求头

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

请求体

amount integer 不传表示全额扣

响应 200

uid string Baton 支付单号:PY + yyyymmdd + 6 位序号 + 4 位校验段
reference_id string 商户侧订单号,同商户同环境唯一
amount integer 最小币种单位整数,USD 8900 = $89.00
currency string
currency_exponent integer 小数位数。JPY=0、USD=2、KWD=3;展示时用它换算
status created | pending | authorized | captured | settled | failed | cancelled | refunded | partially_refunded created 已创建未发起 · pending 渠道处理中 · authorized 已授权待扣 · captured 已扣款 · settled 已结算 · failed 终态失败 · cancelled 终态取消 · refunded / partially_refunded 已退。 failed 与 cancelled 是终态,迟到的成功回调不会把它们翻回成功。
is_terminal boolean 后端算好的终态标记,不要自己用 status 枚举判断
payment_method_type string
card_brand string
card_last4 string
connector_code string 最终成功(或最后一次失败)的渠道
attempt_count integer 级联了几次
three_ds_status string
customer_uid string
authorized_amount integer
captured_amount integer
refunded_amount integer
created_at string<date-time>
available_actions string[] 当前允许的操作,由后端计算。前端据此渲染按钮,不要自己推。

错误

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

撤销授权

POST /v1/payments/{uid}/void

取消尚未扣款的授权。已扣款的单请用退款。

路径参数

uid必填 string

请求头

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

响应 200

uid string Baton 支付单号:PY + yyyymmdd + 6 位序号 + 4 位校验段
reference_id string 商户侧订单号,同商户同环境唯一
amount integer 最小币种单位整数,USD 8900 = $89.00
currency string
currency_exponent integer 小数位数。JPY=0、USD=2、KWD=3;展示时用它换算
status created | pending | authorized | captured | settled | failed | cancelled | refunded | partially_refunded created 已创建未发起 · pending 渠道处理中 · authorized 已授权待扣 · captured 已扣款 · settled 已结算 · failed 终态失败 · cancelled 终态取消 · refunded / partially_refunded 已退。 failed 与 cancelled 是终态,迟到的成功回调不会把它们翻回成功。
is_terminal boolean 后端算好的终态标记,不要自己用 status 枚举判断
payment_method_type string
card_brand string
card_last4 string
connector_code string 最终成功(或最后一次失败)的渠道
attempt_count integer 级联了几次
three_ds_status string
customer_uid string
authorized_amount integer
captured_amount integer
refunded_amount integer
created_at string<date-time>
available_actions string[] 当前允许的操作,由后端计算。前端据此渲染按钮,不要自己推。

错误

409幂等键复用但请求体不同,或对象当前状态不允许该操作
请求
curl -X POST https://api.baton.example/v1/payments/{uid}/void \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..."

恢复支付

POST /v1/payments/{uid}/resume

买家完成 3DS 或外部跳转后,用渠道返回的 resume_token 推进这笔支付。

路径参数

uid必填 string

请求头

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

请求体

resume_token必填 string

响应 200

uid string Baton 支付单号:PY + yyyymmdd + 6 位序号 + 4 位校验段
reference_id string 商户侧订单号,同商户同环境唯一
amount integer 最小币种单位整数,USD 8900 = $89.00
currency string
currency_exponent integer 小数位数。JPY=0、USD=2、KWD=3;展示时用它换算
status created | pending | authorized | captured | settled | failed | cancelled | refunded | partially_refunded created 已创建未发起 · pending 渠道处理中 · authorized 已授权待扣 · captured 已扣款 · settled 已结算 · failed 终态失败 · cancelled 终态取消 · refunded / partially_refunded 已退。 failed 与 cancelled 是终态,迟到的成功回调不会把它们翻回成功。
is_terminal boolean 后端算好的终态标记,不要自己用 status 枚举判断
payment_method_type string
card_brand string
card_last4 string
connector_code string 最终成功(或最后一次失败)的渠道
attempt_count integer 级联了几次
three_ds_status string
customer_uid string
authorized_amount integer
captured_amount integer
refunded_amount integer
created_at string<date-time>
available_actions string[] 当前允许的操作,由后端计算。前端据此渲染按钮,不要自己推。
请求
curl -X POST https://api.baton.example/v1/payments/{uid}/resume \
  -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 '{
  "resume_token": "rt_9d12ac"
}'

调整授权金额

POST /v1/payments/{uid}/adjust-authorization

订单加减货导致金额变化时追加或释放授权额度。仅部分渠道支持,不支持时返回 409。

路径参数

uid必填 string

请求头

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

请求体

amount必填 integer 调整后的目标总额,不是差额

响应 200

uid string Baton 支付单号:PY + yyyymmdd + 6 位序号 + 4 位校验段
reference_id string 商户侧订单号,同商户同环境唯一
amount integer 最小币种单位整数,USD 8900 = $89.00
currency string
currency_exponent integer 小数位数。JPY=0、USD=2、KWD=3;展示时用它换算
status created | pending | authorized | captured | settled | failed | cancelled | refunded | partially_refunded created 已创建未发起 · pending 渠道处理中 · authorized 已授权待扣 · captured 已扣款 · settled 已结算 · failed 终态失败 · cancelled 终态取消 · refunded / partially_refunded 已退。 failed 与 cancelled 是终态,迟到的成功回调不会把它们翻回成功。
is_terminal boolean 后端算好的终态标记,不要自己用 status 枚举判断
payment_method_type string
card_brand string
card_last4 string
connector_code string 最终成功(或最后一次失败)的渠道
attempt_count integer 级联了几次
three_ds_status string
customer_uid string
authorized_amount integer
captured_amount integer
refunded_amount integer
created_at string<date-time>
available_actions string[] 当前允许的操作,由后端计算。前端据此渲染按钮,不要自己推。

错误

409幂等键复用但请求体不同,或对象当前状态不允许该操作
请求
curl -X POST https://api.baton.example/v1/payments/{uid}/adjust-authorization \
  -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 '{
  "amount": 9900
}'