Additional information about notifications
In this documentation, you will find additional information about notifications, including special considerations depending on the solution you have integrated, specific aspects of certain topics, and examples of particular notifications for your reference.
Card Updater
Card Updater is a feature for product integrations with recurring payments that updates card data, whether expired or incorrect, and updates this information within Mercado Pago.
This process is triggered by a rejected payment, where the verification done by Card Updater can either generate a new card_id
for a customer (in cases of data entry errors or card changes) or keep the previously generated card_id
while updating the database with the correct card information.
In either case, a Webhooks notification will be sent as shown below:
json
{
"action": "card.updated",
"api_version": "v1",
"application_id": 8339021212080291,
"data": {
"customer_id": "12345678-aluyasdhfyt",
"new_card_id": 50000102202,
"old_card_id": 50000006036
},
"date_created": "2024-01-11T15:23:53-03:00",
"id": "a47fc06844bf4e418a03aeab1479c496",
"live_mode": true,
"type": "automatic-payments",
"user_id": 1197520450,
"version": 1
}
Field | Description |
action | card.updated is the only possible value and indicates when a customer's card was updated. |
application_id | Identifier of the application being notified. |
data | This field contains the update details, such as the customer_id (customer identifier), the new card_id , and the old card_id . If a new card_id is not created, the original one is resent. |
date_created | Creation date of the notification. |
id | Exclusive identifier of the event, prevents duplicate messages. |
live_mode | Indicates if the informed URL is valid. |
type | This value will always be automatic-payments . |
user_id | Identifier of the user to whom the notification is sent. |
Subscriptions
To activate notifications for your Subscriptions integration, you should keep in mind:
- If you have integrated Subscriptions with associated plans, you must activate the
subscription_preapproval_plan
topic to receive alerts about the creation or update of a Plan. - If you have integrated Subscriptions without associated plans, you must activate the
subscription_preapproval
topic to receive alerts about the creation or update of a pending payment subscription, or thesubscription_authorized_payment
topic for updates on authorized payment subscriptions. - In all cases, you should also activate the payments topic, which will allow you to receive notifications about payments associated with those subscriptions when they are made.
Checkout Pro
If you have integrated with Checkout Pro and want to receive notifications, you should keep in mind:
- Activating the
merchant_orders
topic will allow you to receive alerts about the creation and updates of orders. - Additionally, activating the
payments
topic will be useful for keeping your database up to date, as it will notify you about updates to the payments corresponding to those generated orders.
Fraud alerts
If a fraud alert is detected, and you have the stop_delivery_op_wh
topic activated, you will receive a notification like the following:
json
{
"action": "Created",
"api_version": "v1",
"data": {
"description": "desc",
"merchant_order": 249940988000,
"payment_id": 58980959081,
"site_id": "MLA"
},
"date_created": "2022-07-23T23:03:5704:00",
"id": "58980959081",
"live_mode": true,
"type": "stop_delivery_op_wh",
"user_id": 224403329,
"version": 1
}
It includes the details of the order that triggered the alert, under the merchant_order parameter, and the payment_id associated with the payment. With this information, you should proceed to cancel the order without delivering it by making a requisition to the cancellations API.
Please note that this type of notification does not adhere to the usual retry logic. If you do not respond with an HTTP STATUS 200 (OK)
or 201 (CREATED)
upon receipt, the notification will be lost and will not be resent.
Claims
In cases where notifications for the topic topic_claims_integration_wh
have been activated, a Webhooks notification will be sent when a claim or chargeback is initiated, as shown below:
json
{
"action": "Created",
"api_version": "v1",
"data": {
"description": "desc",
"merchant_order": 249940988000,
"payment_id": 58980959081,
"site_id": "MLA"
},
"date_created": "2022-07-23T23:03:5704:00",
"id": "58980959081",
"live_mode": true,
"type": "stop_delivery_op_wh",
"user_id": 224403329,
"version": 1
}
Field | Description |
action | Notification event, indicating whether it is the creation of a resource or its update. |
api_version | Value indicating the API version sending the notification. |
data.id | Unique identifier of the claim or chargeback. |
data.resource | Type of notification received. In this case, it indicates notifications related to claims. |
date_created | Notification creation date. |
id | Received notification identifier. |
live_mode | Indicates if the provided URL is valid. |
type | Type of notification received, according to the previously selected topic. In this case, it will always be claim . |
user_id | User identifier for whom the notification is sent. |
Chargebacks
In cases where notifications for the topic topic_chargebacks_wh
have been activated, a Webhooks notification will be sent when a chargeback is initiated or its status is changed, as shown below:
json
{
"actions":["changed_case_status"],
"api_version":"v1",
"application_id":9007201037432480,
"data":{
"checkout":"PRO",
"date_updated":"0001-01-01T00:00:00Z",
"id":217000061307271000,
"payment_id":81034165129,
"product_id":"BC32A57TRPP001U8NHHG",
"site_id":"MLA",
"transaction_intent_id":""
},
"date_created":"2024-07-02T22:03:24-04:00",
"id":114544942708,
"live_mode":true,
"type":"topic_chargebacks_wh",
"user_id":425424311,
"version":1720427447
}
Offline payment methods
If you have integrated payments with offline payment methods and configured your notifications with the payments topic, you should know that all changes in payment status will be notified to you.
This also applies to expired payments: their status will change from pending
to cancelled
, and the corresponding alert will be sent to your system.
QR Code
If you integrated with QR Code and wish to receive notifications, please note the following:
- Webhooks notifications cannot be configured through Your integrations. You must set them up when creating a payment.
- Consequently, it is not possible to validate the origin of notifications using the
x-Signature
header. For alternative methods to verify the origin of these notifications, please contact Mercado Pago Support. - The activation of the
merchant_orders
topic will allow you to receive alerts about order creation and updates. While the topic sends astatus=opened
, it will be the notification withstatus=closed
that will securely certify that the generated order has been paid.
Payment links
It is not possible to configure notifications for Payment links generated through the Mercado Pago Panel.