Webhooks - Notifications - Mercado Pago Developers
What are you looking for?

Do not know how to start integrating? 

Check the first steps

Notifications

Webhooks

Webhook (also known as web callback) is a simple method that makes it easy for an app or system to provide real-time information whenever an event happens, that is, it is a way to passively receive data between two systems through an HTTP POST.

Once configured, the Webhook will be sent whenever one or more registered events occur, avoiding a search job every minute in search of an answer and, consequently, a system overload and data loss whenever there is some situation.

After receiving a notification on your platform, Mercado Pago will wait for a response to validate that you received it correctly.

Importante
Webhooks notifications can be configured for one or more applications created in your Dashboard.

Prerequisites

Before setting up Webhooks notifications for Wallet Connect, consider the requirements listed below.

RequirementDescription
SSL certificateProtocol that allows you to establish secure communications over the Internet for activities such as browsing, email, and other data transfers.
Request responseThe endpoint must return a 2XX response code to acknowledge receipt. All response codes outside of 2XXs will trigger exponential retries from Mercado Pago.
TimeoutTo avoid timeout issues, the integrator’ application must return a response before triggering complex logic on its side.
Permission requestIn order to be able to whitelist requests via DNS, requests will come through the api.mercadopago.com endpoint. The integrator must disable CSRF (Cross-site request forgery) for api.mercadopago.com, which will allow Mercado Pago requests.

Types of events

There are three different types of events that allow you to receive notifications. These events refer to the update and/or cancellation of an agreement.

User confirmation of the agreement.

From this event, the integrator is notified when a user confirms the agreement.

For this, send a GET request to the endpoint /v2/wallet_connect/agreements/{agreement_id} to obtain the agreement_code and external_flow_id. This will allow to proceed with the creation of the Payer token for payment creation.

See below an example of the code with the information sent at the time of the 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"
    }
}'


        

Cancellation of agreement between integrator and Mercado Pago

In this case, the user has the possibility to unsubscribe from an agreement, which causes the existing contract to be cancelled. When this happens, the payer_token is invalidated and no further charges are made to the user. If the integrator makes new collection attempts, it will be rejected.

Important
If new attempts to charge are made, they will be rejected.

Check below a code example with the information sent at the time of the 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"
  }
}'



        

Agreement payment method update

In this case, the user can add or update a secondary payment method (by default, Mercado Pago account money is the first payment method).

Based on payment statuses, it is possible to detect rejected payments and notify the user so that they can perform the update or add a secondary payment method.

Check below a code example with the information sent at the time of the 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"
    }
}'


        

In the table below you can check more details about the possible values ​​that are sent in the body of the request for cancellation and update of the payment method of an agreement.

FieldValueTypeDescription
idUUID/NumberStringUnique event ID. This ID prevents duplicate messages from the integrator side.
typewallet_connectStringRepresents events about the agreement between the integrator and the Mercado Pago user. This value will always be wallet_connect.
entityagreementStringEntity related to the event. The value will always be agreement.
actionpayment_method.updatedString- Indicates that the secondary payment method associated with the contract has been updated.
- Can be used by the seller as a way to know if a new charge should be made.
actionstatus.updatedString- Indicates that the contract was canceled or confirmed by the user.
- It can be used by the integrator to know if the user has confirmed the agreement or if it was canceled and new charges should not be made.
date{{action_date}}DateAn approximate date (in Zulu format) associated with the event.
data{ id: {{agreement_id}}, status: {{agreement_status}} }id: String status: StringThis field can provide extra details about the event based on type and action.
model_version1IntegerWebhook body template version. It will always be 1.
version0IntegerVersion to identify duplicates within the same id.

Configuration

The configuration Webhooks configuration is done through the Dashboard. Below we will explain how to indicate the URLs that will be notified and how to configure the events for which notification will be received.

webhooks

  1. If you still don't have an application created, access your Dashboard and click Enter to login if you haven't already be logged in.
  2. With the application created, go to the Webhooks Notifications tab in your Dashboard and configure the URLs of production and test from which notifications will be received.
  3. You will also be able to experiment and test if the indicated URL is receiving notifications correctly, being able to verify the request, the response given by the server and the description of the event.
  4. If you need to identify multiple accounts, at the end of the indicated URL you can indicate the parameter ?customer=(sellername) endpoint to identify the sellers.
  5. Next, select the Wallet Connect event that you will receive notifications from in json format via an HTTP POST to the URL specified above. An event is any type of update to the reported object, including status or attribute changes. See the events that can be configured in the table below.
Notification typeActionDescription
Agreement confirmationstatus.updatedThe user confirmed an agreement.
Agreement cancellationstatus.updatedAgreement between the integrator and the user of Mercado Pago was canceled by the user.
Payment method updatepayment_method.updatedPayment method updated by the user.