结算生命周期
结算生命周期
本节规范化描述 AP2 支付意图在结算过程中的状态流转、事件通知以及必须保存的审计资料。
状态流转
┌───────────┐
│ draft │
└─────┬─────┘
▼
┌───────────┐
│ pending │◀─────────────┐
└─────┬─────┘ │
▼ │
┌───────────┐ │
│authorized │ │
└─┬─────┬───┘ │
escrow ▼ ▼ capture │
┌───────────┐ ┌───────────┐ │
│ escrowed │ │ captured │ │
└─────┬─────┘ └─────┬─────┘ │
▼ release ▼ │
┌───────────┐ ┌───────────┐ │
│ released │ │ settled │ │
└───────────┘ └───────────┘ │
▲ │
│ refund │
┌───────────┐ │
│ refunded │──────────────┘
└───────────┘异常会进入 rejected、failed、expired 等终止状态。每一次状态变更都会触发 payment.* 事件。
事件列表
| 事件 | 触发时机 | 说明 |
|---|---|---|
payment.pending | 卖家接受草稿并提交策略校验 | payload 包含最新的 policy trace |
payment.authorized | 策略通过且资金被预授权/托管 | 返回授权引用（authorization reference） |
payment.escrowed | 资金成功进入托管账户 | 包含托管账户 ID |
payment.captured | 即时捕获或分阶段捕获完成 | 描述捕获金额与币种 |
payment.released | 满足释放条件后从托管释放 | 指明触发条件及操作者 |
payment.settled | 控制平面存档结算凭证 | 提供凭证 ID |
payment.refund.pending | 创建退款意图 | 引用原始 paymentIntentId |
payment.refunded | 退款完成结算 | 包含退款凭证 ID |
payment.failed | 结算轨道错误 / 超时 / 策略回滚 | 提供 error.code 与补救建议 |
事件可通过 SSE 或 Webhook 推送。Webhook 与 SSE payload 结构一致，额外包含用于幂等处理的 eventId 头。
必须存档的资料
商家与买家需至少保存：
- 所有版本的支付意图（含签名）。
- 结算轨道返回的授权引用。
- 结算凭证（
settlement-proof.json）。 - 策略轨迹（规则执行结果）。
- 发生争议时的完整证据包。
在受监管辖区，资料保留期限至少 7 年。
Webhook 安全
- 通过
POST /v1/ap2/webhooks注册回调地址，并提交 DID 与公钥。 - 控制平面使用 HTTP Message Signatures（key ID
ap2-control-plane）对请求签名，处理前需验证签名与Digest头。 - 返回
2xx表示成功，非 2xx 将触发最多 8 次指数退避重试。
对账接口
| 接口 | 功能描述 |
|---|---|
GET /v1/ap2/statements?date=YYYY-MM-DD | 获取指定日期的日结报表（含意图、捕获、退款列表） |
GET /v1/ap2/ledger-entries/{accountId} | 分页查询账户（托管 / 运营）账务变动 |
GET /v1/ap2/settlement-proofs/{id} | 拉取标准化结算凭证 |
GET /v1/ap2/audit-log?intentId=... | 查看策略决策与人工操作的顺序日志 |
建议将日结与结算凭证交叉核对，以发现遗漏事件。控制平面保证结算凭证事件 恰好一次 送达，其余事件为 至少一次。
争议处理
争议状态包括 opened、evidence_requested、escalated、resolved。当争议升级时，资金会自动重新托管直至结案。由争议触发的退款会附带 reasonCodes（如 damaged_goods、service_not_delivered、chargeback）。提交退款时带上争议证据 ID 可加速自动化裁决。
更多轨道特性请参见支付轨道指南。
