Inicio
Documentação
Recursos
Parcerias
Comunidade

Parcerias

Conheça nosso programa para agĂȘncias ou desenvolvedores que oferecem serviços de integração e vendedores que desejam contratĂĄ-los.

Comunidade

Fique por dentro das Ășltimas novidades, peça ajuda a outros integradores e compartilhe seu conhecimento.

Webhooks - NotificaçÔes - Mercado Pago Developers

Busca inteligente powered by OpenAI 

Webhooks

Webhooks (tambĂ©m conhecido como retorno de chamada web) sĂŁo um mĂ©todo simples que permite a uma aplicação ou sistema fornecer informaçÔes em tempo real sempre que um evento ocorre. É uma forma passiva de receber dados entre dois sistemas por meio de uma solicitação HTTP POST.

As notificaçÔes Webhooks podem ser configuradas para cada uma das aplicaçÔes criadas em Suas integraçÔes. VocĂȘ tambĂ©m poderĂĄ configurar uma URL de teste que, junto com suas credenciais de teste, permitirĂĄ testar o funcionamento correto das suas notificaçÔes antes de sair Ă  produção.

Uma vez configuradas, as notificaçÔes Webhooks serão enviadas sempre que ocorrer um ou mais eventos cadastrados. Isso evita a necessidade de verificaçÔes constantes, prevenindo a sobrecarga do sistema e a perda de dados em situaçÔes críticas.

Para configurar as notificaçÔes Webhooks, escolha entre uma das opçÔes abaixo:

Tipo de configuraçãoDescrição
Configuração via Suas integraçÔesPermite configurar notificaçÔes para cada aplicação, identificar contas diferentes se necessårio, e validar a origem da notificação utilizando uma assinatura secreta (exceto para notificaçÔes de integraçÔes com Código QR).
Configuração durante a criação de pagamentosPermite a configuração especĂ­fica das notificaçÔes para cada pagamento, preferĂȘncia ou pedidos comerciais. NĂŁo Ă© permitido configurar para integraçÔes com Mercado Pago Point.
Importante
As URLs configuradas durante a criação do pagamento terão prioridade sobre aquelas configuradas através de Suas integraçÔes.

Uma vez que as notificaçÔes estiverem configuradas, consulte as açÔes necessårias após receber uma notificação para validar se foram devidamente recebidas.

Configuração via Suas integraçÔes

Configure notificaçÔes para cada aplicação diretamente em Suas integraçÔes de forma eficiente e segura. Nesta documentação, explicaremos como:

  1. Indicar URLs e configurar eventos
  2. Validar origem da notificação
  3. Simular o recebimento da notificação
Importante
Este método de configuração não estå disponível para integraçÔes com Código QR e nem Assinaturas. Para configurar notificaçÔes com alguma dessas duas integraçÔes, utilize o método Configuração durante a criação de pagamentos .

1. Indicar URLs e configurar eventos

Para configurar as notificaçÔes Webhooks via Suas integraçÔes, é necessårio indicar as URLs onde elas serão recebidas e especificar os eventos para os quais deseja receber notificaçÔes.

Para isso, siga as etapas descritas abaixo.

  1. Acesse Suas integraçÔes e selecione a aplicação para a qual deseja ativar as notificaçÔes. Caso ainda não tenha criado uma aplicação, acesse a documentação Painel do Desenvolvedor e siga as instruçÔes.
  2. No menu à esquerda, vå até Webhooks > Configurar notificaçÔes e configure as URLs que serão usadas para receber as notificaçÔes. Recomendamos utilizar uma URL diferente para o modo de teste e o modo produção:
    • URL modo teste: fornece uma URL que permite testar o correto funcionamento das notificaçÔes dessa aplicação durante a fase de teste ou desenvolvimento. O teste dessas notificaçÔes deverĂĄ ser realizado exclusivamente com as credenciais de teste de usuĂĄrios produtivos.
    • URL modo produção: fornece uma URL para receber notificaçÔes com sua integração produtiva. Essas notificaçÔes deverĂŁo ser configuradas com credenciais produtivas.

webhooks

Nota
Caso seja necessĂĄrio identificar mĂșltiplas contas, adicione o parĂąmetro ?cliente=(nomedovendedor) ao final da URL indicada para identificar os vendedores.
  1. Selecione os eventos para os quais deseja receber notificaçÔes em formato json através de um HTTP POST para a URL especificada anteriormente. Um evento pode ser qualquer atualização no objeto relatado, incluindo alteraçÔes de status ou atributos. Consulte a tabela abaixo para ver os eventos configuråveis, considerando a solução do Mercado Pago integrada e suas necessidades de negócio.

EventosNome em Suas integraçÔesTópicoProdutos associados
Criação e atualização de pagamentosPagamentospaymentCheckout Transparente
Checkout Pro
Checkout Bricks
Assinaturas
Wallet Connect
Pagamento recorrente de uma assinatura (criação - atualização)Planos e assinaturassubscription_authorized_paymentAssinaturas
Vinculação de uma assinatura (criação - atualização)Planos e assinaturassubscription_preapprovalAssinaturas
Vinculação de um plano de assinatura (criação - atualização)Planos e assinaturassubscription_preapproval_planAssinaturas
Vinculação e desvinculação de contas que se conectaram através de OAuthVinculação de aplicaçÔesmp-connectTodos os produtos que tenham OAuth implementado
TransaçÔes com Wallet ConnectWallet Connectwallet_connectWallet Connect
Alertas de fraude apĂłs o processamento de um pedidoAlertas de fraudestop_delivery_op_whCheckout Transparente
Checkout Pro
Criação de estornos e reclamaçÔesReclamaçÔestopic_claims_integration_whCheckout 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 no Mercado PagoCard Updatertopic_card_id_whCheckout Pro
Checkout Transparente
Checkout Bricks
Criação, fechamento ou expiração de ordens comerciaisOrdens comerciaistopic_merchant_order_whCheckout Pro
CĂłdigo QR
Abertura de chargebacks, mudanças de status e modificaçÔes referentes às liberaçÔes de dinheiroChargebackstopic_chargebacks_whCheckout Pro
Checkout Transparente
Checkout Bricks
Finalização, cancelamento ou erros ao processar intençÔes de pagamento de dispositivos Mercado Pago Point.IntegraçÔes Pointpoint_integration_whMercado Pago Point
Importante
Em caso de dĂșvidas sobre quais tĂłpicos ativar ou quais eventos serĂŁo notificados, consulte a documentação InformaçÔes adicionais sobre notificaçÔes .
  1. Por fim, clique e Salvar para gerar uma assinatura secreta exclusiva para a sua aplicação, permitindo validar a autenticidade das notificaçÔes recebidas e garantir que tenham sido enviadas pelo Mercado Pago. A assinatura gerada não tem prazo de validade e sua renovação periódica não é obrigatória, embora seja altamente recomendåvel. Para renovå-la, clique no botão de redefinição ao lado da assinatura.
Importante
As notificaçÔes de Código QR não podem ser verificadas utilizando a assinatura secreta, por isso, prossiga diretamente com a etapa de simulação de recebimento de notificaçÔes. Para integraçÔes com Código QR que necessitam verificar a origem das notificaçÔes, entre em contato com Soporte do Mercado Pago .

2. Validar origem da notificação

As notificaçÔes enviadas pelo Mercado Pago serão semelhantes ao exemplo abaixo para um alerta do tópico payment:

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"
 }
}

O Mercado Pago sempre incluirå a assinatura secreta nas notificaçÔes Webhooks recebidas na URL cadastrada. Isso permitirå validar a sua autenticidade, proporcionando maior segurança e prevenindo possíveis fraudes.

Esta assinatura serĂĄ enviada no header x-signature, conforme o exemplo abaixo.

x-signature

`ts=1704908010,v1=618c85345248dd820d5fd456117c2ab2ef8eda45a0282ff693eac24131a5e839`

Para configurar essa validação, é necessårio extrair a chave contida no header e comparå-la com a chave fornecida para sua aplicação em Suas integraçÔes. Para isso, siga as etapas abaixo. No final, disponibilizamos alguns SDKs com um exemplo de código completo para facilitar o processo:

  1. Para extrair o timestamp (ts) e a assinatura do header x-signature, divida o conteĂșdo do header pelo caractere ,, o que resultarĂĄ em uma lista de 2 elementos. O valor para o prefixo ts Ă© o timestamp (em milissegundos) da notificação, e v1 Ă© a assinatura encriptada. Seguindo o exemplo apresentado acima, ts=1704908010 e v1=618c85345248dd820d5fd456117c2ab2ef8eda45a0282ff693eac24131a5e839.
  2. Utilizando o template e as descriçÔes 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];
  • ParĂąmetros com sufixo _url sĂŁo provenientes de query params. Exemplo: [data.id_url]. Deve ser substituĂ­do pelo valor correspondente ao ID do evento (data.id). Esse query param poderĂĄ ser encontrado na notificação recebida.
  • [ts_header] representa o valor ts extraĂ­do do header x-signature.
  • [x-request-id_header] deve ser substituĂ­do pelo valor recebido no header x-request-id.
Importante
Se algum dos valores mostrados no modelo acima nĂŁo estiver presente na sua notificação, vocĂȘ deve removĂȘ-lo.
  1. Em Suas integraçÔes, selecione a aplicação integrada e navegue até a seção de Webhooks para visualizar a assinatura secreta gerada.
  2. Crie a contra chave para validação. Para isso, calcule um HMAC (Código de Autenticação de Mensagem Baseado em Hash) utilizando a função de hash SHA256 em base hexadecimal. Utilize a assinatura secreta como chave e o template preenchido com os respectivos valores como mensagem.
          
$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 header, assegurando que correspondam exatamente. Além disso, é possível usar o timestamp extraído do header para comparå-lo com um timestamp gerado no momento do recebimento da notificação. Isso permite estabelecer uma margem de tolerùncia para atrasos no recebimento da mensagem.

Veja exemplos de cĂłdigos completos abaixo:

          
<?php
// Obtain the x-signature value from the header
$xSignature = $_SERVER['HTTP_X_SIGNATURE'];
$xRequestId = $_SERVER['HTTP_X_REQUEST_ID'];

// Obtain Query params related to the request URL
$queryParams = $_GET;

// Extract the "data.id" from the query params
$dataID = isset($queryParams['data.id']) ? $queryParams['data.id'] : '';

// Separating the x-signature into parts
$parts = explode(',', $xSignature);

// Initializing variables to store ts and hash
$ts = null;
$hash = null;

// Iterate over the values to obtain ts and v1
foreach ($parts as $part) {
    // Split each part into key and value
    $keyValue = explode('=', $part, 2);
    if (count($keyValue) == 2) {
        $key = trim($keyValue[0]);
        $value = trim($keyValue[1]);
        if ($key === "ts") {
            $ts = $value;
        } elseif ($key === "v1") {
            $hash = $value;
        }
    }
}

// Obtain the secret key for the user/application from Mercadopago developers site
$secret = "your_secret_key_here";

// Generate the manifest string
$manifest = "id:$dataID;request-id:$xRequestId;ts:$ts;";

// Create an HMAC signature defining the hash type and the key as a byte array
$sha = hash_hmac('sha256', $manifest, $secret);
if ($sha === $hash) {
    // HMAC verification passed
    echo "HMAC verification passed";
} else {
    // HMAC verification failed
    echo "HMAC verification failed";
}
?>

        
          
// Obtain the x-signature value from the header
const xSignature = headers['x-signature']; // Assuming headers is an object containing request headers
const xRequestId = headers['x-request-id']; // Assuming headers is an object containing request headers

// Obtain Query params related to the request URL
const urlParams = new URLSearchParams(window.location.search);
const dataID = urlParams.get('data.id');

// Separating the x-signature into parts
const parts = xSignature.split(',');

// Initializing variables to store ts and hash
let ts;
let hash;

// Iterate over the values to obtain ts and v1
parts.forEach(part => {
    // Split each part into key and value
    const [key, value] = part.split('=');
    if (key && value) {
        const trimmedKey = key.trim();
        const trimmedValue = value.trim();
        if (trimmedKey === 'ts') {
            ts = trimmedValue;
        } else if (trimmedKey === 'v1') {
            hash = trimmedValue;
        }
    }
});

// Obtain the secret key for the user/application from Mercadopago developers site
const secret = 'your_secret_key_here';

// Generate the manifest string
const manifest = `id:${dataID};request-id:${xRequestId};ts:${ts};`;

// Create an HMAC signature
const hmac = crypto.createHmac('sha256', secret);
hmac.update(manifest);

// Obtain the hash result as a hexadecimal string
const sha = hmac.digest('hex');

if (sha === hash) {
    // HMAC verification passed
    console.log("HMAC verification passed");
} else {
    // HMAC verification failed
    console.log("HMAC verification failed");
}

        
          
import hashlib
import hmac
import urllib.parse

# Obtain the x-signature value from the header
xSignature = request.headers.get("x-signature")
xRequestId = request.headers.get("x-request-id")

# Obtain Query params related to the request URL
queryParams = urllib.parse.parse_qs(request.url.query)

# Extract the "data.id" from the query params
dataID = queryParams.get("data.id", [""])[0]

# Separating the x-signature into parts
parts = xSignature.split(",")

# Initializing variables to store ts and hash
ts = None
hash = None

# Iterate over the values to obtain ts and v1
for part in parts:
    # Split each part into key and value
    keyValue = part.split("=", 1)
    if len(keyValue) == 2:
        key = keyValue[0].strip()
        value = keyValue[1].strip()
        if key == "ts":
            ts = value
        elif key == "v1":
            hash = value

# Obtain the secret key for the user/application from Mercadopago developers site
secret = "your_secret_key_here"

# Generate the manifest string
manifest = f"id:{dataID};request-id:{xRequestId};ts:{ts};"

# Create an HMAC signature defining the hash type and the key as a byte array
hmac_obj = hmac.new(secret.encode(), msg=manifest.encode(), digestmod=hashlib.sha256)

# Obtain the hash result as a hexadecimal string
sha = hmac_obj.hexdigest()
if sha == hash:
    # HMAC verification passed
    print("HMAC verification passed")
else:
    # HMAC verification failed
    print("HMAC verification failed")

        
          
import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"fmt"
	"net/http"
	"strings"
)

func main() {
	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		// Obtain the x-signature value from the header
		xSignature := r.Header.Get("x-signature")
		xRequestId := r.Header.Get("x-request-id")

		// Obtain Query params related to the request URL
		queryParams := r.URL.Query()

		// Extract the "data.id" from the query params
		dataID := queryParams.Get("data.id")

		// Separating the x-signature into parts
		parts := strings.Split(xSignature, ",")

		// Initializing variables to store ts and hash
		var ts, hash string

		// Iterate over the values to obtain ts and v1
		for _, part := range parts {
			// Split each part into key and value
			keyValue := strings.SplitN(part, "=", 2)
			if len(keyValue) == 2 {
				key := strings.TrimSpace(keyValue[0])
				value := strings.TrimSpace(keyValue[1])
				if key == "ts" {
					ts = value
				} else if key == "v1" {
					hash = value
				}
			}
		}

		// Get secret key/token for specific user/application from Mercadopago developers site
		secret := "your_secret_key_here"

		// Generate the manifest string
		manifest := fmt.Sprintf("id:%v;request-id:%v;ts:%v;", dataID, xRequestId, ts)

		// Create an HMAC signature defining the hash type and the key as a byte array
		hmac := hmac.New(sha256.New, []byte(secret))
		hmac.Write([]byte(manifest))

		// Obtain the hash result as a hexadecimal string
		sha := hex.EncodeToString(hmac.Sum(nil))

if sha == hash {
    // HMAC verification passed
    fmt.Println("HMAC verification passed")
} else {
    // HMAC verification failed
    fmt.Println("HMAC verification failed")
}

	})
}

        

3. Simular o recebimento da notificação

Para garantir que as notificaçÔes estejam configuradas corretamente, é necessårio simular o recebimento delas. Para isso, siga os seguintes passos:

  1. Após configurar as URLs e os eventos desejados, clique em Salvar para salvar a configuração.
  2. Após isso, clique em Simular para testar se a URL indicada estå recebendo as notificaçÔes corretamente.
  3. Na tela de simulação, selecione a URL a ser testada, podendo ser uma URL de teste ou de produção.
  4. Em seguida, selecione o tipo de evento desejado e insira a identificação que serå enviada no corpo da notificação.
  5. Por fim, clique 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

Durante o processo de criação de pagamentos, preferĂȘncias ou ordens comerciais, Ă© possĂ­vel configurar a URL de notificação de maneira especĂ­fica para cada pagamento, utilizando o campo notification_url e implementando o receptor de notificaçÔes necessĂĄrio.

Importante
Este método não permite configurar notificaçÔes para o tópico de point_integration_wh utilizando este método. Para ativå-lo, utilize as configuraçÔes de Suas integraçÔes .

A seguir, explicamos como realizar esta configuração utilizando nossos SDKs.

  1. No campo notification_url, informe a URL que receberå as notificaçÔes, conforme o exemplo abaixo. Para receber notificaçÔes exclusivamente via Webhooks e não via IPN, adicione o parùmetro source_news=webhooks à notification_url. Por exemplo: https://www.yourserver.com/notifications?source_news=webhooks.
          
<?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)

        
          
accessToken := "{{ACCESS_TOKEN}}"


cfg, err := config.New(accessToken)
if err != nil {
   fmt.Println(err)
   return
}


client := payment.NewClient(cfg)


request := payment.Request{
   TransactionAmount: <transactionAmount>,
   Token: <token>,
   Description: <description>,
   Installments: <installments>,
   PaymentMethodID:   <paymentMethodId>,
   NotificationURL: "https:/mysite.com/notifications/new",
   Payer: &payment.PayerRequest{
      Email: <email>,
      Identification: &payment.IdentificationRequest{
         Type: <type>,
         Number: <number>,
      },
   },
}


resource, err := client.Create(context.Background(), request)
if err != nil {
fmt.Println(err)
}


fmt.Println(resource)

        
          
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 utilizando 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;
 }
?>

Após realizar as configuraçÔes necessårias, a notificação Webhooks serå entregue com formato JSON. Veja o exemplo de notificação do tópico de payments e as descriçÔes das informaçÔes enviadas na tabela abaixo.

Importante
Os pagamentos de teste, criados com credenciais de teste, nĂŁo enviarĂŁo notificaçÔes. A Ășnica maneira de testar o recebimento de notificaçÔes Ă© por meio da Configuração via Suas integraçÔes .

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"
 }
}
AtributoDescriçãoExemplo no JSON
idID de notificação12345
live_modeIndica se a URL informada Ă© vĂĄlidatrue
typeTipo de notificação recebida de acordo com o tópico previamente selecionado (payments, mp-connect, subscription, claim, automatic-payments, etc.)payment
date_createdData de criação do recurso notificado2015-03-25T10:04:58.396-04:00
user_idIdentificador do vendedor44444
api_versionValor que indica a versão da API que envia a notificação.v1
actionEvento notificado, indicando se é uma atualização de recurso ou a criação de um novopayment.created
data.idID do pagamento, do merchant_order ou da reclamação999999999
Importante
Para obter o formato de notificaçÔes para tópicos diferentes de payment, como point_integration_wh, topic_claims_integration_wh e topic_card_id_wh, consulte InformaçÔes adicionais sobre notificaçÔes .

AçÔes necessårias após receber uma notificação

Ao receber uma notificação em sua plataforma, o Mercado Pago aguarda uma resposta para validar se vocĂȘ a recebeu corretamente. Para isso, Ă© necessĂĄrio retornar um status HTTP STATUS 200 (OK) ou 201 (CREATED).

O tempo de espera para a confirmação da recepção das notificaçÔes 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å novas tentativas de envio a cada 15 minutos, até receber uma resposta. Após a terceira tentativa, o prazo serå prorrogado, mas os envios continuarão acontecendo.

Após responder à notificação e confirmar seu recebimento, é possível obter as informaçÔes completas do recurso notificado fazendo uma requisição ao endpoint correspondente da API. Para identificar qual endpoint utilizar, confira a tabela abaixo:

TipoURLDocumentação
paymenthttps://api.mercadopago.com/v1/payments/[ID]Obter pagamento
subscription_preapprovalhttps://api.mercadopago.com/preapproval/searchObter assinatura
subscription_preapproval_planhttps://api.mercadopago.com/preapproval_plan/searchObter plano de assinatura
subscription_authorized_paymenthttps://api.mercadopago.com/authorized_payments/[ID]Obter dados de fatura
point_integration_whhttps://api.mercadopago.com/point/integration-api/payment-intents/{paymentintentid}Obter intenção de pagamento
topic_claims_integration_whhttps://api.mercadopago.com/post-purchase/v1/claims/[claim_id]Obter detalhes da reclamação
topic_merchant_order_whhttps://api.mercadopago.com/merchant_orders/[ID]Obter pedido
topic_chargebacks_whhttps://api.mercadopago.com/v1/chargebacks/[ID]Obter estorno

Com essas informaçÔes, vocĂȘ poderĂĄ realizar as atualizaçÔes necessĂĄrias na sua plataforma como, por exemplo, atualizar um pagamento aprovado.

Painel de notificaçÔes

O painel de notificaçÔes permite ao usuårio visualizar os eventos disparados sobre uma determinada integração, verificar o status e obter informaçÔes detalhadas desses eventos.

Este painel serĂĄ exibido assim que vocĂȘ configurar suas notificaçÔes Webhooks, e vocĂȘ pode acessĂĄ-lo a qualquer momento clicando em Webhooks dentro de Suas integraçÔes.

Entre as informaçÔes disponíveis estão a porcentagem de notificaçÔes entregues, bem como uma visão råpida das URLs e dos eventos configurados.

AlĂ©m disso, vocĂȘ encontrarĂĄ uma lista completa das Ășltimas notificaçÔes enviadas e seus detalhes, como status da entrega (sucesso ou falha), ação (ação associada ao evento disparado), evento (tipo de evento disparado) e data e hora. Se desejar, Ă© possĂ­vel filtrar esses resultados exibidos por status da entrega e por perĂ­odo (data e hora).

paiel de notificaçÔes webhooks

Detalhes do evento

Ao clicar em uma das notificaçÔes listadas, é possível acessar os detalhes do evento. Esta seção fornece mais informaçÔes e permite a recuperação de dados perdidos em caso de falha na entrega da notificação para manter o sistema sempre atualizado.

  • Status: Status do evento junto com o cĂłdigo de sucesso ou erro correspondente.
  • Evento: Tipo de evento disparado, conforme selecionado na configuração das notificaçÔes.
  • Tipo: TĂłpico ao qual o evento disparado pertence, conforme a seleção feita durante a configuração.
  • Data e hora do disparo: Data e hora em que o evento foi disparado.
  • Descrição: Descrição detalhada do evento conforme documentada.
  • ID do disparo: Identificador Ășnico da notificação enviada.
  • Requisição: JSON da requisição correspondente Ă  notificação disparada.

detalhes de notificaçÔes enviadas

Em caso de falha na entrega da notificação, é possível visualizar os motivos e corrigir as informaçÔes necessårias para evitar problemas futuros.