## Guia Completo de Notificações Mercado Pago: Webhooks e IPN
As notificações são mensagens essenciais enviadas pelo servidor do Mercado Pago
para a sua aplicação a partir de eventos específicos (como a criação ou atualização
de um pagamento). A ativação desses tópicos de notificação é crucial para que você
possa programar o *backend* da sua loja para realizar diversas ações, como
atualizar o status de pedidos ou enviar e-mails de confirmação.
Existem dois tipos principais de notificações disponíveis para configuração:
**Webhooks** e **IPN**.
| Tipo | Descrição | Status |
| :--- | :--- | :--- |
| **Webhooks** | Utiliza HTTP REST para notificar instantaneamente as atualizações.
Oferece maior segurança na integração por meio de uma assinatura secreta para
validação de origem. | **Recomendado**. |
| **IPN (Instant Payment Notification)** | Permite que sua aplicação receba
notificações via chamada HTTP POST sobre o status de pagamento, *chargeback* ou
*merchant order*. Não permite validação via *header* `x-Signature`. | **Será
descontinuado**. |
Recomendamos fortemente a utilização das **notificações Webhooks** devido à maior
segurança e confiabilidade, especialmente porque o IPN será descontinuado em breve.
---
### 1. Tópicos de Notificação (Eventos)
A ativação dos tópicos depende da solução integrada e das necessidades do seu
negócio.
Abaixo está uma visão geral dos principais eventos e seus tópicos correspondentes:
| Evento | Nome em Suas integrações | Tópico | Produtos Associados |
| :--- | :--- | :--- | :--- |
| Criação e atualização de pagamentos | Orders (Mercado Pago) | `order` | Checkout
Transparente, Mercado Pago Point, Código QR |
| Criação e atualização de pagamentos | Pagamentos | `payment` | Checkout
Transparente (*legacy*), Checkout Pro, Checkout Bricks, Assinaturas, Wallet Connect
|
| Pagamento recorrente de uma assinatura | Planos e assinaturas |
`subscription_authorized_payment` | Assinaturas |
| Vinculação de um plano de assinatura | Planos e assinaturas |
`subscription_preapproval_plan` | Assinaturas |
| Criação, fechamento ou expiração de ordens comerciais | Ordens comerciais |
`topic_merchant_order_wh` / `merchant_order` | Checkout Pro, Código QR (*legacy*) |
| Abertura de *chargebacks* | Chargebacks | `topic_chargebacks_wh` / `chargebacks`
| Checkout Pro, Checkout Transparente, Checkout Bricks |
| Alertas de fraude | Alertas de fraude | `stop_delivery_op_wh` | Checkout
Transparente, Checkout Pro |
| Criação de estornos e reclamações | Reclamações | `topic_claims_integration_wh` |
Checkout Transparente, Checkout Pro, Checkout Bricks, Assinaturas, Mercado Pago
Point, Código QR, Wallet Connect |
| Recuperação e atualização de informações de cartões | Card Updater |
`topic_card_id_wh` | Checkout Pro, Checkout Transparente, Checkout Bricks |
#### Considerações Especiais para Tópicos:
* **Assinaturas:** Se houver planos associados, ative
`subscription_preapproval_plan`. Se não houver, ative `subscription_preapproval` ou
`subscription_authorized_payment`. Em **todos os casos**, é necessário **ativar o
tópico `payments`** para receber notificações sobre os pagamentos efetuados.
* **Alertas de Fraude (`stop_delivery_op_wh`):** Se um alerta de fraude for
detectado e o tópico estiver ativo, você receberá uma notificação. **Deve-se
cancelar o pedido sem entregá-lo**, realizando uma chamada à API de cancelamentos.
Este tipo de notificação não segue a lógica usual de tentativas; se você não
retornar `HTTP STATUS 200 (OK)` ou `201 (CREATED)`, a notificação será perdida e
não será reenviada.
* **Código QR (Webhooks):** Não é possível configurar notificações via **Suas
integrações** para Webhooks de Código QR. A configuração deve ser feita no momento
da criação do pagamento. Por isso, a validação de origem usando o *header* `x-
Signature` não é possível.
* **Link de pagamento:** Não é possível configurar notificações para Links de
pagamento gerados através do Painel do Mercado Pago.
---
### 2. Configuração de Webhooks (Recomendada)
As notificações Webhooks podem ser configuradas de duas maneiras:
1. **Configuração via Suas integrações:** Permite configurar notificações para
cada aplicação e validar a origem usando a assinatura secreta.
2. **Configuração durante a criação de pagamentos:** Permite a configuração
específica via campo `notification_url` para cada pagamento, preferência ou pedido
comercial.
**Importante:** As URLs configuradas durante a criação do pagamento terão
prioridade sobre aquelas configuradas através de Suas integrações.
#### 2.1 Configuração via Suas integrações
Este método permite configurar URLs de teste e produção:
1. Acesse **Suas integrações** e selecione a aplicação desejada.
2. No menu esquerdo, vá para **Webhooks > Configurar notificações**.
3. Configure a **URL modo teste** e a **URL modo produção**.
* *Nota:* Para identificar múltiplas contas, adicione o parâmetro `?
cliente=(nomedovendedor)` ao final da URL.
4. Selecione os **eventos** (tópicos) para os quais deseja receber notificações em
formato `json` via `HTTP POST`.
5. Clique em **Salvar** para gerar uma **assinatura secreta** exclusiva. Essa
chave é fundamental para validar a autenticidade das notificações.
#### 2.2 Configuração durante a criação de pagamentos
Você pode especificar a URL de notificação ao criar pagamentos utilizando o campo
`notification_url`. Para garantir que a notificação seja enviada exclusivamente via
Webhooks, adicione o parâmetro `source_news=webhooks` à URL.
**Exemplo de Código (cURL):**
```bash
curl -X POST \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
'[Link] \
-d '{
"transaction_amount": 100,
"token": "ff8080814c11e237014c1ff593b57b4d",
"description": "Blue shirt",
"installments": 1,
"payment_method_id": "visa",
"issuer_id": 310,
"notification_url": "[Link]
source_news=webhooks",
"payer": {
"email": "test@[Link]"
}
}'
```
#### 2.3 Estrutura e Exemplo de Notificação Webhook
As notificações são entregues em formato JSON, mesmo quando configuradas durante a
criação do pagamento.
**Exemplo de Notificação (`payment` tópico):**
```json
{
"id": 12345,
"live_mode": true,
"type": "payment",
"date_created": "2015-03-25T10:04:58.396-04:00",
"user_id": 44444,
"api_version": "v1",
"action": "[Link]",
"data": {
"id": "999999999"
}
}
```
O campo `[Link]` (`999999999` no exemplo) é o ID do pagamento, da *merchant order*
ou da reclamação.
---
### 3. Validação de Origem (Webhooks)
Para garantir que a notificação foi enviada pelo Mercado Pago, o *header* **`x-
signature`** é enviado com a assinatura secreta.
**Exemplo de Header `x-signature`:**
`ts=1704908010,v1=618c85345248dd820d5fd456117c2ab2ef8eda45a0282ff693eac24131a5e839`
Onde `ts` é o *timestamp* da notificação, e `v1` é a assinatura encriptada.
#### Processo de Validação (HMAC SHA256)
1. Extraia o `ts` e o `v1` (hash) do *header* `x-signature`.
2. Obtenha o valor do *header* `x-request-id`.
3. Obtenha o valor do ID do evento (`[Link]`) dos *query params*.
4. Crie a *string* do template (manifesto) utilizando a estrutura abaixo,
removendo qualquer valor que não esteja presente na sua notificação:
**Template:** `id:[data.id_url];request-id:[x-request-id_header];ts:
[ts_header];`
5. Calcule um HMAC (Código de Autenticação de Mensagem Baseado em Hash) usando a
função de **hash SHA256** em base hexadecimal.
* Utilize a **assinatura secreta** (obtida em Suas integrações) como chave.
* Utilize o template preenchido como mensagem.
6. Compare a chave gerada (`sha`) com a chave extraída do *header* (`v1` ou
`hash`).
#### Exemplo de Código para Validação (PHP)
O exemplo abaixo demonstra como realizar a verificação do HMAC:
```php
<?php
// Obtém o valor do x-signature do header
$xSignature = $_SERVER['HTTP_X_SIGNATURE'];
$xRequestId = $_SERVER['HTTP_X_REQUEST_ID'];
// Obtém Query params relacionados à URL da requisição
$queryParams = $_GET;
$dataID = isset($queryParams['[Link]']) ? $queryParams['[Link]'] : ''; // Extrai
o "[Link]" dos query params
// Separa o x-signature em partes (ts e v1)
$parts = explode(',', $xSignature);
$ts = null;
$hash = null;
// Itera sobre os valores para obter ts e v1
foreach ($parts as $part) {
$keyValue = explode('=', $part, 2);
if (count($keyValue) == 2) {
$key = trim($keyValue);
$value = trim($keyValue);
if ($key === "ts") {
$ts = $value;
} elseif ($key === "v1") {
$hash = $value;
}
}
}
// Obtém a chave secreta (substitua por sua chave real)
$secret = "your_secret_key_here";
// Gera a string do manifesto
$manifest = "id:$dataID;request-id:$xRequestId;ts:$ts;";
// Cria uma assinatura HMAC usando SHA256
$sha = hash_hmac('sha256', $manifest, $secret);
if ($sha === $hash) {
// Verificação HMAC aprovada
echo "HMAC verification passed";
} else {
// Verificação HMAC falhou
echo "HMAC verification failed";
}
?>
```
---
### 4. Configuração de IPN (Aviso de Descontinuação)
IPN é um mecanismo de notificação legado que será descontinuado em breve. Ele
permite notificações sobre `payment`, `chargebacks` e `merchant_orders`.
#### 4.1 Configuração via Suas integrações (IPN)
Ao contrário de Webhooks, a configuração via Suas integrações para IPN define
**apenas uma URL de notificação** para **todos os aplicativos da sua conta do
Mercado Pago**.
1. Acesse **Suas integrações** e selecione uma aplicação.
2. No menu, clique em **IPN** e configure a **URL de produção**.
3. Selecione os **eventos** (`payment`, `point_integration_ipn`,
`delivery_cancellation`, `merchant_order`, `chargebacks`).
#### 4.2 Configuração durante a criação (IPN)
Para configurar notificações IPN específicas para um pagamento, use o campo
`notification_url`. Para receber *exclusivamente* via IPN, adicione o parâmetro
`source_news=ipn` à URL.
**Exemplo de Código (PHP - para criação de pagamento com IPN específico):**
```php
<?php
// ... (setup e dados do pagamento)
$payment->notification_url = `[Link]
source_news=ipn`;
// ...
$response = array(
'status' => $payment->status,
'status_detail' => $payment->status_detail,
'id' => $payment->id
);
echo json_encode($response);
?>
```
#### 4.3 Formato da Notificação IPN
Ao contrário de Webhooks (que enviam JSON), o Mercado Pago notificará a URL IPN com
dois parâmetros:
`[Link]
| Campo | Descrição |
| :--- | :--- |
| `topic` | Identifica o tipo de recurso: `payment`, `chargebacks`,
`merchant_order` ou `point_integration_ipn`. |
| `id` | Identificador único do recurso notificado. |
---
### 5. Ações Necessárias Após Receber uma Notificação (Webhooks e IPN)
Ao receber qualquer notificação (Webhooks ou IPN), o Mercado Pago espera uma
confirmação de recebimento.
#### 5.1 Confirmação de Recebimento
É necessário retornar um status **`HTTP STATUS 200 (OK)`** ou **`201 (CREATED)`**.
* O **tempo de espera** para essa confirmação é de **22 segundos**.
* Se a confirmação falhar, o sistema realizará **novas tentativas de envio a cada
15 minutos** até receber uma resposta. Após a terceira tentativa, o prazo é
prorrogado, mas os envios continuam.
#### 5.2 Obtenção dos Dados Completos
Após responder com sucesso (200/201), você deve buscar as informações completas do
recurso notificado fazendo uma requisição ao *endpoint* correspondente da API,
utilizando o ID recebido na notificação.
| Tópico | URL (Endpoint para consulta) | Documentação |
| :--- | :--- | :--- |
| `payment` | `[Link] | Obter pagamento |
| `topic_merchant_order_wh` ou `merchant_orders` |
`[Link] | Obter pedido |
| `topic_chargebacks_wh` ou `chargebacks` |
`[Link] | Obter estorno |
| `point_integration_wh` ou `point_integration_ipn` |
`[Link]
{paymentintentid}` | Obter intenção de pagamento |
Com essas informações completas, você pode realizar as atualizações necessárias na
sua plataforma, como, por exemplo, mudar o status de um pedido para "aprovado".
#### Exemplo de Código para Processamento de IPN/Webhook (PHP)
Este exemplo demonstra como usar os parâmetros recebidos por IPN (`topic` e `id`)
ou as informações recebidas por Webhook para buscar o recurso completo e verificar
se o valor pago é suficiente para liberar o item (lógica aplicável a *merchant
orders*):
```php
<?php
MercadoPago\SDK::setAccessToken("ENV_ACCESS_TOKEN");
// Lógica para obter o ID e o TÓPICO (ajustada para IPN ou Webhook)
$topic = $_GET["topic"] ?? $_POST["type"];
$id = $_GET["id"] ?? ($_POST["data"]["id"] ?? null);
$resource = null;
switch($topic) {
case "payment":
$resource = MercadoPago\Payment::find_by_id($id);
// Se for um pagamento, geralmente queremos a ordem associada
if (isset($resource->order->id)) {
$merchant_order = MercadoPago\MerchantOrder::find_by_id($resource-
>order->id);
}
break;
case "merchant_order":
$merchant_order = MercadoPago\MerchantOrder::find_by_id($id);
break;
// Outros casos (subscription, claim, etc.)
}
// Exemplo de lógica de verificação de pagamento total para Merchant Order
if (isset($merchant_order)) {
$paid_amount = 0;
foreach ($merchant_order->payments as $payment) {
if ($payment['status'] == 'approved'){
$paid_amount += $payment['transaction_amount'];
}
}
// Se o valor pago for igual ou maior que o total da ordem, o item pode ser
liberado
if($paid_amount >= $merchant_order->total_amount){
print_r("Totalmente pago. Libere seu item.");
} else {
print_r("Ainda não pago. Não libere seu item.");
}
}
// Lembre-se de retornar HTTP 200/201
header('HTTP/1.1 200 OK');
?>
```
**Analogia para Entendimento:**
Pense no Mercado Pago como um mensageiro importante. Você tem um sistema de
recebimento (sua URL de notificação).
1. **Polling (Método Ineficiente):** Seria como você ligar para o mensageiro a
cada 5 minutos perguntando: "Algum evento novo? Algum evento novo?" (Isso
sobrecarrega seu sistema).
2. **Webhooks (Método Recomendado):** O mensageiro (Mercado Pago) liga para você
**instantaneamente** quando algo acontece (ex: pagamento aprovado). Ele usa uma
senha secreta (`x-signature`) para provar que é ele mesmo, garantindo a segurança.
Você deve sempre atender (retornar 200/201) e, depois de confirmar o recebimento,
ligar de volta para o escritório dele (a API) para pegar os detalhes completos da
mensagem.
3. **IPN (Método Antigo):** É parecido com o Webhook, mas o mensageiro não usa a
senha secreta de forma validável, e a ligação pode demorar um pouco mais. Como é
menos seguro e está sendo desativado, é melhor evitá-lo.