API 参考

平台支付号。

商户订单号，按原值区分大小写。

环境：test 为测试，live 为生产。测试与生产对象相互隔离。

订单金额，最小货币单位。首次提交上游后不可修改。

大写三字母币种代码。

Payment 状态。客户端不得把未知状态当作成功。

• created：订单已建立，尚未提交有效扣款尝试；有效期内允许新尝试
• processing：已提交，正在处理或结果尚未确认；不允许新尝试
• requires_action：当前尝试需要付款人完成认证等动作；不允许新尝试
• failed：最近一次尝试已明确失败；不是终态，满足期限、次数与风控条件时可显式重试
• succeeded：已确认支付成功
• canceled：已确认安全取消
• expired：没有未解决的尝试且订单已到期关闭

结果确认程度。

• known：结果已确认
• needs_query：结果未知，平台正在用原标识向上游查证
• manual_review：超过自动查询窗口，转人工跟进；不会自动判失败

已确认扣款金额；成功时等于 amount。

已确认的有效退款本金，即成功退款累计减去已确认的退款退回；不含处理中的退款，也不含平台异常退款。

已确认退回的退款本金累计。

审核中及处理中退款的本金占用。

按有效退款本金 refunded_amount 派生的退款汇总状态：none、partial、full。

当前尝试的 3DS 认证状态，取认证会话状态：not_required、pending、challenge、authenticated、failed、abandoned、expired，须容忍新增取值。 认证成功（authenticated）不等于扣款成功，不要据此判断支付结果。尚无尝试或未进入认证时为 null。

平台资金处理进度，仅供对账参考，不代表支付是否成功，也不代表何时打款。

平台资金处理进度，仅供对账参考，不代表支付是否成功，也不代表何时打款。

最近一次支付尝试号；尚未提交尝试时为 null。

已发起的尝试次数；默认最多 3 次。

对象版本，每次有效业务变更递增。比较版本来丢弃旧事件，不要按状态名排序。

status=requires_action 时需要付款人完成的动作，其他情况为 null。

首期公共 API 只开放 redirect_to_url。客户端须容忍未来新增的类型。

认证会话号，关联具体的支付尝试。

平台认证承载页地址。

认证访问的失效时间（最长 10 分钟）。

latest_attempt_id 所指尝试明确失败时的原因，否则为 null。

失败原因码。

脱敏说明。

失败的支付尝试号。

订单摘要。

商户侧客户标识。

商户自定义键值，最多 20 个键；键最长 40 字符，值为最长 200 字符的字符串。禁止放入卡号等敏感数据，平台会做检查并拒绝。

最近一次尝试所用卡的脱敏信息；尚无卡信息时为 null。

卡品牌。

卡号后四位。

创建时间。

确认支付成功的时间；未成功时为 null。

可发起新尝试的截止时间，创建时确定（默认创建后 30 分钟，平台可在 5–120 分钟之间调整，以本字段为准）。到期只关闭新的付款入口，不否定已提交的支付。

平台退款号。

对象版本，每次有效业务变更递增（状态、失败原因、退回金额）。比较版本来丢弃旧事件，不要按状态名排序。

原支付号。

商户退款号，同一商户同一环境内唯一。

退款本金，最小货币单位。

退款币种，继承原支付。

退款状态。

• pending_review：已受理，等待审核；保持资金占用
• processing：已批准并提交，或正在确认上游结果；保持占用
• succeeded：上游已确认退款成功；占用转为正式扣减
• failed：已明确退款未成功；解除占用
• rejected：审核驳回，未提交上游；解除占用
• canceled：提交上游前被有权限的人员取消；解除占用
• returned：曾确认成功的退款之后全部或部分资金被真实退回

退款原因。

退款成功后被真实退回的本金累计。

status 为 failed 或 rejected 时的原因，否则为 null。

失败原因码。

脱敏说明。

商户自定义键值，最多 20 个键；键最长 40 字符，值为最长 200 字符的字符串。禁止放入卡号等敏感数据，平台会做检查并拒绝。

受理时间。

进入 succeeded、failed、rejected 或 canceled 的时间；尚未结束时为 null。

收银会话号。

关联的 Payment。

收银会话状态。

• open：可提交支付
• completed：仅在关联 Payment 成功后出现
• expired：不再允许新提交；不代表关联支付失败

收银页地址，携带只绑定本会话的短时凭据，不含商户服务端密钥。只用于让付款人浏览器整页跳转：不要写入日志、分析工具或错误上报，也不要分享给他人。

会话失效时间，创建时确定：最长 30 分钟（平台可调短）且不超过订单剩余可支付期。过期后的只读期内（创建时确定，默认且最长 24 小时）付款人仍可用原链接查看会话与支付结果（只读，不能提交），之后链接失效。

支付结束后的商户返回地址。

付款人点击“返回商户”时的地址；点击它不等于撤销已提交的扣款。未提供时为 null。

收银页语言。

创建时间。

币种。

待结算：支付已成功，但到账、账期或对账条件未全部满足的净额；不可打款。

可结算：已满足释放条件且未被占用的金额；唯一可用于打款的桶。

保证金：按规则留存、等待释放的金额。

风险冻结：与具体风险处置或争议关联的冻结金额。

退款占用：被审核中或处理中退款占用的金额。

打款占用：被有效结算单占用、尚未确认打款完成的金额。

待追偿：平台因真实强制扣收等形成的对商户应收债权；不属于商户可用资金。

商户账面应付余额 = pending + available + reserve + risk_hold + refund_pending + payout_pending。

商户净头寸（仅展示用途）= book_payable - merchant_receivable，可为负；不能替代 available。

流水号。

记账类型，例如 payment_captured（支付成功入账）、refund_reserved（退款占用）、settlement_reserved（结算占用）、funds_released（资金释放）；须容忍新增取值。

来源业务对象类型，例如 payment、refund、dispute、settlement、payout、payout_return（退汇）、adjustment。

来源业务对象 ID。

余额桶：pending、available、reserve、risk_hold、refund_pending、payout_pending、merchant_receivable。

有符号金额，最小货币单位：正数增加该桶，负数减少该桶。

币种。

业务发生时间。

记账时间；迟到事实不伪造为按时到达。

关联的账务交易（凭证）号；桶间转移的两条流水共用同一个号。

结算单号。

结算币种。

账期起始业务日期（含），按商户结算业务时区。

账期结束业务日期（含）。

结算单状态。

• pending_review：系统已生成，待审核；已原子占用所选商户余额
• approved：复核通过，待执行
• rejected：审核拒绝；释放占用
• paying：已交付执行或打款结果未确定；保持占用
• paid：已复核打款成功
• failed：已明确本次没有成功付款；释放占用
• canceled：尚未对外执行且按权限撤销；释放占用
• returned：曾经成功的打款之后发生银行退汇

本结算单从 available 转入 payout_pending 的余额占用 S。

结算手续费 F，默认 0。

实际银行打款金额 = S - F。

结算单生成时固化的收款账户脱敏快照。

账户持有人。

银行名称。

账号后四位。

对应的打款记录；尚未执行时为 null。

生成时间。

来源类型，例如 payment、refund、adjustment。

来源对象 ID。

计入本结算单的有符号金额，币种同结算单。

打款记录号。

对应的结算单。

打款金额，最小货币单位。

币种。

打款状态：created、processing、unknown、succeeded、failed、canceled、returned。 unknown 时对应结算单保持 paying，不自动释放资金。

平台打款唯一参考号，不复用于新的转账。

交付执行时间；尚未执行时为 null。

经复核确认成功或失败的时间；尚未确认时为 null。

事件 ID，用于去重。

事件类型，取值见 webhooks.v1.yaml 的 EventType；客户端须容忍未知类型。

载荷的 API 版本。

事件创建时间；不能代替签名时间。

环境：test 为测试，live 为生产。测试与生产对象相互隔离。

商户号。

事件发生时的业务对象快照（Payment、Refund、Dispute 或 Settlement），只含商户有权查看的最小必要数据，含 id 与 version。