授权、截止与恢复
会话访问、资金执行和业务领取是不同的权限边界。恢复时先找回原 Session 与 Request,再判断交易事实,避免一次网络超时变成第二次付款。
三层授权
商户 API Key 保留在业务服务端,用于创建 Checkout、查询所属会话及实现方允许的访问能力换发。Session Token 是绑定一个 Session 的不透明 Bearer,供钱包确认、读取 Request、可选提交 Credential 和查询。钱包/Core 授权才允许资金执行。Token 不证明买家身份,交易哈希也不赋予商品领取权。
从受信交付获得原 sessionUrl,后续 links 和 Location 必须与它同一 HTTPS origin,操作 method 必须匹配;不要向其他来源转发 Token 或跟随带凭据请求的重定向。checkoutUrl 的 fragment 使用分别编码的 sessionUrl 与 token,读取后清除地址栏 fragment;API 调用通过 Authorization Bearer 发送。不要把 Token 放进 API URL、日志或 localStorage。
五个独立时间
| 时间 | 使用方式 |
|---|---|
| Session.expiresAt | 首次确认必须严格早于该时间 |
| Request.createdAt | 首次成功确认并保存的时间 |
| Request.expiresAt | 执行、finalized 验证与原子核销的截止 |
| credit.expiresAt | 授信长期有效期 |
| Token 有效期 | 访问权限,不改变业务截止或链上事实 |
例如 Session 09:55 到期,09:54 确认且执行窗口为 10 分钟,则 Request 10:04 到期。09:55 不终止已确认的执行。重试、换 Token、换设备或换 Broadcaster 都不刷新 10:04。09:59 上链但 10:05 才完成 finalized 与核销,不能正常成功。离线或 RPC 不可用不延长窗口。
状态与恢复动作
| 状态或结果 | 处理 |
|---|---|
| open | 尚未确认;确认前显示并核对选项 |
| requires_action | 已有唯一 Request;可能仍有在途交易,不能据此安全重付 |
| processing | 已观察到匹配的规范链操作,继续等最终性与核销 |
| succeeded | 读取不可变 receipt 与当前 evidenceStatus,幂等履约 |
| failed | 本次请求已结束;原交易事实继续核对,不能恢复为 succeeded |
| Credential 202 | 仅提示已受理;继续读取原 sessionUrl |
创建/确认响应丢失时复用原 Idempotency-Key 与输入,取回原对象。相同键不同输入返回 409;换确认键不能突破一个 Session 一个 Request 的约束。读取 Request 状态已是 processing/succeeded/failed 时,不自动启动新的钱包执行。
超时、索引落后和广播响应丢失都不能证明未付款。先恢复并查询原交易;只有原操作已确定失败/失效、排除其他在途交易且仍在截止内,才考虑按同一要求重试。旧操作未知时新建 Checkout 可能重复付款或授信。
Token 失效返回 401;通过实现方认证的商户流程取得原会话的新访问能力。换发不改变 Request;终态恢复访问不能重新确认。400 表示无效输入,403 操作不允许,404 对象不存在或越权,409 状态/幂等冲突,429 应退避,503 表示依赖不可用。retryable 指重试原 HTTP 操作,不是重新付款;遵循 Retry-After。
回执健康与异常
成功 receipt 内容不变;当前 evidenceStatus 可以为 confirmed、reconciling 或 disputed。后两者需要暂停新增依赖该证据的业务并核对补偿。暂时 RPC 不可用本身不抹去历史回执,历史授信回执也不能代替当前可用性查询。
迟到付款、额外到账和异常授信独立记录,exceptionSummary.count 与 unresolvedCount 显示数量。failed 后发现事实不生成正常成功 receipt;异常计数不代表已退款或撤销。后续退款、人工处理及授信撤销另行完成。商户以服务来源、sessionId 绑定原订单和调用者,并在自己的数据库保证只履约一次。