Configure notifications
Webhooks notifications, also known as web callbacks, are an effective method that allows Mercado Pago servers to send information in real time when a specific event related to your integration occurs. Instead of your system constantly querying for updates, Webhooks allow the passive and automatic transmission of data between Mercado Pago and your integration through an HTTPS POST request, optimizing communication and reducing server load.
Below, you'll find a step-by-step guide to receive payment notifications in your Payouts integrations. Once configured, Webhook notifications will be sent whenever there is any update on the reported topic, including the creation of a transaction or status changes during processing.
Through the config.notification_url field, you can set up Webhook notifications when making the call to create a payout. Simply fill it with the URL where you want to receive the updates.
notification_url value, such as localhost/ or 127.0.0.1, with or without a specified port. Use a server with a named domain (DNS) or an externally accessible development IP so that Mercado Pago can send notifications correctly.curl--data '{ ... "config": { "notification_url": "https://link-your-webhook-notification.com" } ... }'
| Field | Type | Description | Required | Example |
config | Object | Body. Object that groups the payout settings. | Required for notifications | - |
config.notification_url | String | Body. URL where you will receive notifications of transaction-related events, such as status changes. | Required for notifications | https://link-your-webhook-notification.com |
See below examples of the messages returned when an event occurs.
Message when creating a transaction:
json{ "created_date": "2026-01-29T15:20:25.470+00:00", "external_reference": "MP0197", "id": "TOP01KKYN1QY2SS1MKAY4E5KM8WZ6", "last_updated_date": "2026-01-29T15:20:25.470+00:00", "payout": { "external_reference": "MP0197", "id": "POP01KKCFKH9J2C8TQSQZM4R3Z22C", "notification_url": "https://link-your-webhook-notification.com" }, "status": "approved" }
Message when updating a transaction:
json{ "created_date": "2026-01-29T15:20:25.470+00:00", "external_reference": "MP0197", "id": "TOP01KKYN1QY2SS1MKAY4E5KM8WZ6", "last_updated_date": "2026-01-29T15:20:25.470+00:00", "payout": { "external_reference": "MP0197", "id": "POP01KKCFKH9J2C8TQSQZM4R3Z22C", "notification_url": "https://link-your-webhook-notification.com" }, "status": "success", "status_detail": "accredited" }
The payout.id attribute corresponds to the payout ID, id is the transaction ID, and status indicates the transaction's current processing status.
When you receive a notification on your platform, Mercado Pago expects a response to validate that the reception was correct. Return an HTTP STATUS 200 (OK) or 201 (CREATED). The waiting time for this confirmation is 22 seconds. If this response is not sent, the system will understand that the notification was not received and will make a new attempt to send it every 15 minutes until it receives the response. After the third attempt, the deadline is extended, but the deliveries continue to happen.
After responding to the notification and confirming its receipt, you can obtain all the information about the notified resource by sending a request to the endpoint /v1/payouts/{payout_id}/transactions/{transaction_id}GET. With this information, you'll be able to make the necessary updates.