接收支付通知
通知端点管理与商户 Webhook 投递的开放状态待确认。不要让订单履约依赖它们。当前使用服务端 Checkout 查询/轮询确认支付;启用通知前查阅 API 可用性。确认账户与环境支持通知后,再启用下方的接收流程。
Webhook 用于触发资源查询,不应直接成为履约指令。投递开放后,仍保留查询对账,避免延迟或遗漏通知导致订单无人处理。完整参考定义端点属性、管理请求、错误、事件字段、签名与重试。
当前通过查询确认支付
创建 Checkout 时,将其 ID 与商户订单关联保存在服务端。查询该 Checkout 的当前状态,核对预期订单、金额与币种。浏览器回跳或客户成功页面不能代替服务端确认;只有权威资源达到接受的成功状态,才执行幂等履约。
下面需要 Bash/zsh 和 curl。将 PAYMENTS_API_ORIGIN 设为账户对应文档环境的 HTTPS origin,末尾不带斜杠;INVISI_API_KEY 为该环境的服务端 API Key;CHECKOUT_ID 为创建返回的原 Checkout ID。不要记录含密钥的请求头。
: "${PAYMENTS_API_ORIGIN:?Set the documented merchant API HTTPS origin}"
: "${INVISI_API_KEY:?Set the server-side key for that environment}"
: "${CHECKOUT_ID:?Set the original Checkout ID}"
curl --fail-with-body --silent --show-error \
"${PAYMENTS_API_ORIGIN}/v1/checkouts/${CHECKOUT_ID}" \
-H "Authorization: Bearer ${INVISI_API_KEY}"
准确字段和状态变化见 Checkout API。使用有界退避安排服务端轮询,HTTP 错误或待处理状态不能视为支付成功。服务恢复后查询保存的未完成 Checkout,并分页列出收款补齐遗漏。查询得到的资源状态可能比早先通知更新。
准备持久化事件收件箱
账户与环境的 Webhook 能力开放后,按端点契约注册公开可访问的服务端 URL。正式环境要求 HTTPS。每个端点使用独立 secret;创建后将完整字符串安全保存在服务端,查询和更新不会返回。创建请求结果不确定时,使用原幂等键和不变参数重试。
预期接收流程如下:
- 在 JSON 中间件改写前收集有大小上限的原始请求体。读取文档规定的
Invisi-Signature,使用该端点完整 secret 验签。 - 解析已认证的请求体并校验事件 envelope。Thin Event 包含
id、type、related_object.id、related_object.type、created_at。 - 在持久化事务中写入事件收件箱,以商户/环境及事件
id唯一约束去重,保留异步处理所需数据。内存 Set 无法跨崩溃保存或协调副本。已经可靠保存的重复事件视为已接收。 - 可靠接收后尽快返回
2xx,重复事件也一样。持久化失败不要确认成功;资源查询与履约异步进行。 - Worker 使用正确账户的服务端凭证查询关联资源,核对订单映射与当前状态,再执行幂等履约或退款记账。后续处理失败通过商户自己的持久化工作队列重试。
事件去重与业务幂等保护不同边界:多个不同事件可能指向同一订单,轮询也可能与通知并发。需要在订单/付款层面以持久化状态及履约系统的幂等能力保证业务动作唯一。本文不提供数据库收件箱、队列或真实履约实现。
对精确原始字节验签
下载无第三方依赖的 Node.js 验签示例,要求 Node.js 20 或更高版本,仅使用内置 node:crypto。
传入原始请求体 Buffer、Invisi-Signature 字符串和端点 secret。函数解析 t=<unix_seconds>,v1=<lowercase_hex>,对精确的 t + "." + raw_body 使用 HMAC-SHA256,以 timingSafeEqual 比较等长签名,并仅接受当前时间前后 300 秒内的投递。组件格式错误或重复、未知字段、非法 hex、不安全时间戳、缺少 secret、已解析的请求体、签名不匹配均返回失败。接收端应读取 Invisi-Signature;不要将其他头名作为自动兼容回退。
secret 必须使用完整字符串,包括可能存在的 whsec_ 前缀,不做解码。JSON 重新序列化会改变签名字节。验签失败时不要保存或处理事件,保持服务器时钟同步。函数只验证真实性与时效;事件校验、防重放去重、可靠接收和业务授权仍由应用负责。
下面是框架已收集有界原始 Buffer 后的局部接入片段。变量来自 HTTP 请求及服务端密钥存储,不能先用全局 JSON parser 改写请求体:
import { verifyWebhook } from './verify-webhook.mjs';
// rawBody: Buffer; signatureHeader: request's Invisi-Signature value;
// endpointSecret: complete secret from secure server configuration.
if (!verifyWebhook({ rawBody, signatureHeader, secret: endpointSecret })) {
// Reject this HTTP request without accepting the event.
throw new Error('Webhook verification failed');
}
const event = JSON.parse(rawBody.toString('utf8'));
// Next: validate envelope -> durable inbox insert -> 2xx -> async worker.
离线验证签名样例
将下载文件保存为独立工作目录下的 verify-webhook.mjs,在该目录用 Node.js 20+ 执行以下命令。它使用明确公开的合成 secret 与固定时钟,不发送任何网络请求,依次输出 true 和 false。真实接收端不能使用样例 secret 或固定时钟。
node --input-type=module <<'JS'
import { verifyWebhook } from './verify-webhook.mjs';
const rawBody = Buffer.from('{"id":"evt_local","type":"checkout.succeeded","related_object":{"id":"checkout_local","type":"checkout"},"created_at":"2027-01-15T08:00:00Z"}\n');
const fixture = {
rawBody,
secret: 'whsec_local_fixture_only',
signatureHeader: 't=1800000000,v1=9517bb307d48742fdb59ad626cb4c64f6bb218438a50e16cfbf874924050ba48',
nowSeconds: 1800000000,
};
console.log(verifyWebhook(fixture));
console.log(verifyWebhook({ ...fixture, rawBody: Buffer.from('{}') }));
JS
处理重试、延迟与遗漏
文档契约规定每次投递超时为 5 秒,连接失败、超时、非 2xx 和重定向触发重试,且不跟随重定向。重试间隔逐步增加,最长至首次投递后 3 天。端点停用或删除会停止自动投递,但在途请求仍可能到达。启用投递前,确认目标环境支持上述签名与重试规则。
同一事件重投保留 ID 与请求体,更新投递时间戳和签名。较早的 created_at 可以配合新的投递签名出现:按投递时间拒绝过期签名,按事件 ID 去重,不应只因事件创建时间早而拒绝合法延迟通知。事件可能乱序,不能把到达顺序当作资源状态顺序。
根据 related_object.type 选择 GET /v1/checkouts/{id} 或待开放的退款 API。不能把退款事件当作 Checkout,也不能因创建退款请求就判定退款完成。投递失败不会改变收款/退款状态。返回 2xx 后 worker 处理失败由商户自行重试,平台已停止该事件自动重投。
开放正式投递前
确认目标账户与环境确实开放端点管理及投递,并端到端核验文档规定的头名、签名与重试行为。演练非法 body/签名、两个方向的时钟偏差、重复、乱序、接收端停机、持久化失败、worker 失败,以及通过 Checkout 轮询恢复。测试/正式环境的 secret、Key、收件箱命名空间与资源 ID 分开管理。监控最早未处理事件和待处理订单年龄,保留查询补偿的运维路径。