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.

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.

Antes de configurar as notificações Webhooks para Wallet Connect considere os requisitos listados abaixo.

Existem três tipos diferentes de eventos que permitem o recebimento de notificações. Esses eventos referem-se à atualização e/ou cancelamento de uma vinculação.

A partir deste evento, o integrador é notificado quando um usuário confirma a vinculação.

Para isso, envie um GET ao endpoint /v2/wallet_connect/agreements/{agreement_id} para obter o agreement_code e external_flow_id. Isso permitirá seguir com a criação do token de pagamento para a criação dos pagamentos.

Veja abaixo um exemplo de código com as informações enviadas no momento da requisição.

curl
Copiar
{
  "id": "22abcd1235ed497f945f755fcaba3c6c",
  "type": "wallet_connect",
  "entity": "agreement",
  "action": "status.updated",
  "date": "2021-09-30T23:24:44Z",
  "model_version": 1,
  "version": 0,
  "data": {
    "id": "22abcd1235ed497f945f755fcaba3c6c",
    "status": "confirmed_by_user"
  }
}

Neste evento, o usuário tem a possibilidade de se descadastrar de uma vinculação, o que faz com que a vinculação existente seja cancelada. Quando isso acontece, o payer_token é invalidado e nenhuma outra cobrança é feita ao usuário.

Veja abaixo um exemplo de código com as informações enviadas no momento da requisição.

curl
Copiar
{
  "id": "22abcd1235ed497f945f755fcaba3c6c",
  "type": "wallet_connect",
  "entity": "agreement",
  "action": "status.updated",
  "date": "2021-09-30T23:24:44Z",
  "model_version": 1,
  "version": 0,
  "data": {
    "id": "22abcd1235ed497f945f755fcaba3c6c",
    "status": "cancelled"
  }
}

Neste caso, o usuário pode adicionar ou atualizar uma forma de pagamento secundária (por padrão, dinheiro em conta Mercado Pago é a primeira forma de pagamento).

Com base nos status de pagamento, é possível detectar pagamentos rejeitados e notificar o usuário para que ele possa realizar a atualização ou adicionar uma forma de pagamento secundária.

Veja abaixo um exemplo de código com as informações enviadas no momento da requisição.

curl
Copiar
{
  "id": "22abcd1235ed497f945f755fcaba3c6c",
  "type": "wallet_connect",
  "entity": "agreement",
  "action": "payment_method.updated",
  "date": "2021-09-30T23:24:44Z",
  "model_version": 1,
  "version": 0,
  "data": {
    "id": "22abcd1235ed497f945f755fcaba3c6c"
  }
}

Na tabela abaixo mostramos com mais detalhes os possíveis valores que são enviados no corpo da requisição do cancelamento e atualização do meio de pagamento de uma vinculação.

A configuração das Webhooks é feita através do Painel do desenvolvedor. Abaixo explicaremos como indicar as URLs que serão notificadas e como configurar os eventos dos quais se receberá a notificação.

1. Se ainda não tiver uma aplicação criada, acesse seu Painel do desenvolvedor e clique em Entrar para fazer seu login caso ainda não esteja logado.
2. Com a aplicação criada, acesse a aba Notificações Webhooks em seu Painel do desenvolvedor e configure as URLs de produção e teste da qual serão recebidas as notificações.
3. Você também poderá experimentar e testar se a URL indicada está recebendo as notificações corretamente, podendo verificar a solicitação, a resposta dada pelo servidor e a descrição do evento.
4. Caso seja necessário identificar múltiplas contas, no final do URL indicada você poderá indicar o parâmetro ?customer=(sellername) endpoint para identificar os vendedores.
5. Em seguida, selecione o evento Wallet Connect do qual 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.