用途:该技能面向 Mercado Pago 通知接收端的实现,适用于 notification_url、x-signature、webhook、IPN、HMAC、retry 与通知类型相关场景;不用于创建支付(应使用 mp-checkout-online)或二维码通知(应使用 mp-instore)。
主要能力:覆盖 Webhooks(v2,JSON 格式、HMAC 签名,推荐新集成使用)与 IPN(旧版,基于查询参数、无签名,仍支持但不建议新项目使用)。支持的事件类型包括 Checkout Pro/Bricks/API 的 payment.created、payment.updated;订阅的 plan、subscription、invoice 的 created/updated;到店的 point_integration_wh;Marketplace 的 payment 事件;Orders API 的 order.created/updated;拒付的 chargeback.created/updated;配送的 delivery.created/updated。
使用方式:Webhook 可通过 Dashboard 全局配置,或在创建 preference 时设置 notification_url。notification_url 必须为 HTTPS、可公开访问、5 秒内返回 200/201、不得返回 3xx 重定向。处理流程为:接收 POST、先立即返回 200、校验 x-signature(HMAC-SHA256)、检查幂等、通过 API 获取资源详情、按状态处理业务逻辑、存储处理结果。签名头格式为 x-signature: ts=...,v1=...,manifest 为 id:{data.id};request-id:{x-request-id};ts:{ts};,末尾分号必需,比较需使用防时序攻击的方式。幂等建议用数据库唯一约束,开发期可用内存 Set 但不适用于生产。重试间隔依次为 5 分钟、45 分钟、6 小时、2 天、4 天,失败条件为非 2xx、超时超过 5 秒或端点不可达。IPN 格式为 GET .../ipn?topic=payment&id=...,无签名校验。本地开发可用 ngrok http <port> 暴露服务,并在 http://127.0.0.1:4040 重放。
限制与注意:x-signature 密钥与 Access Token 不同,需从 Dashboard 获取;data.id 有时为字符串;preference 中的 notification_url 会覆盖 Dashboard 配置;部分事件类型需在 Dashboard 订阅才会触发。具体各语言 SDK 代码示例、事件负载结构与错误码需通过 MCP 或官方文档获取,资料中未提供完整实现代码。