取消支付

契约 v1.0.0

本页目录

cancelPayment

POST/v1/payments/{payment_id}/cancel

所需权限payments:write需要幂等键

在能证明安全时关闭支付，无请求体。created 及无在途尝试的 failed 可直接取消。 requires_action 只有在上游确认取消且确认没有成功扣款后才变为 canceled；无法确认时返回 202，保持原状态或 processing 并查证，不在本地强制取消。 processing、succeeded 等不可取消的状态返回 409。

请求头

请求头	必填	格式	说明
Authorization	是	Bearer <API_KEY>	服务端密钥，只能在商户服务端使用；商户与环境由密钥推导。缺失、无效、撤销或过期返回 401。
Idempotency-Key	是	1–255 个可见 ASCII 字符	幂等键，1–255 个可见 ASCII 字符。作用域为商户、环境、方法与路径：同键且安全业务参数一致时复用原业务对象，参数冲突返回 409 idempotency_conflict。一次提交使用一个键，网络重试沿用原键；换卡等新的提交使用新键。同键并发时只有一个请求取得执行权，其余请求等待其事务提交后返回同一对象（200）；等待超时返回 409 operation_in_progress（retryable=true），稍后用原键重试。被 400、401、403、422 拒绝的请求不占用幂等键，修正后用新键提交。

请求示例

curl

curl -X POST 'https://api.payhub.bbpays.site/v1/payments/<PAYMENT_ID>/cancel' \
  -H 'Authorization: Bearer <TEST_SERVER_API_KEY>' \
  -H 'Idempotency-Key: <UNIQUE_OPERATION_KEY>'

需要替换的占位符

<PAYMENT_ID>：创建支付返回的 id（pay_ 开头）
<TEST_SERVER_API_KEY>：测试环境服务端 API Key：在商户后台「API Key」页面创建
<UNIQUE_OPERATION_KEY>：你为这次提交生成的幂等键（如 UUID），网络重试沿用同一个

说明

服务端 API Key 只能在你的服务端使用，文档站不提供在线调试。获取测试 Key：商户后台 API Key（在新标签页打开商户后台）（测试环境；需要所有者、管理员或开发者）

响应

已取消（status=canceled），或同键幂等复用。

尚未提交的支付已安全取消

{
  "id": "pay_demo_006",
  "merchant_order_no": "ORDER-DEMO-006",
  "environment": "test",
  "amount": 10000,
  "currency": "USD",
  "status": "canceled",
  "resolution_status": "known",
  "captured_amount": 0,
  "refunded_amount": 0,
  "refund_returned_amount": 0,
  "refund_reserved_amount": 0,
  "refund_status": "none",
  "authentication_status": null,
  "reconciliation_status": "pending",
  "upstream_receipt_status": "not_received",
  "latest_attempt_id": null,
  "attempt_count": 0,
  "version": 2,
  "next_action": null,
  "failure": null,
  "description": "示例订单",
  "customer_reference": "CUSTOMER-DEMO-006",
  "metadata": {
    "business_order_type": "one_time_purchase"
  },
  "card": null,
  "created_at": "2026-09-23T09:00:00Z",
  "succeeded_at": null,
  "expires_at": "2026-09-23T09:30:00Z",
  "request_id": "req_demo_016"
}

响应字段

返回对象字段说明见对象小节。

名称	类型	必填	说明
`id`	string	必填	平台支付号。示例：`pay_demo_001`
`merchant_order_no`	string	必填	商户订单号，按原值区分大小写。示例：`ORDER-DEMO-001`
`environment`	string	必填	环境：test 为测试，live 为生产。测试与生产对象相互隔离。 `test` `live` 将来可能新增取值；不认识的状态不要当作成功。示例：`test`
`amount`	integer(int64)	必填	订单金额，最小货币单位。首次提交上游后不可修改。约束：`≥ 1` 示例：`10000`
`currency`	string	必填	大写三字母币种代码。约束：`格式 ^[A-Z]{3}$` 示例：`USD`
`status`	string	必填	Payment 状态。客户端不得把未知状态当作成功。 created：订单已建立，尚未提交有效扣款尝试；有效期内允许新尝试 processing：已提交，正在处理或结果尚未确认；不允许新尝试 requires_action：当前尝试需要付款人完成认证等动作；不允许新尝试 failed：最近一次尝试已明确失败；不是终态，满足期限、次数与风控条件时可显式重试 succeeded：已确认支付成功 canceled：已确认安全取消 expired：没有未解决的尝试且订单已到期关闭 `created`：订单已建立，尚未提交有效扣款尝试；有效期内允许新尝试 `processing`：已提交，正在处理或结果尚未确认；不允许新尝试 `requires_action`：当前尝试需要付款人完成认证等动作；不允许新尝试 `failed`：最近一次尝试已明确失败；不是终态，满足期限、次数与风控条件时可显式重试 `succeeded`：已确认支付成功 `canceled`：已确认安全取消 `expired`：没有未解决的尝试且订单已到期关闭将来可能新增取值；不认识的状态不要当作成功。示例：`requires_action`
`resolution_status`	string	必填	结果确认程度。 known：结果已确认 needs_query：结果未知，平台正在用原标识向上游查证 manual_review：超过自动查询窗口，转人工跟进；不会自动判失败 `known`：结果已确认 `needs_query`：结果未知，平台正在用原标识向上游查证 `manual_review`：超过自动查询窗口，转人工跟进；不会自动判失败将来可能新增取值；不认识的状态不要当作成功。示例：`known`
`captured_amount`	integer(int64)	必填	已确认扣款金额；成功时等于 amount。约束：`≥ 0` 示例：`0`
`refunded_amount`	integer(int64)	必填	已确认的有效退款本金，即成功退款累计减去已确认的退款退回；不含处理中的退款，也不含平台异常退款。约束：`≥ 0` 示例：`0`
`refund_returned_amount`	integer(int64)	必填	已确认退回的退款本金累计。约束：`≥ 0` 示例：`0`
`refund_reserved_amount`	integer(int64)	必填	审核中及处理中退款的本金占用。约束：`≥ 0` 示例：`0`
`refund_status`	string	必填	按有效退款本金 refunded_amount 派生的退款汇总状态：none、partial、full。 `none` `partial` `full` 将来可能新增取值；不认识的状态不要当作成功。示例：`none`
`authentication_status`	string可为空	必填	当前尝试的 3DS 认证状态，取认证会话状态：not_required、pending、challenge、authenticated、failed、abandoned、expired，须容忍新增取值。认证成功（authenticated）不等于扣款成功，不要据此判断支付结果。尚无尝试或未进入认证时为 null。示例：`challenge`
`reconciliation_status`	ReconciliationStatus	必填	平台资金处理进度，仅供对账参考，不代表支付是否成功，也不代表何时打款。 `pending` `matched` `difference` `resolved` 将来可能新增取值；不认识的状态不要当作成功。
`upstream_receipt_status`	UpstreamReceiptStatus	必填	平台资金处理进度，仅供对账参考，不代表支付是否成功，也不代表何时打款。 `not_received` `partially_received` `received` `reversed` 将来可能新增取值；不认识的状态不要当作成功。
`latest_attempt_id`	string可为空	必填	最近一次支付尝试号；尚未提交尝试时为 null。示例：`pat_demo_001`
`attempt_count`	integer(int32)	必填	已发起的尝试次数；默认最多 3 次。约束：`≥ 0` 示例：`1`
`version`	integer(int64)	必填	对象版本，每次有效业务变更递增。比较版本来丢弃旧事件，不要按状态名排序。约束：`≥ 1` 示例：`2`
`next_action`	NextAction可为空	必填	status=requires_action 时需要付款人完成的动作，其他情况为 null。
`type`	string	必填	首期公共 API 只开放 redirect_to_url。客户端须容忍未来新增的类型。 `redirect_to_url` 将来可能新增取值；不认识的状态不要当作成功。示例：`redirect_to_url`
`authentication_session_id`	string	必填	认证会话号，关联具体的支付尝试。示例：`auth_demo_001`
`url`	string(uri)	必填	平台认证承载页地址。示例：`https://pay.payhub.example/auth/<SHORT_LIVED_TOKEN>`
`expires_at`	string(date-time)	必填	认证访问的失效时间（最长 10 分钟）。示例：`2026-09-23T09:10:00Z`
`failure`	PaymentFailure可为空	必填	latest_attempt_id 所指尝试明确失败时的原因，否则为 null。
`code`	string	必填	失败原因码。示例：`card_declined`
`message`	string	必填	脱敏说明。示例：`发卡行拒绝了该交易。`
`attempt_id`	string	必填	失败的支付尝试号。示例：`pat_demo_001`
`description`	string	否	订单摘要。约束：`最长 256` 示例：`示例订单`
`customer_reference`	string	否	商户侧客户标识。约束：`最长 128` 示例：`CUSTOMER-DEMO-001`
`metadata`	object	否	商户自定义键值，最多 20 个键；键最长 40 字符，值为最长 200 字符的字符串。禁止放入卡号等敏感数据，平台会做检查并拒绝。约束：`最多 20 个键值最长 200` 示例：`{"business_order_type":"one_time_purchase"}`
`card`	CardSummary可为空	必填	最近一次尝试所用卡的脱敏信息；尚无卡信息时为 null。
`brand`	string	必填	卡品牌。示例：`visa`
`last4`	string	必填	卡号后四位。约束：`格式 ^[0-9]{4}$` 示例：`1234`
`created_at`	string(date-time)	必填	创建时间。示例：`2026-09-23T09:00:00Z`
`succeeded_at`	string(date-time)可为空	必填	确认支付成功的时间；未成功时为 null。示例：`null`
`expires_at`	string(date-time)	必填	可发起新尝试的截止时间，创建时确定（默认创建后 30 分钟，平台可在 5–120 分钟之间调整，以本字段为准）。到期只关闭新的付款入口，不否定已提交的支付。示例：`2026-09-23T09:30:00Z`
`request_id`	string	必填	本次请求的唯一标识，用于排查与支持。示例：`req_demo_001`

可能的错误码

HTTP	错误码	何时出现	如何处理
400	invalid_request	缺 `Idempotency-Key`；订单号含非法字符；`payment_method_data` 与 `payment_method_id` 同时提交；`confirm=false` 携带卡信息；`confirm=true` 缺 `return_url`；收银会话两组身份参数同时提交或都缺；缺少上游要求的 `browser_info` / `billing_details` 字段；游标、时间格式、`limit` 不合法	按 `error.field` 修正后重新提交，不要自动重扣
404	not_found	ID 错误；用测试 Key 查询生产对象；查询平台异常退款（不通过开放 API 返回）	核对 ID 与 Key 的环境；平台不会透露对象是否属于其他商户
409	operation_in_progress	并发发送了同键请求	稍后用同一个键重试，或查询 `related_resource_id`；不要换键
409	invalid_state	取消 `processing` / `succeeded` 的支付；对已过期、已取消、已成功的订单 confirm；为不可支付的订单创建收银会话	查询对象最新状态后决定
401	unauthenticated通用	未带 `Authorization`；Key 复制不完整；轮换后旧 Key 已过期；Key 被撤销	检查凭据，在商户后台 API Key 页面核对 Key 状态与环境
403	forbidden通用	只读 Key 创建退款；`getEvent` 缺少事件所属业务的读权限；请求来源 IP 不在 Key 的白名单时返回更具体的 `ip_not_allowed`	使用具备所需 scope 的 Key；不要绕过限制
429	rate_limited通用	商户、Key 维度的频率限制；换 Key 不能绕过商户总限额	等待 `Retry-After` 秒后用原幂等键重试
500	internal_error通用	—	用原幂等键重试或按商户订单号 / 退款号查询；不能换键重扣
502 / 503	upstream_unavailable通用	上游或平台依赖故障，平台无法确认本次请求是否已生效	同上

注意事项

没有请求体，但必须带幂等键。
created 与没有在途尝试的 failed 可以直接取消。
requires_action 只有在上游确认取消、且确认没有成功扣款后才会变为 canceled；无法确认时返回 202 并保持原状态，平台继续查证。
processing、succeeded 等状态不能取消，返回 409 invalid_state。

注意

202 不等于已取消：以 payment.canceled 事件或查询结果为准。

这页有帮助吗？

取消支付

请求头

请求示例

响应

响应字段

可能的错误码

注意事项

相关