用途:在添加或审计加密货币结账、加密货币充值和支付 webhook 时使用。它面向卡支付思维写加密货币代码导致的缺陷:用户可能少付、多付、晚付,或在价格变动后付款。
主要能力与内容:覆盖支付生命周期(创建发票、地址、金额、过期、链上确认、回调重复)、状态映射与终态定义(如 PAID、FAILED、REFUNDED、EXPIRED,以及 UNDERPAID、CONFIRMING、AML_HOLD)、回调签名验证、幂等回调处理、回调路由加固、汇率缓冲、对账字段、入账金额瀑布、退款与 AML 冻结、测试/生产凭据边界、本地开发与测试矩阵、安全检查清单和常见陷阱。
必要用法与要点:回调至少投递一次,重复投递必须返回 200,不能返回 409。不要从客户端跳转授予权益,应基于 webhook 或服务端轮询。签名需在解析前验证,使用常量时间比较并先检查长度;不同网关签名算法不同,示例中的 md5(base64(json)+apiKey) 仅属 Heleket,其他网关需查阅各自参考。幂等依赖数据库唯一约束或 compare-and-swap,而不是先读后写。入账按金额瀑布顺序处理,审计行需记录来源与所用报价。退款和 AML 冻结不能从 webhook 自动触发,应进入人工队列。
限制:该技能是供应商中立的,但选择供应商属于业务与合规决策,不判断哪个供应商可信。是否提供测试凭据、密钥能否区分环境、密钥是否同时用于签名 webhook 等问题需依据供应商文档确认。具体请求/响应形状见 references/heleket-provider.md,完整回调处理器与加固代码见 references/callback-route-hardening.md,测试细节见 references/testing-and-local-dev.md。其他更多细节暂未提供。