Recursos para IA

Configurar notificações de pagamento

As notificações Webhooks, também conhecidas como devoluções de chamada web, são mensagens HTTP que o Mercado Pago envia ao seu servidor quando ocorre um evento específico na sua integração. Em vez de seu sistema realizar consultas constantes para verificar atualizações, os Webhooks transmitem os dados automaticamente por meio de uma solicitação HTTPS POST.

Configurar Webhooks

A seguir, apresentamos um passo a passo para receber notificações em integrações com Checkout Pro. Uma vez configuradas, as notificações Webhook serão enviadas sempre que ocorrer alguma atualização sobre o tópico reportado, incluindo criação e atualização de orders e processamento de transações.

Acesse Integrações e selecione a aplicação integrada com Checkout Pro para a qual deseja ativar as notificações.

Visão geral de Integrações

No menu lateral, selecione Configuração de Webhooks.
No switch Teste / Produção da parte superior, selecione Teste e insira a URL HTTPS para receber notificações de teste. Se quiser configurar notificações de produção, selecione Produção e insira a URL HTTPS de produção.

Caso seja necessário identificar múltiplas contas, adicione o parâmetro ?client=(nomedovendedor) ao final da URL indicada para identificar os vendedores.

Selecione o evento Order (Mercado Pago) para receber notificações, que serão enviadas em formato JSON através de um HTTPS POST para a URL configurada para o ambiente correspondente.

Configuração de Webhooks do Checkout Pro com Orders

Por fim, clique em Salvar. Isso gerará uma assinatura secreta exclusiva para a aplicação, que permitirá validar a autenticidade das notificações recebidas e confirmar que foram enviadas pelo Mercado Pago. A assinatura não tem prazo de validade e sua renovação periódica não é obrigatória, embora seja recomendada. Para renová-la, clique em Redefinir assinatura secreta.

Simular a recepção da notificação

Para garantir que as notificações sejam configuradas corretamente, é necessário simular sua recepção. Para isso, siga o passo a passo abaixo.

Após configurar seus Webhooks, clique em Simular notificação.
Na tela de simulação, selecione a URL que será testada.
Em seguida, selecione o tipo de evento e insira a identificação que será enviada no corpo da notificação (Data ID).

Simulação de uma notificação Webhook

Por fim, clique em Enviar teste para verificar a solicitação, a resposta fornecida pelo servidor e a descrição do evento. Você receberá uma resposta conforme o exemplo abaixo, que representa o body da notificação recebida em seu servidor.

json
{
  "action": "order.processed",
  "api_version": "v1",
  "application_id": "5852534070406015",
  "data": {
    "currency_id": "CLP",
    "external_reference": "ext_ref_manual_full_test",
    "id": "ORDTST01M4V4VSXCTN8ZN1FJ02KKMFGE",
    "items": [
      {
        "external_code": "ITEM-001",
        "quantity": 1
      }
    ],
    "status": "processed",
    "status_detail": "accredited",
    "total_amount": "4500",
    "total_paid_amount": "4500",
    "transactions": {
      "payments": [
        {
          "amount": "4500",
          "attempt_number": 1,
          "id": "PAY01M4V4XX5CXZ6KF1P3DEMX83VY",
          "paid_amount": "4500",
          "payment_method": {
            "id": "master",
            "installments": 1,
            "type": "credit_card"
          },
          "reference": {
            "id": "183961436800"
          },
          "status": "processed",
          "status_detail": "accredited"
        }
      ]
    },
    "type": "online",
    "version": 1
  },
  "date_created": "2026-10-13T17:28:26.540980984Z",
  "live_mode": false,
  "type": "order",
  "user_id": "3431137176"
}

Se por algum motivo você não estiver recebendo as notificações do Mercado Pago, alternativamente pode obter as informações sobre o recurso que não foi notificado enviando uma solicitação ao endpoint /v1/orders/{order_id}GET. O uso deste método não é recomendado, por isso sugerimos adicionalmente entrar em contato com Suporte.

Monitorar notificações

Para consultar o funcionamento das notificações, abra a aplicação e, em Início, selecione a aba Webhooks. Utilize o switch Teste / Produção para consultar as notificações do ambiente selecionado.

Nessa tela, você pode filtrar os envios, consultar data, status da entrega, ação, evento e ID do recurso, e revisar as métricas de entrega e tempo de resposta. Em Teste, os dados são atualizados em tempo real.

Monitoramento de notificações Webhook

Para consultar os dados do envio e o corpo da notificação, selecione uma notificação da tabela para abrir os detalhes.

Detalhes de uma notificação Webhook

Para reenviar uma ou mais notificações, selecione-as na tabela e clique em Reenviar notificações.

Validar a origem da notificação

A validação da origem de uma notificação é fundamental para assegurar a segurança e a autenticidade das informações recebidas. Este processo ajuda a prevenir fraudes e garante que somente as notificações legítimas sejam processadas.

O Mercado Pago enviará ao seu servidor uma notificação similar ao exemplo abaixo para um alerta do tema order. Neste exemplo, está incluída a notificação completa, que contém os query params, o body e o header da notificação.

Query params: São parâmetros de consulta que acompanham a URL. No exemplo, temos data.id=ORD01JQ4S4KY8HWQ6NA5PXB65B3D3 e type=order.
Body: O corpo da notificação contém informações detalhadas sobre o evento, como action, api_version, application_id, date_created, id, live_mode, type, user_id e data.
Header: O cabeçalho contém metadados importantes, incluindo a assinatura secreta da notificação x-signature.

http
POST /test?data.id=ORD01JQ4S4KY8HWQ6NA5PXB65B3D3&type=order HTTP/1.1
Host: prueba.requestcatcher.com
Accept: */*
Accept-Encoding: *
Connection: keep-alive
Content-Length: 177
Content-Type: application/json
Newrelic: eyJ2IjpbMCwxXSwiZCI6eyJ0eSI6IkFwcCIsImFjIjoiOTg5NTg2IiwiYXAiOiI5NjA2MzYwOTQiLCJ0eCI6ImY4MzljZjg4ODg2MGRmZTIiLCJ0ciI6ImMwOGMwZGMyMjNjZDY2YjJkZWQwMjUxZmYxNWNiNGQ1IiwicHIiOjEuMjUwMzIsInNhIjp0cnVlLCJ0aSI6MTc0Mjg0MjU4MDE2NCwiaWQiOiIxOGI2NDcxNjNkNzI3NjU4IiwidGsiOiIxNzA5NzA3In19=
Traceparent: 00-c08c0dc223cd66b2ded0251ff15cb4d5-18b647163d727658-01
Tracestate: 1709707@nr=0-0-989586-960636094-18b647163d727658-f839cf888860dfe2-1-1.250320-1742842580164
User-Agent: restclient-node/4.15.3
X-Request-Id: 2066ca19-c6f1-498a-be75-1923005edd06
X-Rest-Pool-Name: /services/webhooks.js
X-Retry: 0
X-Signature: ts=1742505638683,v1=ced36ab6d33566bb1e16c125819b8d840d6b8ef136b0b9127c76064466f5229b
X-Socket-Timeout: 22000
{"action":"order.processed","api_version":"v1","application_id":"123456","date_created":"2025-08-07T18:54:40.851374414Z","id":"123456","live_mode":true,"type":"order","user_id":123456,"data":{"id":"ORD01JYH1Z1YJN4HZ8J3Q0RB3YP6D"}}

A partir da notificação Webhook recebida, você poderá validar a autenticidade da sua origem. O Mercado Pago sempre incluirá a chave secreta nas notificações Webhooks que serão recebidas, o que permitirá validar sua autenticidade. Esta chave será enviada no header x-signature, que será similar ao exemplo abaixo.

plain
ts=1742505638683,v1=ced36ab6d33566bb1e16c125819b8d840d6b8ef136b0b9127c76064466f5229b

Para confirmar a validação, é necessário extrair a chave contida no header e compará-la com a chave fornecida para a sua aplicação em Configuração de Webhooks.

Siga uma das abordagens abaixo para validar a autenticidade da notificação.

O SDK oficial implementa verificação de assinatura baseada em HMAC (HMAC-based Webhook Signature Verification) para autenticar a origem de cada notificação recebida.

Para obter sua chave secreta (secret), abra a aplicação e, no menu lateral, selecione Configuração de Webhooks. Depois, revele a Assinatura secreta.

<?php
use MercadoPago\Webhook\WebhookSignatureValidator;
use MercadoPago\Exceptions\InvalidWebhookSignatureException;

try {
    WebhookSignatureValidator::validate(
        $_SERVER['HTTP_X_SIGNATURE'],
        $_SERVER['HTTP_X_REQUEST_ID'],
        $_GET['data_id'],
        $secret
    );
    http_response_code(200);
} catch (InvalidWebhookSignatureException $e) {
    http_response_code(401);
}

import { WebhookSignatureValidator, InvalidWebhookSignatureError } from 'mercadopago';

try {
    WebhookSignatureValidator.validate({
        xSignature: req.headers['x-signature'],
        xRequestId: req.headers['x-request-id'],
        dataId:     req.query['data.id'],
        secret,
    });
    res.sendStatus(200);
} catch (err) {
    if (err instanceof InvalidWebhookSignatureError) res.status(401).end();
    else throw err;
}

from mercadopago.webhook import WebhookSignatureValidator, InvalidWebhookSignatureError

try:
    WebhookSignatureValidator.validate(
        request.headers.get("x-signature"),
        request.headers.get("x-request-id"),
        request.args.get("data.id"),
        secret,
    )
    return "", 200
except InvalidWebhookSignatureError:
    return "", 401

import "github.com/mercadopago/sdk-go/pkg/webhook"

err := webhook.ValidateSignature(
    r.Header.Get("x-signature"),
    r.Header.Get("x-request-id"),
    r.URL.Query().Get("data.id"),
    secret,
)
if err != nil {
    w.WriteHeader(http.StatusUnauthorized)
    return
}
w.WriteHeader(http.StatusOK)

using MercadoPago.Error;
using MercadoPago.Webhook;

try {
    WebhookSignatureValidator.Validate(
        xSignature: Request.Headers["x-signature"],
        xRequestId: Request.Headers["x-request-id"],
        dataId:     Request.Query["data.id"],
        secret:     secret);
    return Ok();
} catch (InvalidWebhookSignatureException) {
    return Unauthorized();
}

import com.mercadopago.webhook.WebhookSignatureValidator;
import com.mercadopago.exceptions.MPInvalidWebhookSignatureException;

try {
    WebhookSignatureValidator.validate(
        request.getHeader("x-signature"),
        request.getHeader("x-request-id"),
        request.getParameter("data.id"),
        secret);
    response.setStatus(200);
} catch (MPInvalidWebhookSignatureException e) {
    response.setStatus(401);
}

require 'mercadopago/webhook/validator'

begin
    Mercadopago::Webhook::Validator.validate(
        request.headers['x-signature'],
        request.headers['x-request-id'],
        request.params['data.id'],
        secret
    )
    head :ok
rescue Mercadopago::Webhook::InvalidWebhookSignatureError
    head :unauthorized
end

Ações necessárias após receber a notificação

Quando você recebe uma notificação em sua plataforma, o Mercado Pago espera uma resposta para validar que essa recepção foi correta. Para isso, você deve devolver um HTTP STATUS 200 (OK) ou 201 (CREATED).

O tempo de espera para essa confirmação será de 22 segundos. Se essa confirmação não for enviada, o sistema entenderá que a notificação não foi recebida e realizará uma nova tentativa de envio a cada 15 minutos, até que receba a resposta. Após a terceira tentativa, o prazo será prorrogado, mas os envios continuarão acontecendo.

sequenceDiagram
    participant MercadoPago as Mercado Pago
    participant Integrador as Integrador

    MercadoPago->>Integrador: tentativa: 1. Atraso: 0 minutos
    MercadoPago->>Integrador: tentativa: 2. Atraso: 15 minutos
    MercadoPago->>Integrador: tentativa: 3. Atraso: 30 minutos
    MercadoPago->>Integrador: tentativa: 4. Atraso: 6 horas
    MercadoPago->>Integrador: tentativa: 5. Atraso: 48 horas
    MercadoPago->>Integrador: tentativa: 6. Atraso: 96 horas
    MercadoPago->>Integrador: tentativa: 7. Atraso: 96 horas
    MercadoPago->>Integrador: tentativa: 8. Atraso: 96 horas

Após responder à notificação e confirmar seu recebimento, você pode obter todas as informações sobre a order notificada enviando uma solicitação ao endpoint /v1/orders/{order_id}GET.

Com essa informação, você poderá realizar as atualizações necessárias em sua plataforma, como atualizar um pagamento aprovado.

AnteriorSwiftIntegre o Checkout Pro em uma aplicação mobile utilizando Swift.

PróximoConfigurar notificações opcionaisConfigure notificações opcionais para receber alertas sobre outros eventos da sua integração com o Checkout Pro.