Webhooks - Notificaciones - Mercado Pago Developers
¿Qué documentación quieres buscar?

¿No sabes cómo empezar la integración? 

Accede a los primeros pasos

Notificaciones

Webhooks

Webhook (también conocido como devolución de llamada web) es un método simple que facilita que una aplicación o sistema proporcione información en tiempo real cada vez que ocurre un evento, es decir, es una forma de recibir datos pasivamente entre dos sistemas a través de un HTTP POST.

Una vez configurado, el Webhook se enviará siempre que se produzcan uno o más eventos registrados, evitando un trabajo de búsqueda innecesarios de una respuesta y, en consecuencia, una sobrecarga del sistema y pérdida de datos siempre que se presente alguna situación.

Luego de recibir una notificación en su plataforma, Mercado Pago esperará una respuesta para validar si la recibió correctamente.

Importante
Las notificaciones de webhook se pueden configurar para una o más aplicaciones creadas en su Panel del desarrollador.

Requisitos previos

Antes de configurar las notificaciones de Webhooks para Wallet Connect, considere los requisitos enumerados a continuación.

RequisitoDescripción
Certificado SSLProtocolo que permite establecer comunicaciones seguras en Internet para actividades como navegación, correo electrónico y otras transferencias de datos.
Respuesta al requestEl endpoint debe devolver un código de respuesta 2XX para reconocer la recepción del request. Todos los códigos de respuesta fuera de 2XX activarán reintentos exponenciales de Mercado Pago.
TimeoutPara evitar problemas de timeout, la aplicación debe devolver una respuesta antes de activar una lógica compleja.
Solicitud de permisoPara poder incluir solicitudes en la lista de permisos a través de DNS, las solicitudes llegarán a través del endpoint api.mercadopago.com. El integrador deberá deshabilitar el CSRF (Cross-site request forgery) para api.mercadopago.com, lo que permitirá las solicitudes de Mercado Pago.

Tipos de eventos

Hay tres tipos diferentes de eventos que le permiten recibir notificaciones. Estos eventos se refieren a la actualización y/o cancelación de un contrato.

Confirmación del agreement por parte del usuario.

A partir de este evento, el integrador es notificado cuando un usuario confirma el agreement.

Para esto, envíe un GET al endpoint /v2/wallet_connect/agreements/{agreement_id} para obtener el agreement_code y external_flow_id. Esto permitirá seguir con la creación del Payer token para la creación de los pagos.

A continuación se muestra un ejemplo de código con la información enviada en el momento del request.

          
curl -X POST 'https://api.integrator.com/wallet_connect/events' \
-H 'Content-Type: application/json' \
-d '{
    "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"
    }
}'


        

Cancelación de un agreement entre integrador y Mercado Pago

En este caso, el usuario tiene la posibilidad de darse de baja de un agreement, lo que provoca la cancelación del contrato existente. Cuando esto sucede, el payer_token se invalida y no se realizan más cargos al usuario.

Importante
En caso de que se hagan nuevos intentos de cobro, serán rechazados.

Observa a continuación un ejemplo de código con la información enviada en el momento del request.

          
curl -X POST 'https://api.integrator.com/wallet_connect/events' \
-H 'Content-Type: application/json' \
 -d '{
  "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"
  }
}'



        

Actualización del medio de pago de un agreement

En este caso, el usuario puede agregar o actualizar un medio de pago secundario (por defecto, Account Money de Mercado Pago es el primer medio de pago).

En función de los estados de pago, es posible detectar pagos rechazados y notificar al usuario para que realice la actualización o agregue un medio de pago secundario.

Observa a continuación un ejemplo de código con la información enviada en el momento del request.

          
curl -X POST 'https://api.integrator.com/wallet_connect/events' \
-H 'Content-Type: application/json' \
-d '{
    "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"
    }
}'



        

En la siguiente tabla mostramos con más detalle los posibles valores que se envían en el cuerpo del request de cancelación y actualización del medio de pago de un agreement.

CampoValorTipoDescripción
idUUID/NumberStringID exclusivo del evento. Este ID evita mensajes duplicados del lado del integrador.
typewallet_connectStringRepresenta eventos sobre el agreement entre el integrador y el usuario de Mercado Pago. Este valor siempre será wallet_connect.
entityagreementStringEntidad relacionada con el agreement. El valor siempre será agreement.
actionpayment_method.updatedString- Indica que se ha actualizado el medio de pago secundario asociado al agreement.
- Puede ser utilizado por el vendedor como una forma de saber si se debe realizar un nuevo cargo.
actionstatus.updatedString- Indica que el agreement fue cancelado o confirmado por el usuario.
- Puede ser usado por el integrador para saber si el usuario confirmó el agreement o si fue cancelado y no se deben realizar nuevos cobros.
date{{action_date}}DateUna fecha aproximada (en formato Zulu) asociada con el evento.
data{ id: {{agreement_id}}, status: {{agreement_status}} }id: String status: StringEste campo puede proporcionar detalles adicionales sobre el evento según el tipo y la acción.
model_version1IntegerVersión del modelo del body del webhook. Siempre será 1.
version0IntegerVersión para identificar duplicados dentro del mismo id.

Configuración

La configuración de los webhooks se realiza a través del Dashboard. A continuación explicaremos cómo indicar las URLs que serán notificadas y cómo configurar los eventos para los que se recibirán notificaciones.

webhooks

  1. Si aún no tienes una aplicación creada, accede a tu Dashboard y haz clic en Entrar para iniciar sesión si aún no está conectado.
  2. Con la aplicación creada, ve a la pestaña Notificaciones de Webhooks en tu Panel de control y configura las URLs de producción y prueba de las que se recibirán notificaciones.
  3. También podrás experimentar y probar si la URL indicada está recibiendo notificaciones correctamente, pudiendo verificar la solicitud, la respuesta dada por el servidor y la descripción del evento.
  4. Si necesitas identificar varias cuentas, al final de la URL indicada puedes indicar el parámetro ?customer=(sellername) endpoint para identificar a los vendedores.
  5. Luego seleccione el evento Wallet Connect del que recibirá notificaciones en formato json a través de un HTTP POST a la URL especificada anteriormente. Un evento es cualquier tipo de actualización del objeto informado, incluidos los cambios de estado o atributos. Vea los eventos que se pueden configurar en la siguiente tabla.
Tipo de notificaciónAcciónDescripción
Confirmación del agreementstatus.updatedEl usuario ha confirmado un agreement.
Cancelación del agreementstatus.updatedAgreement entre el integrador y el usuario de Mercado Pago fue cancelado por el usuario.
Actualización de método de pagopayment_method.updatedEl usuario ha actualizado el método de pago de un agreement.