预授权冻结的对账问题:CLOSED 覆盖两种结局,解冻流水号不能复用
现象
围绕支付宝预授权冻结的报障,基本落在下面几类。
一是查询接口返回 rest_amount 为 0,同一条流水却是 operation_type = FREEZE,第一反应是数据错了。
二是商户查 order_status 看到 CLOSED,据此判断“押金已退、流程结束”,但用户账单里确实有一笔扣款。
三是重试引发的问题:解冻工单重发报错,或者转支付时 out_trade_no 复用直接被打回。
四是对账公式不成立,total_freeze_amount - total_pay_amount 和 rest_amount 对不上。
这些问题大多不是接口故障,而是把几个名字相同、语义不同的东西混在了一起。
参考文档:预授权支付 快速接入、资金授权冻结接口 alipay.fund.auth.order.freeze、如何查询冻结订单扣款金额或者解冻成功。
三种「冻结」先分清
排查前先确认参数落在哪一层,否则后面每一步都会误判。
预授权冻结:由商户端主动向用户账户冻结额度,调用 alipay.fund.auth.order.freeze,对应 product_code = PREAUTH_PAY。冻结成功后钱仍在用户账户里,只是不可用,钱并没有转到商户账户。
风控/渠道冻结:支付渠道把订单状态置为 TRADE_FREEZE,冻的是商户已经收到的资金,冻结期间不能提现,申诉通过后转 TRADE_UNFREEZE。这是渠道或平台对商户侧资金的处理,与预授权不是同一层,不能拿 TRADE_FREEZE 去解释预授权的 status。
信用授权:出参 pre_auth_type 返回 CREDIT_AUTH,表示这笔是信用授权,没有真实冻结资金。pre_auth_type 为空或非 CREDIT_AUTH 才是普通资金授权,真的冻了用户的钱。这一步决定了后面“用户说钱被冻了”到底该不该成立。
三个金额口径与等式
查询走 alipay.fund.auth.operation.detail.query,必返四个字段:
total_freeze_amount:累计冻结,资金 + 信用rest_amount:剩余冻结,支付/解冻后的余额total_pay_amount:累计用于支付amount:本次operation_id对应操作的金额
另有八个拆分字段:total_freeze_credit_amount、total_freeze_fund_amount、total_pay_credit_amount、total_pay_fund_amount、rest_credit_amount、rest_fund_amount、credit_amount、fund_amount。这八个不一定会返回,以实际调用结果为准,不要把拆分字段当作必返项写进对账逻辑。
等式关系:
total_freeze_amount = total_freeze_credit_amount + total_freeze_fund_amount
total_pay_amount = total_pay_credit_amount + total_pay_fund_amount
rest_amount = rest_credit_amount + rest_fund_amount
rest_amount = 0 表示已经没有任何冻结。需要留意:如果用户支付后设置了自动解冻,会出现 total_freeze_amount - total_pay_amount ≠ rest_amount。遇到等式不成立,先查这笔是否加了自动解冻,再去怀疑数据。
CLOSED / FINISH 的状态语义陷阱
order_status 的取值:
| 值 | 含义 |
|---|---|
AUTH_ORDER_NOT_EXIST | 订单不存在 |
INIT | 已创建未授权 |
AUTHORIZED | 已授权,可转支付或解冻 |
CLOSED | 授权未完成超时关闭,或冻结资金全额解冻 |
FINISH | 转支付完成且无剩余冻结 |
问题出在 CLOSED 一个值覆盖了两种完全相反的结局:压根没有冻结成功,和冻结成功但后来又全部解冻了。如果只看 CLOSED 就对外说“这单本来就没冻成”,对账时必然出错。
另外要注意,AUTHORIZED 并不是“已冻结未扣款”的专属状态:
- 只冻结、没转支付 →
AUTHORIZED - 冻结后转支付、但剩余仍是冻结的 → 还是
AUTHORIZED
FINISH 才代表转支付完成且没有剩余冻结。
operation_type(FREEZE / UNFREEZE / PAY)是这条 operation_id 对应流水的操作类型,不是整笔授权单的状态。所以 rest_amount = 0 时 operation_type = FREEZE 是正常数据:这一笔记录对应的是冻结操作,但这笔冻结已经被全额解冻了。单条流水的类型和整单当前余额,是两个维度。
冻结/解冻/撤销/转支付的互斥与幂等
这几个接口之间有两类互斥关系:一个是调用顺序上的,一个是单号上的。
out_order_no 与 out_request_no 永不复用。 冻结接口的 out_order_no 是商户授权资金订单号,创建后不能修改,商户端唯一。out_request_no 是资金操作请求流水号,唯一;解冻接口 alipay.fund.auth.order.unfreeze 支持部分解冻,并按 out_request_no 幂等返回,所以每次资金操作都必须用不同的 out_request_no。
部分解冻必须换流水号。 第一次解冻 50 元,第二次再解 30 元,两次的 out_request_no 必须不同,否则第二次会被当成重发。反过来,同一笔解冻请求重发,解冻流水号和解冻金额都必���保持完全一致,改金额等于换了一笔业务。
转支付 out_trade_no 任何情况下不可重复。 调用 alipay.trade.pay 时传 auth_no,product_code 预授权传 PREAUTH_PAY。auth_confirm_mode 传 COMPLETE 表示转支付并把剩余授权资金解冻;传 NOT_COMPLETE 或不传则只转支付、剩余仍冻结。out_trade_no 失败过、撤销过都不能复用,复用直接报错。
撤销不是解冻。 alipay.fund.auth.operation.cancel 只用于两种场景:业务系统超时需要终止流程,或授权结果未知、查询接口拿不到明确结果。正常已冻结要退,应该调解冻接口。出参 action 有两个值:close 表示关闭订单且无资金解冻,unfreeze 表示产生了资金解冻。也就是说“撤销成功”不等于“没动过钱”,回执里必须看 action。
冻结成功 ≠ 扣款成功。 冻结成功时押金还在用户账户,只是不可用;扣款成功(转支付)才是钱从用户账户到了商户账户。这两件事在状态机上是两步。
排查要点怎么做
第一步,按冻结返回码分流。 alipay.fund.auth.order.freeze 四种结果:
10000:授权成功40004:授权失败10003:等待用户授权,须 5 秒后调alipay.fund.auth.operation.detail.query轮询,建议总轮询 30s;最后一次仍为INIT,必须立刻调alipay.fund.auth.operation.cancel撤销20000:未知异常,调查询接口确认
10003 这条分支最容易漏。轮询到超时还没结果就放着不管,会留下一笔状态不明的授权单。
第二步,查询接口里怎么读。 先取 order_status 判断整单处在哪个阶段,再取 operation_type 判断这条流水做了什么,最后取 rest_amount 判断还剩多少冻结。三个字段一起看,不要只看一个。同时读 pre_auth_type,确认是资金授权还是 CREDIT_AUTH。
第三步,代回等式。 用 total_freeze_amount、total_pay_amount、rest_amount 互相校验;拆分字段有返回就一起代入,没返回就以实测为准,不要硬算。等式不成立时,第一嫌疑是自动解冻。
冻结请求的固定参数也一并核对:product_code 预授权传 PREAUTH_PAY,老当面资金授权传 PRE_AUTH 或 FUND_TRADE_FAST_PAY;auth_code_type 固定 bar_code;amount 单位为元、两位小数,范围 [0.01, 100000000.00];pay_timeout 取值 1m~15d,不接受小数,为空默认 15m。
边界
不支持追加冻结。 冻结金额必须一开始就大于未来消费转支付金额,中途发现不够,只能重新走一笔,不能在原单上加。
pay_timeout 默认 15m。 租车、酒店这类场景如果用户授权动作慢,默认值容易导致超时关闭,落进 CLOSED 的第一种含义里。
CREDIT_AUTH 不冻真钱。 这类单子也会计入 total_freeze_amount,对账时如果只看总额不看 pre_auth_type,会得出“用户被冻了钱”的错误结论。
自动解冻会破坏等式。 total_freeze_amount - total_pay_amount ≠ rest_amount 在开启自动解冻时是预期行为,不要当成数据异常上报。
解冻必须商户端发起。 支付宝不会自动解冻。除此之外,remark 会展示在用户账单上,别往里塞内部单号或调试信息。