Spring Boot中Mercado Pago通知接口POST请求不支持问题排查

排查路径匹配一致性 #

先确认Controller类和方法的路径组合是否和Security放行规则完全匹配：

• 若通知接口所在Controller类带有@RequestMapping("/pagomercadopago")，方法上的@PostMapping("/notificaciones")完整路径为/pagomercadopago/notificaciones，和Security配置的/pagomercadopago/**匹配，这部分没问题；
• 检查是否存在大小写错误，比如Mercado Pago通知地址全小写，但你的路径包含大写字母，导致匹配失败；
• 确认Controller方法没有额外添加多余路径前缀。

关闭该路径的CSRF防护 #

Spring Security默认开启CSRF校验，Mercado Pago的通知请求不会携带CSRF Token，这会直接拦截POST请求并返回"方法不支持"。在Security配置中针对该路径关闭CSRF：

@Override
protected void configure(HttpSecurity http) throws Exception {
    http
        // 其他配置项
        .csrf(csrf -> csrf
            .ignoringAntMatchers("/pagomercadopago/**")
        )
        .authorizeRequests(auth -> auth
            .antMatchers("/pagomercadopago/**").permitAll()
            // 其他授权规则
        );
}

调整Security规则顺序 #

Security规则是从上到下匹配，如果permitAll()规则放在anyRequest().authenticated()这类拦截规则之后，会导致前置规则先拦截请求。确保放行规则放在所有需要认证的规则之前：

@Override
protected void configure(HttpSecurity http) throws Exception {
    http
        .csrf(csrf -> csrf.ignoringAntMatchers("/pagomercadopago/**"))
        .authorizeRequests(auth -> auth
            .antMatchers("/pagomercadopago/**").permitAll() // 优先放行目标路径
            .anyRequest().authenticated() // 再设置其他请求的认证要求
        );
}

修正接口参数接收逻辑 #

Mercado Pago的通知是JSON格式POST请求，需确保Controller方法正确接收请求体：

@RestController
@RequestMapping("/pagomercadopago")
public class MercadoPagoController {

    @PostMapping("/notificaciones")
    public ResponseEntity<String> handleNotification(@RequestBody Map<String, Object> notification) {
        // 处理通知逻辑
        return ResponseEntity.ok("OK");
    }
}

• 必须添加@RequestBody注解接收JSON请求体，否则Spring会默认认为请求需要表单参数，无法匹配到该方法，进而返回请求方法不支持。

排查自定义过滤器/拦截器干扰 #

如果项目中有自定义过滤器或拦截器，检查它们是否拦截了/pagomercadopago/notificaciones的POST请求。比如部分拦截器会校验请求头、参数，不符合条件就直接返回，导致请求无法到达Controller。

本地测试验证 #

用Postman直接发送POST请求到http://localhost:端口/pagomercadopago/notificaciones，携带JSON请求体，确认接口能正常响应。如果本地测试正常，再排查Mercado Pago模拟工具的网络或配置问题。

内容的提问来源于stack exchange，提问作者Richard Figueroa