跳到主要内容
版本:当前指南

管理密钥、Webhook 与测试接入

当前可依赖的接入路径​

创建、查询、列出、关闭 Checkout 与查询可用收款方式的商户路由已确认,仍需核实账户及环境权限。当前以服务端查询确认支付。Webhook 端点管理与投递、逐笔付款明细和退款开放待确认;创建归集的执行支持另待确认。

后台密钥管理、事件中心、模拟器、沙盒重置及 IP 白名单的公开状态待确认,菜单可见或“模拟成功”不能作为正式能力证明。精确请求与最新开放状态请在开发者中心商业支付文档核对,不使用内部管理接口。

获取、存放与轮换凭据​

  1. 由有权限负责人通过已核实的开通流程取得对应环境凭据;后台若提供密钥创建,逐项核对权限与用途后再建。
  2. 将完整密钥直接保存到服务端受控配置,应用前端、客户页面、源码仓库和日志不留副本。
  3. 测试与正式环境的密钥、资源 ID、通知端点和数据分开管理,不靠密钥前缀猜测权限。
  4. 如需轮换,先确认实际过渡及撤销规则,准备新凭据并验证必要查询/创建权限,再切换业务服务、观察未决订单,最后按批准安排撤销旧密钥。
  5. 已疑似泄露时优先按应急安排撤销与恢复,清点影响范围;不假定旧密钥还有固定时长可用。记录操作而不记录完整密钥。

当前先用查询确认​

创建前保存订单、付款尝试、请求参数与幂等键;创建后保存真实 Checkout ID 和 URL。服务端只查询本商户已绑定的资源,核对订单、金额、币种、主状态及异常,再按订单保证只履约一次。

查询超时、限流或服务重启时保留未知结果并恢复原记录;使用有界频率与退避,不能靠前端循环请求或新建收款替代恢复。具体判断见订单与异常处理。

Webhook 确认开放后再启用​

  1. 先确认目标环境和账户支持端点管理及实际投递,再确认签名、事件和重试规则。
  2. 按当前契约配置服务端通知 URL;正式环境使用 HTTPS,安全保存该端点完整 secret,不能混用 API Key。
  3. 技术人员在解析 JSON 前取得原始请求体,按当前商业支付文档验证 Invisi-Signature。不要自动回退使用其他签名头。
  4. 验签后持久化事件并按商户、环境及事件 ID 去重;可靠保存后返回成功,异步查询相关资源再处理业务。
  5. 保留 Checkout 查询补偿及订单级履约去重。事件重复、乱序或延迟不能造成重复发货;通知投递成功不等于业务处理完成。

通知签名失败时检查端点 secret、原始字节、签名头和服务器时钟;事件缺失时先查询支付事实,不能把“没收到通知”解释为未付款。

测试与上线验收​

在获准测试环境至少演练:正常支付、重复点击、创建超时、查询失败、服务重启、同订单多 Checkout 成功、迟到资金、少付/多付以及伪造前端成功。预期都是事实可恢复、订单只履约一次、资金异常有人跟进。

仅对已开放的能力追加 Webhook 验签及重复乱序测试、退款签名与额度占用测试、归集拒签和发送后状态恢复测试。离线或模拟器通过不证明真实端到端可用。测试是否上链、资产是否有真实价值应以测试环境说明为准,不假定沙盒永不动资金。

排障提供环境、订单/Checkout ID、发生时间、可用 Request-Id 和脱敏错误;不要发送 Authorization 头、完整密钥或含访问令牌的客户链接。

使用事件中心和请求日志定位异常​

后台事件中心、请求日志和重发工具的开放状态待确认。仅在账户提供对应功能时:

  1. 固定账户、环境、时间及业务资源 ID,按当前提供的事件类型、事件 ID 或关联对象筛选,确认没有查错环境或被时间筛选隐藏。
  2. 打开详情,核对事件时间、类型、关联资源及实际提供的版本信息,再进入原订单或资金任务查看当前结果。较早事件不能覆盖较新资源状态。
  3. 若提供投递详情,分别检查端点、尝试记录、响应和错误。事件已生成不代表已投递;HTTP 成功不代表商户异步业务处理完成。
  4. 只有通知投递及重发功能均已确认开放,且接收端具备验签与业务去重时,才按实际按钮重发并核对结果。重发是通知恢复,不是重新收款、退款或重新履约。
  5. 若请求日志可用,按请求编号和资源关联查请求结果;查阅或导出前确认凭据已脱敏,保留必要证据后再按实际权限处理日志,不先清空排障依据。

没有事件或日志时,先通过已开放的 Checkout 查询恢复支付事实,再核实筛选、权限、日志范围与工具状态,不把空列表视为未付款,也不使用未经确认的事件名称或载荷格式接入。

运行后台测试工具前​

只有账户实际提供相应工具时,先确认测试环境、凭据、测试资产是否有价值,以及模拟是否会生成真实任务、发生链上交易或发送真实通知。Checkout 预览只验证展示,模拟支付只覆盖工具明确说明的行为,两者都不能替代真实目标环境的端到端验收。

若提供通知模拟,选择获准测试端点及当前支持的事件结构,避免向正式客户系统误发;检查投递、验签、持久化、资源查询与幂等处理各环节。自定义数据格式错误先按页面纠正,不把模拟载荷当成正式契约。超时先查原测试任务,批量测试后按订单检查重复交付与未决异常。不要为重置演练而清除仍需复核的订单或日志。