POST /v1/payments/{uid}/capture
仅 capture_mode=manual 且状态为 authorized 时可用。可部分扣款,剩余授权自动释放。
路径参数
请求头
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}/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
路径参数
请求头
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 推进这笔支付。
路径参数
请求头
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[] | 当前允许的操作,由后端计算。前端据此渲染按钮,不要自己推。 |
请求
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。
路径参数
请求头
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
}'