IPN - Notificaciones - Mercado Pago Developers
Developers
Referencia de API
Soporte
Ingresar

    Inicio

    Empieza por aquí

    Cobros online

    Checkout Pro

    Checkout API

    Link de pago

    Marketplace

    Mobile Checkout

    Web Tokenize Checkout

    Pagos presenciales

    Código QR

    Plugins y plataformas

    WooCommerce

    Prestashop

    Magento 2

    Shopify

    VTEX

    SDKs

    Notificaciones

    Webhooks

    IPN

    Gestión de cuenta

    Reportes

    Obtener pagos

    Mejora la aprobación

    Gestión de contracargos

    Devoluciones y cancelaciones

    Requisitos para salir a producción

    Recursos

    Localización

    Changelog

    Status

EN ESTA PÁGINA

Sugiere cambios
Ayúdanos a mejorar la documentación
¿Viste información errónea, te gustaría que expliquemos algo más o que mejoremos nuestras guías? Déjanos tus sugerencias en GitHub.

Notificaciones IPN

Introducción

IPN (Instant Payment Notification) es una notificación que se envía de un servidor a otro mediante una llamada HTTP POST en relación a tus transacciones.

Para recibir las notificaciones de los eventos en tu plataforma, puedes configurar previamente una notification_url a la cual Mercado Pago tenga acceso.

Eventos

Importante
Un evento es cualquier tipo de actualización sobre el objeto notificado, incluyendo cambios de estado o de atributos.

Notificamos eventos referidos a tus órdenes (merchant_orders), pagos recibidos (payment) o contracargos recibidos (chargebacks).

La merchant_orders es una entidad que agrupa tanto pagos como envíos. Tendrás que consultar los datos de las órdenes que te sean notificadas.

Siempre que suceda un evento relacionado a alguno de los recursos mencionados, te enviaremos una notificación usando HTTP POST a la notification_url que especificaste.

Si la aplicación no está disponible o demora en responder más de 22 segundos, Mercado Pago reintentará la notificación mediante el siguiente esquema:

  1. Reintento a los 5 minutos.
  2. Reintento a los 45 minutos.
  3. Reintento a las 6 horas.
  4. Reintento a los 2 días.
  5. Reintento a los 4 días.

Mercado Pago informará a esta notification_url tanto en la creación como actualización de los estados de pagos u ordenes con dos parámetros:

CampoDescripción
topicIdentifica de qué se trata. Puede ser payment, chargebacks o merchant_order
idEs un identificador único del recurso notificado.

Ejemplo: Si configuraste la notification_url: https://www.yoursite.com/notifications, recibirás notificaciones de pago de esta manera: https://www.yoursite.com/notifications?topic=payment&id=123456789

¿Qué debo hacer al recibir una notificación?

Cuando recibas una notificación en tu plataforma, Mercado Pago espera una respuesta para validar que la recibiste correctamente. Para esto, debes devolver un HTTP STATUS 200 (OK) ó 201 (CREATED).

Recuerda que esta comunicación es exclusivamente entre los servidores de Mercado Pago y tu servidor, por lo cual no habrá un usuario físico viendo ningún tipo de resultado.

Luego de esto, puedes obtener la información completa del recurso notificado accediendo a la API correspondiente en https://api.mercadopago.com/:

TipoURLDocumentación
payment/v1/payments/[ID]ver documentación
chargebacks/v1/chargebacks/[ID]-
merchant_orders/merchant_orders/[ID]ver documentación

Con esta información puedes realizar las actualizaciones necesarias en tu plataforma, por ejemplo registrar un pago acreditado o una orden cerrada.

Importante
Ten en cuenta que si se exceden los tiempos de respuesta es posible recibir notificaciones duplicadas de un evento.

Notificaciones de merchant_orders

Si estas integrando pagos presenciales, te recomendamos utilizar notificaciones IPN de topic merchant_order. Para ello, ten en cuenta las siguientes reglas:

  1. El campo status de la merchant_order permanecerá en opened cuando aún no tenga pagos asociados, o los tenga y estén rechazados o aprobados por un monto menor al total de la orden.
  2. El campo status de la merchant_order será closed cuando la suma de los pagos aprobados sea igual o mayor al total de la orden.

Dentro de la orden, en el objeto payments, encontrarás todos los pagos de la misma. Es importante obtener el id de los pagos con status = approved para poder realizar devoluciones.

Importante
Cuando la merchant_order esté en estado closed, revisa que la sumatoria de los pagos en estado approved sea igual o mayor al total de la orden.

Implementa el receptor de notificaciones tomando como ejemplo el siguiente código:

php

<?php
	MercadoPago\SDK::setAccessToken("ENV_ACCESS_TOKEN");

	$merchant_order = null;

	switch($_GET["topic"]) {
		case "payment":
			$payment = MercadoPago\Payment::find_by_id($_GET["id"]);
			// Get the payment and the corresponding merchant_order reported by the IPN.
			$merchant_order = MercadoPago\MerchantOrder::find_by_id($payment->order->id);
			break;
		case "merchant_order":
			$merchant_order = MercadoPago\MerchantOrder::find_by_id($_GET["id"]);
			break;
	}

	$paid_amount = 0;
	foreach ($merchant_order->payments as $payment) {
		if ($payment['status'] == 'approved'){
			$paid_amount += $payment['transaction_amount'];
		}
	}

	// If the payment's transaction amount is equal (or bigger) than the merchant_order's amount you can release your items
	if($paid_amount >= $merchant_order->total_amount){
		if (count($merchant_order->shipments)>0) { // The merchant_order has shipments
			if($merchant_order->shipments[0]->status == "ready_to_ship") {
				print_r("Totally paid. Print the label and release your item.");
			}
		} else { // The merchant_order don't has any shipments
			print_r("Totally paid. Release your item.");
		}
	} else {
		print_r("Not paid yet. Do not release your item.");
	}

?>
Para obtener tu ACCESS_TOKEN, revisa la sección de Credenciales

Búsqueda de la orden

Si estas integrando pagos presenciales, se debe implementar como método de contingencia, la búsqueda de la orden utilizando el external_reference de la misma como criterio de búsqueda.

curl

curl -X GET \
    -H 'Authorization: Bearer $ACCESS_TOKEN' \
    https://api.mercadopago.com/merchant_orders?external_reference=$EXTERNAL_REFERENCE

Más información en la Referencia de API.

Se puede implementar la búsqueda por external_reference de dos formas:

FormasDescripción
ManualEl punto de venta debe incluir un botón para realizar la búsqueda.
AutomáticaPasado un tiempo prudencial sin haber recibido alguna notificación, se comienza una búsqueda de la orden cada un intervalo de, por ejemplo, 5 segundos.

Por cada escaneo del QR se genera una merchant_order distinta. Debe considerarse que si el cliente escanea más de una vez, una orden quedará en open por tiempo indefinido. Debe tomarse la merchant_order con el status = closed para cerrar la transacción.

Si se realiza la búsqueda una vez escaneado el QR, se obtienen todos los datos referidos a la orden:

json

{
  "id": 1126664483,
  "status": "closed",
  "payments": [
     {
      "id": 4996721469,
      "transaction_amount": 4,
      "status": "rejected",
      [...],
    },
     {
      "id": 4996721476,
      "transaction_amount": 4,
      "status": "approved",
      [...], }, 

En caso contrario, la respuesta que se recibe si todavía no se escaneó el QR al cual se publicó la orden será:

json

{
   "elements": null,
   "next_offset": 0,
   "total": 0
 }
Importante
Desde Mercado Pago requerimos para homologar la integración de pagos presenciales que tengan implementada la notificación (IPN) como método principal. La búsqueda de orden por external_reference deberá usarse sólo como contingencia ante el eventual caso que no se reciban notificaciones.

Recibir un solo tipo de notificación

Si quieres recibir solamente las notificaciones de IPN, y no de Webhooks, puedes agregar en la notification_url el parámetro source_news=ipn. Como por ejemplo:

https://www.yourserver.com/notifications?source_news=ipn

El cambio no afecta a los parámetros ya incluidos en la URL.
¿Te resultó útil esta información?

Copyright © 1999-2021 DeRemate.com de Uruguay S.R.L.

Términos y condicionesCómo cuidamos tu privacidad
Partners Mercado Pago

Al navegar en este sitio aceptas las cookies que utilizamos para mejorar tu experiencia. Más información.