# MoonPay Commerce：核对Pay Link成功事件、验签和重投

整理：链小知（AI 辅助）
资料核对日期：2026-10-14
引用地址：https://lianxiaozhi.com/tools/guides/moonpay-commerce-paylink-webhook-signature-replay-check
难度：进阶
核验方式：官方文档整理，未执行真实账户操作

固定事件作用域与交易ID，避免把重复通知或Deposit告警当成新增订单收款。

## 使用工具
- [MoonPay Commerce](https://lianxiaozhi.com/tools/moonpay-commerce) · [官方入口](https://moonpay.hel.io/)

## 前置条件
- 准备已有且脱敏的订单、请求或回执记录；没有实际记录时仅按文档列出待核字段。
- 本教程依据公开资料，不登录、申请密钥、调用业务API、创建收款或执行退款。

## 1. 固定Pay Link事件与作用域

Pay Link一次性付款成功通知的订阅类型为REGULAR_TRANSACTION或ALL，实际payload的event为CREATED。省略paylinkId表示账户全局，指定则限该Pay Link。

Deposit与订阅是其他事件类别；不用DEPOSIT_TX_*、最低额或审核告警判断Pay Link已收款。

核对结果：订阅类型、CREATED及全局/单链接作用域对应。
依据：[MoonPay Commerce：Pay Link成功事件与作用域](https://docs.hel.io/reference/webhook/paylink-transaction/overview.md)
依据：[MoonPay Commerce：各类Webhook及限定请求头](https://docs.hel.io/reference/webhook/overview.md)

## 2. 先验Bearer和原正文签名

官方Webhook要求Authorization: Bearer <sharedToken>与X-Signature。用原请求正文在JSON解析前计算sharedToken为键的HMAC-SHA256十六进制摘要，使用恒定时间比较。

sharedToken在创建时只返回一次；本文不创建、不读取或保存实际凭据，仅核已有脱敏验签结果。认证缺失或验签失败则事件不作为订单完成依据。

核对结果：Bearer检查与原正文HMAC检查都有结果或明确未验证。
依据：[MoonPay Commerce：Webhook配置、原始正文验签与重投](https://docs.hel.io/docs/webhooks.md)
依据：[MoonPay Commerce：各类Webhook及限定请求头](https://docs.hel.io/reference/webhook/overview.md)

## 3. 按交易字段关联订单并防重复

CREATED载荷的transactionObject含id、paylinkId和meta.transactionSignature/transactionStatus；transaction是同一数据的JSON字符串。chargeToken关联买方Charge页面。

重投可能重复同一交易。应用处理时按已核实的交易id及订单关联避免重复履约；这是对交易字段与重投机制的处理建议，不声称官方提供全平台exactly-once。X-Webhook-Delivery-Id与X-Transaction-Id在当前参考页限定Deposit通知，不能假定Pay Link也有。

核对结果：重投与新交易已分开；没有限定头时不用猜测头值去重。
依据：[MoonPay Commerce：Pay Link CREATED交易字段](https://docs.hel.io/reference/webhook/paylink-transaction/payloads.md)
依据：[MoonPay Commerce：Webhook配置、原始正文验签与重投](https://docs.hel.io/docs/webhooks.md)
依据：[MoonPay Commerce：各类Webhook及限定请求头](https://docs.hel.io/reference/webhook/overview.md)

## 4. 对照通知送达和真实收款

仪表盘Developers → Webhooks可核事件日志、送达状态及时间，官方自动重投最多12次，达到上限可从日志手动replay。本文只核已有记录，不重放实际通知。

送达失败属于通知问题，不能据此宣称付款失败；结合Charge的paylinkTx或signature交易记录核收款。无法取得对应交易时保留未知。

核对结果：日志送达、重投次数和底层交易三项分列。
依据：[MoonPay Commerce：Webhook配置、原始正文验签与重投](https://docs.hel.io/docs/webhooks.md)
依据：[MoonPay Commerce：按chargeId查询paylinkTx](https://docs.hel.io/reference/charge/retrieve.md)
依据：[MoonPay Commerce：按链上signature查询交易](https://docs.hel.io/reference/transactions/retrieve-by-signature.md)

## 常见错误
- 本文只核Pay Link成功事件；Deposit共享请求头及配额告警不扩展到所有Webhook。
- 通知处理建议不保证不丢消息，也不代替实际收款和对账验收。

## 完成检查
- 形成订单、资源ID、金额、状态与未验证项的对照；保留失败原文。

## 相关知识

## 官方依据
- [MoonPay Commerce：Pay Link成功事件与作用域](https://docs.hel.io/reference/webhook/paylink-transaction/overview.md)
- [MoonPay Commerce：各类Webhook及限定请求头](https://docs.hel.io/reference/webhook/overview.md)
- [MoonPay Commerce：Webhook配置、原始正文验签与重投](https://docs.hel.io/docs/webhooks.md)
- [MoonPay Commerce：Pay Link CREATED交易字段](https://docs.hel.io/reference/webhook/paylink-transaction/payloads.md)
- [MoonPay Commerce：按chargeId查询paylinkTx](https://docs.hel.io/reference/charge/retrieve.md)
- [MoonPay Commerce：按链上signature查询交易](https://docs.hel.io/reference/transactions/retrieve-by-signature.md)