SuperAPI AI 工具集

paypro-global-webhooks

测试与质量

查看项目

更新于 10-15 22:14

技能介绍

用途:本技能用于接收并验证 PayPro Global 的 Webhook(官方称 IPN,即时支付通知)。当订单或订阅事件发生时,PayPro Global 会向你配置的 IPN URL 发送 HTTP POST,请求体格式为 application/x-www-form-urlencoded(非 JSON)。其验证方式是专用的,既不是请求头中的 HMAC,也不是 Standard Webhooks。

主要能力:验证含三层,建议尽可能全部启用。一是 IP 白名单,请求仅来自固定 IP:IPv4 198.199.123.239、157.230.8.40,IPv6 2604:a880:400:d0::1843:7001、2604:a880:400:d1::b6c:c001。二是 SIGNATURE(SHA256 十六进制),对七个字段值按固定顺序拼接后计算:ORDER_ID + ORDER_STATUS + ORDER_TOTAL_AMOUNT + CUSTOMER_EMAIL + VALIDATION_KEY + TEST_MODE + IPN_TYPE_NAME。三是 HASH(MD5),真实订单为 ORDER_ID + SecretKey 的 MD5,测试订单为 MD5("1")。VALIDATION_KEY 与 SecretKey 是两个不同的密钥,均位于 Store Settings → General Settings → Integration,混淆二者是最常见的验证错误。签名覆盖的是特定字段值而非原始请求体,因此需先解析表单再计算。

使用方式:服务端重新计算并做时间安全比较。事件名通过 IPN_TYPE_NAME 字段传递,常见事件包括 OrderCharged、OrderRefunded、OrderPartiallyRefunded、OrderChargedBack、OrderChargedBackWon、OrderDeclined、SubscriptionChargeSucceed(拼写非 Succeeded)、SubscriptionChargeFailed、SubscriptionRenewed、SubscriptionSuspended、SubscriptionTerminated、SubscriptionFinished。环境变量为 PAYPRO_VALIDATION_KEY(用于 SIGNATURE)与 PAYPRO_SECRET_KEY(用于 HASH)。本地开发可运行:npx hookdeck-cli listen 3000 paypro-global --path /webhooks/paypro-global。完整处理器示例见 examples/express/、examples/nextjs/、examples/fastapi/,另有 references/overview.md、references/setup.md、references/verification.md 参考。

适用场景与限制:适用于电商、SaaS 订阅等需要处理 PayPro Global 支付与订阅事件的后端集成。PayPro Global 对非 200 响应每 30 分钟重试一次,最多 3 次,因此处理器应保证幂等,建议按“先验证、再解析、后幂等处理”的顺序实现,并结合重试与错误处理模式。生成文件时应注明来源注释。其他未在资料中说明的功能、定价或平台信息暂未提供。