Webhooks - Notificações - Mercado Pago Developers
O que você está buscando?

Não sabe como começar a integrar? 

Acesse os primeiros passos

Webhooks

O Webhooks (também conhecido como retorno de chamada web) é um método simples que facilita com que um app ou sistema forneça informações em tempo real sempre que um evento acontece, ou seja, é um modo de receber dados entre dois sistemas de forma passiva através de um HTTP POST.

As notificações Webhooks poderão ser configuradas para uma ou mais aplicações criadas em seu Painel do desenvolvedor.

Uma vez configurado, o Webhook será enviado sempre que ocorrer um ou mais eventos cadastrados, evitando que haja um trabalho de pesquisa a cada minuto em busca de uma resposta e, por consequência, que ocorra uma sobrecarga do sistema e a perda de dados sempre que houver alguma situação. Após receber uma notificação na sua plataforma, o Mercado Pago aguardará uma resposta para validar se você a recebeu corretamente.

Nesta documentação, explicaremos as configurações necessárias para o recebimento das mensagens (através do Painel do desenvolvedor ou durante a criação de pagamentos), além de apresentar quais são as ações necessárias que você deverá ter para que o Mercado Pago valide que as notificações foram devidamente recebidas.

Configuração através do Painel do desenvolvedor

Abaixo explicaremos como: indicar as URLs que serão notificadas, configurar os eventos dos quais se receberá a notificação, simular o recebimento de diversos tipos de notificações e validar que as notificações que recebe são enviadas pelo Mercado Pago.

webhooks

Configurar URLs e Eventos

  1. Caso ainda não tenha, crie uma aplicação no Painel do desenvolvedor.
  2. Com a aplicação criada, navegue até a seção Webhooks na página de "Detalhes da aplicação" e configure as URLs de produção e teste da qual serão recebidas as notificações.
  3. Caso seja necessário identificar múltiplas contas, no final da URL indicada você poderá indicar o parâmetro ?cliente=(nomedovendedor) endpoint para identificar os vendedores.
  4. Em seguida, selecione os eventos dos quais você receberá notificações em formato json através de um HTTP POST para a URL especificada anteriormente. Um evento é qualquer tipo de atualização no objeto relatado, incluindo alterações de status ou atributo. Veja na tabela abaixo os eventos que poderão ser configurados.
Tipo de notificaçãoAçãoDescrição
paymentpayment.createdCriação de pagamento
paymentpayment.updatedAtualização de pagamento
mp-connectapplication.deauthorizedDesvinculação de conta
mp-connectapplication.authorizedVinculação de conta
subscription_preapprovalcreated - updatedAssinatura
subscription_preapproval_plancreated - updatedPlano de assinatura
subscription_authorized_paymentcreated - updatedPagamento recorrente de uma assinatura
point_integration_whstate_FINISHEDProcesso de pagamento concluído
point_integration_whstate_CANCELEDProcesso de pagamento cancelado
point_integration_whstate_ERROROcorreu um erro ao processar a tentativa de pagamento
deliverydelivery.updatedDados de envio e atualização do pedido
delivery_cancellationcase_createdSolicitação de cancelamento do envio
topic_claims_integration_whupdatedReclamações feitas pelas vendas
  1. Por fim, clique em Salvar para gerar uma assinatura secreta para a aplicação. A assinatura é um método de validação para garantir que as notificações recebidas foram enviadas pelo Mercado Pago, por isso, é importante conferir as informações de autenticidade para evitar fraudes.
Importante
O Mercado Pago sempre enviará essa assinatura nas notificações Webhooks. Sempre confira essa informação de autenticidade para evitar fraudes.

A assinatura gerada não tem prazo de validade e, embora não seja obrigatório, recomendamos renovar periodicamente a assinatura secreta. Para isso, basta clicar no botão de redefinição ao lado da assinatura.

Validar origem da notificação

No momento em que a URL cadastrada receber uma notificação, você poderá validar se o conteúdo enviado no header x-signature (exemplo: ts=1704908010,v1=618c85345248dd820d5fd456117c2ab2ef8eda45a0282ff693eac24131a5e839) foi enviado pelo Mercado Pago, a fim de obter mais segurança no recebimento das suas notificações. Veja abaixo como configurar essa validação.

  1. Extraia o timestamp (ts) e a assinatura do header x-signature. Para isso, divida o conteúdo do header pelo caractere ,, o que resultará em uma lista de elementos.
  2. Em seguida, divida cada elemento da lista pelo caractere =, o que resultará em um par de prefixos e os valores. O valor para o prefixo ts é o timestamp (em milissegundos) da notificação e v1 é a assinatura encriptada.
  3. Utilizando o template abaixo, substitua os parâmetros pelos dados recebidos na sua notificação.

template

id:[data.id_url];request-id:[x-request-id_header];ts:[ts_header];

No template, os valores englobados por [] devem ser trocados pelos valores da notificação, como:

  • Parâmetros com sufixo _url são provenientes de query params. Exemplo: [data.id_url] será substituido pelo valor correspondente ao ID do evento (data.id).
  • [timestamp] será o valor ts extraído do header x-signature.
Caso algum dos valores apresentados no template abaixo não esteja presente em sua notificação, você deverá removê-los do template.
  1. No Painel do desenvolvedor, selecione a aplicação integrada, navegue até a seção Webhooks e revele a assinatura secreta gerada.
  2. Gere a contra chave para validação. Para isso, calcule um HMAC com a função de hash SHA256 em base hexadecimal, utilize a assinatura secreta como chave e o template populado com os valores como mensagem. Exemplo:
          
$cyphedSignature = hash_hmac('sha256', $data, $key);

        
          
const crypto = require('crypto');
const cyphedSignature = crypto
    .createHmac('sha256', secret)
    .update(signatureTemplateParsed)
    .digest('hex'); 

        
          
String cyphedSignature = new HmacUtils("HmacSHA256", secret).hmacHex(signedTemplate);

        
          
import hashlib, hmac, binascii

cyphedSignature = binascii.hexlify(hmac_sha256(secret.encode(), signedTemplate.encode()))

        
  1. Por fim, compare a chave gerada com a chave extraída do cabeçalho, considerando elas devem ter uma correspondência exata. Além disso, é possível usar o timestamp extraído do header para comparação com um timestamp gerado na hora do recebimento da notificação, a fim de estipular uma tolerância de atraso no recebimento da mensagem.

Simular o recebimento da notificação

  1. Após configurar as URLs e os Eventos, clique em Simular para experimentar e testar se a URL indicada está recebendo as notificações corretamente.
  2. Na tela em questão, selecione a URL a ser testada, podendo ser de teste ou de produção.
  3. Em seguida, selecione o tipo de evento e insira a identificação que será enviada no corpo da notificação.
  4. Por fim, cique em Enviar teste para verificar a solicitação, a resposta dada pelo servidor e a descrição do evento.

Configuração durante a criação de pagamentos

É possível configurar a URL de notificação de modo mais específico, para cada pagamento utilizando o campo notification_url. Veja abaixo como fazer isso com uso dos SDKs.

  1. No campo notificaction_url, indique a URL da qual serão recebidas as notificações como exemplificado abaixo.
          
<?php 
$client = new PaymentClient();

        $body = [
            'transaction_amount' => 100,
            'token' => 'token',
            'description' => 'description',
            'installments' => 1,
            'payment_method_id' => 'visa',
            'notification_url' => 'http://test.com',
            'payer' => array(
                'email' => 'test@test.com',
                'identification' => array(
                    'type' => 'CPF',
                    'number' => '19119119100'
                )
            )
        ];

$client->create(body);
?>

        
          
const client = new MercadoPagoConfig({ accessToken: 'ACCESS_TOKEN' });
const payment = new Payment(client);

const body = {
 transaction_amount: '100',
  token: 'token',
  description: 'description',
  installments: 1,
  payment_method_id: 'visa',
  notification_url: 'http://test.com',
  payer: {
    email: 'test@test.com',
    identification: {
      type: 'CPF',
      number: '19119119100'
    }
  }
};

payment.create({ body: body, requestOptions: { idempotencyKey: '<SOME_UNIQUE_VALUE>' } }).then(console.log).catch(console.log);

        
          
MercadoPago.SDK.setAccessToken("YOUR_ACCESS_TOKEN");


Payment payment = new Payment();
payment.setTransactionAmount(Float.valueOf(request.getParameter("transactionAmount")))
      .setToken(request.getParameter("token"))
      .setDescription(request.getParameter("description"))
      .setInstallments(Integer.valueOf(request.getParameter("installments")))
      .setPaymentMethodId(request.getParameter("paymentMethodId"))
      .setNotificationUrl("http://requestbin.fullcontact.com/1ogudgk1");


Identification identification = new Identification();
identification.setType(request.getParameter("docType"))
             .setNumber(request.getParameter("docNumber")); 


Payer payer = new Payer();
payer.setEmail(request.getParameter("email"))
    .setIdentification(identification);
   
payment.setPayer(payer);


payment.save();


System.out.println(payment.getStatus());



        
          
require 'mercadopago'
sdk = Mercadopago::SDK.new('YOUR_ACCESS_TOKEN')


payment_data = {
 transaction_amount: params[:transactionAmount].to_f,
 token: params[:token],
 description: params[:description],
 installments: params[:installments].to_i,
 payment_method_id: params[:paymentMethodId],
 notification_url: "http://requestbin.fullcontact.com/1ogudgk1",
 payer: {
   email: params[:email],
   identification: {
     type: params[:docType],
     number: params[:docNumber]
   }
 }
}


payment_response = sdk.payment.create(payment_data)
payment = payment_response[:response]


puts payment



        
          
using System;
using MercadoPago.Client.Common;
using MercadoPago.Client.Payment;
using MercadoPago.Config;
using MercadoPago.Resource.Payment;


MercadoPagoConfig.AccessToken = "YOUR_ACCESS_TOKEN";


var paymentRequest = new PaymentCreateRequest
{
   TransactionAmount = decimal.Parse(Request["transactionAmount"]),
   Token = Request["token"],
   Description = Request["description"],
   Installments = int.Parse(Request["installments"]),
   PaymentMethodId = Request["paymentMethodId"],
   NotificationUrl = "http://requestbin.fullcontact.com/1ogudgk1",


   Payer = new PaymentPayerRequest
   {
       Email = Request["email"],
       Identification = new IdentificationRequest
       {
           Type = Request["docType"],
           Number = Request["docNumber"],
       },
   },
};


var client = new PaymentClient();
Payment payment = await client.CreateAsync(paymentRequest);


Console.WriteLine(payment.Status);



        
          
import mercadopago
sdk = mercadopago.SDK("ACCESS_TOKEN")


payment_data = {
   "transaction_amount": float(request.POST.get("transaction_amount")),
   "token": request.POST.get("token"),
   "description": request.POST.get("description"),
   "installments": int(request.POST.get("installments")),
   "payment_method_id": request.POST.get("payment_method_id"),
   "notification_url" =  "http://requestbin.fullcontact.com/1ogudgk1",
   "payer": {
       "email": request.POST.get("email"),
       "identification": {
           "type": request.POST.get("type"), 
           "number": request.POST.get("number")
       }
   }
}


payment_response = sdk.payment().create(payment_data)
payment = payment_response["response"]


print(payment)

        
          
curl -X POST \
   -H 'accept: application/json' \
   -H 'content-type: application/json' \
   -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
   'https://api.mercadopago.com/v1/payments' \
   -d '{
         "transaction_amount": 100,
         "token": "ff8080814c11e237014c1ff593b57b4d",
         "description": "Blue shirt",
         "installments": 1,
         "payment_method_id": "visa",
         "issuer_id": 310,
         "notification_url": "http://requestbin.fullcontact.com/1ogudgk1",
         "payer": {
           "email": "test@test.com"


         }
   }'



        
  1. Implemente o receptor de notificações usando o seguinte código como exemplo:

php

<?php
 MercadoPago\SDK::setAccessToken("ENV_ACCESS_TOKEN");
 switch($_POST["type"]) {
     case "payment":
         $payment = MercadoPago\Payment::find_by_id($_POST["data"]["id"]);
         break;
     case "plan":
         $plan = MercadoPago\Plan::find_by_id($_POST["data"]["id"]);
         break;
     case "subscription":
         $plan = MercadoPago\Subscription::find_by_id($_POST["data"]["id"]);
         break;
     case "invoice":
         $plan = MercadoPago\Invoice::find_by_id($_POST["data"]["id"]);
         break;
     case "point_integration_wh":
         // $_POST contém as informações relacionadas à notificação.
         break;
 }
?>
  1. Feitas as devidas configurações, a notificação via Webhooks terá o seguinte formato:
Importante
Para o tipo de evento point_integration_wh, o formato da notificação muda. Clique aqui para consultar a documentação do Mercado Pago Point.
No caso dos eventos de delivery e topic_claims_integration_wh, também teremos alguns atributos diferentes na resposta. Veja na tabela abaixo quais são essas particularidades.

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": "payment.created",
 "data": {
     "id": "999999999"
 }
}

Isso indica que foi criado o pagamento 999999999 para o usuário 44444 em modo de produção com a versão V1 da API e que esse evento ocorreu na data 2016-03-25T10:04:58.396-04:00.

AtributoDescrição
idID de notificação
live_modeIndica se a URL informada é valida
typeTipo de notificação recebida (payments, mp-connect, subscription, claim, etc)
date_createdData de criação do recurso
user_idUserID de vendedor
api_versionIndica se é uma notificação duplicada ou não
actionTipo de notificação recebida, indicando se se trata da atualização de um recurso ou da criação de um novo
data - idID do payment, do merchant_order ou da reclamação
attempts (delivery)Número de vezes que uma notificação foi enviada
received (delivery)Data de criação do recurso
resource (delivery)Tipo de notificação recebida, indicando se trata-se da atualização de um recurso ou da criação de um novo
sent (delivery)Data de envio da notificação
topic (delivery)Tipo de notificação recebida
resource (claims)Tipo de notificação recebida, indicando notificações relacionadas à reclamações feitas por vendas
  1. Caso deseje receber notificações apenas de Webhook e não de IPN, você pode adicionar na notification_url o parâmetro source_news=webhook. Por exemplo: https://www.yourserver.com/notifications?source_news=webhooks

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

Quando você recebe uma notificação na sua plataforma, o Mercado Pago aguarda uma resposta para validar se você a recebeu corretamente. Para isso, você deve retornar um HTTP STATUS 200 (OK) ou 201 (CREATED). Caso essa resposta não seja enviada, será entendido que você não recebeu a notificação e uma nova tentativa de envio será realizada até que você envie a resposta.

Na tabela abaixo você encontra os principais eventos, prazos e tempo de espera para o recebimento de novas tentativas de notificação.

EventoPrazo após o primeiro envioTempo de espera de confirmação
Envio-22 segundos
Primeira tentativa15 minutos5 segundos
Segunda tentativa30 minutos5 segundos
Terceira tentativa6 horas5 segundos
Quarta tentativa48 horas5 segundos
Quinta tentativa96 horas5 segundos
Importante
No caso do tipo de evento delivery, para evitar que o tópico de notificações realize novas tentativas de envio será necessário confirmar o recebimento das mensagens retornando um HTTP STATUS 200 (OK) em até 500 ms. Caso não seja enviada uma mensagem confirmando o recebimento da notificação, novas tentativas serão feitas em um período de 12 horas.

Depois de dar um retorno à notificação e confirmar o seu recebimento, você obterá as informações completas do recurso notificado acessando o endpoint correspondente da API:

TipoURLDocumentação
paymenthttps://api.mercadopago.com/v1/payments/[ID]ver documentação
subscription_preapprovalhttps://api.mercadopago.com/preapprovalver documentação
subscription_preapproval_planhttps://api.mercadopago.com/preapproval_planver documentación
subscription_authorized_paymenthttps://api.mercadopago.com/authorized_paymentsver documentación
topic_claims_integration_whhttps://api.mercadopago.com/claim_resourcever documentação

Além disso, especificamente em alertas de fraude, o pedido não deve ser entregue e o cancelamento precisa ser realizado através da API de cancelamentos.

Na notificação, você receberá um JSON com as seguintes informações contendo o id de pagamento para efetuar o cancelamento.

json



 "description": ".....",
 "merchant_order": 4945357007,
 "payment_id": 23064274473

Importante
É possível obter mais detalhes sobre o pedido utilizando a API Obter pedido .

Com essas informações, você poderá realizar as atualizações necessárias na sua plataforma como, por exemplo, atualizar um pagamento aprovado.