Consultar pagos recibidos en Mercado Pago

Lee los pagos que RECIBIÓ la cuenta de Mercado Pago de esta conexión, YA sincronizados: estado, monto, moneda, lo reembolsado, el neto recibido, las comisiones y cuándo se libera el dinero.


Tool ID	`mercadopago.pagos.consultar`
Nombre MCP	`mercadopago__pagos__consultar`
Conector	`mercadopago`
Plano	`action`
Lee el alcance	`pagos` (debe estar habilitado en la conexión)
Scope (permiso)	`mercadopago:read`
Auth	`none`
Versión	`1`
Sensible	sí
Deprecado	no
Comportamiento	readOnly=true, destructive=false, idempotent=true, openWorld=false

Requiere conexión. Indica cuál en cada llamada: header X-Connect-Connection en REST y campo connectionId en el execute de MCP. No hay resolución implícita, ni siquiera con una sola conexión activa: la conexión es la empresa. El id sale de conexiones.estado.consultar.

Qué hace

Sirve para conciliar ventas y cobros. No es saldo ni cartola: no incluye retiros ni transferencias. Lectura pura: NO contacta a Mercado Pago ni dispara una sincronización. Revisa 'cobertura' antes de concluir que no hay pagos: una lista vacía con 'cobertura.completa' en false no lo prueba. Para traer datos nuevos usa 'mercadopago.conexion.sincronizar'. Pagina con 'cursor'.

Entrada

Campo	Tipo	Requerido	Descripción
`desde`	string `^\d{4}-\d{2}-\d{2}$`	no	Primer día (AAAA-MM-DD, por fecha de creación del pago en hora de Chile). Omítelo para no filtrar.
`hasta`	string `^\d{4}-\d{2}-\d{2}$`	no	Último día, incluido (AAAA-MM-DD, por fecha de creación del pago en hora de Chile). Omítelo para no filtrar.
`estado`	string	no	Filtra por estado de Mercado Pago (por ejemplo 'approved'). Omítelo para ver todos.
`pagoId`	string `^[1-9][0-9]{0,30}$`	no	Trae sólo ese pago, por su id de Mercado Pago (texto).
`cursor`	string	no	Puntero opaco a la página siguiente. Reenvía tal cual el 'cursor' que devolvió la llamada anterior; nunca lo construyas a mano. Omítelo para pedir la primera página.
`limit`	entero 1-500	no · default `100`	Cuántas filas trae la página, entre 1 y 500. Por omisión, 100.

JSON Schema de entrada

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "desde": {
      "description": "Primer día (AAAA-MM-DD, por fecha de creación del pago en hora de Chile). Omítelo para no filtrar.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "hasta": {
      "description": "Último día, incluido (AAAA-MM-DD, por fecha de creación del pago en hora de Chile). Omítelo para no filtrar.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "estado": {
      "description": "Filtra por estado de Mercado Pago (por ejemplo 'approved'). Omítelo para ver todos.",
      "type": "string",
      "minLength": 1,
      "maxLength": 40
    },
    "pagoId": {
      "description": "Trae sólo ese pago, por su id de Mercado Pago (texto).",
      "type": "string",
      "pattern": "^[1-9][0-9]{0,30}$"
    },
    "cursor": {
      "description": "Puntero opaco a la página siguiente. Reenvía tal cual el 'cursor' que devolvió la llamada anterior; nunca lo construyas a mano. Omítelo para pedir la primera página.",
      "type": "string"
    },
    "limit": {
      "default": 100,
      "description": "Cuántas filas trae la página, entre 1 y 500. Por omisión, 100.",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    }
  }
}

Ejemplo

curl

curl -X POST https://connect.emisso.ai/api/v1/tools/mercadopago.pagos.consultar/execute \
  -H "Authorization: Bearer connect_sk_…" \
  -H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \
  -H "Content-Type: application/json" \
  -d '{"input":{"desde":"2026-10-01","hasta":"2026-10-15","estado":"approved"}}'

MCP · meta-tool execute

{
  "tool": "mercadopago.pagos.consultar",
  "params": {
    "desde": "2026-10-01",
    "hasta": "2026-10-15",
    "estado": "approved"
  },
  "connectionId": "conn_9tKfR2mQx4Vb"
}

Salida esperada (200):

{
  "data": {
    "pagos": [
      {
        "pagoId": "1325001234",
        "estado": "approved",
        "estadoDetalle": "accredited",
        "fechaCreacion": "2026-10-14T15:02:11.000Z",
        "fechaAprobacion": "2026-10-14T15:02:13.000Z",
        "fechaActualizacion": "2026-10-14T15:02:13.000Z",
        "fechaLiberacion": "2026-10-28T15:02:13.000Z",
        "estadoLiberacion": "pending",
        "moneda": "CLP",
        "monto": "15990",
        "montoReembolsado": "0",
        "montoNetoRecibido": "15333",
        "comisiones": {
          "estado": "declaradas",
          "totalReceptor": "657",
          "detalle": [
            {
              "tipo": "mercadopago_fee",
              "monto": "657",
              "pagador": "collector"
            }
          ]
        },
        "medioPago": "visa",
        "tipoMedioPago": "credit_card",
        "tipoOperacion": "regular_payment",
        "cuotas": 1,
        "referenciaExterna": "orden-8841",
        "descripcion": "Pedido web",
        "sincronizadoEn": "2026-10-14T16:00:02.000Z"
      }
    ],
    "cobertura": {
      "desde": "2025-10-24T16:00:00.000Z",
      "hasta": "2026-10-14T15:58:00.000Z",
      "completa": true,
      "ventanasSinLeer": 0,
      "sincronizadoEn": "2026-10-14T16:00:02.000Z"
    },
    "cursor": null
  },
  "meta": {
    "request_id": "req_…",
    "tool_id": "mercadopago.pagos.consultar",
    "plane": "action",
    "latency_ms": 24,
    "audit_status": "recorded"
  }
}

Los importes vienen como texto decimal y con su moneda. Una comisión 'desconocidas' no es cero.

Salida

Campo	Tipo	Requerido	Descripción
`pagos`	lista de objeto	sí	Los pagos RECIBIDOS por la cuenta conectada, del más nuevo al más antiguo por fecha de creación.
`pagos[].pagoId`	string	sí	El id del pago en Mercado Pago, como texto: no lo conviertas a número.
`pagos[].estado`	string	sí	El estado del pago con el código de Mercado Pago: 'approved', 'pending', 'rejected', 'refunded', 'charged_back', 'cancelled'…
`pagos[].estadoDetalle`	string	null	sí
`pagos[].fechaCreacion`	string	sí	Cuándo se creó el pago (ISO 8601, UTC).
`pagos[].fechaAprobacion`	string	null	sí
`pagos[].fechaActualizacion`	string	sí	La última actualización que Connect leyó del pago (ISO 8601, UTC). Un pago puede cambiar después (reembolso, contracargo).
`pagos[].fechaLiberacion`	string	null	sí
`pagos[].estadoLiberacion`	string	null	sí
`pagos[].moneda`	string	sí	La moneda del pago (ISO 4217, por ejemplo 'CLP'). Siempre presente.
`pagos[].monto`	string	sí	El monto cobrado, en decimal como texto (por ejemplo "15990" o "1250.5") y en la moneda de 'moneda'. No lo sumes con importes de otra moneda.
`pagos[].montoReembolsado`	string	null	sí
`pagos[].montoNetoRecibido`	string	null	sí
`pagos[].comisiones`	objeto	sí	Las comisiones del pago según Mercado Pago. Revisa 'estado' antes de usar el total: desconocidas NO es cero.
`pagos[].comisiones.estado`	`"declaradas"` · `"sin_comisiones_declaradas"` · `"desconocidas"`	sí	'declaradas': Mercado Pago informó el detalle. 'sin_comisiones_declaradas': informó un detalle vacío y el neto recibido es igual al monto, así que la comisión es cero. 'desconocidas': no la informó o no se pudo leer; NO la trates como cero.
`pagos[].comisiones.totalReceptor`	string	null	sí
`pagos[].comisiones.detalle`	lista de objeto	sí	Cada comisión informada por Mercado Pago. Vacío cuando el estado no es 'declaradas'.
`pagos[].medioPago`	string	null	sí
`pagos[].tipoMedioPago`	string	null	sí
`pagos[].tipoOperacion`	string	null	sí
`pagos[].cuotas`	entero	null	sí
`pagos[].referenciaExterna`	string	null	sí
`pagos[].descripcion`	string	null	sí
`pagos[].sincronizadoEn`	string	sí	Cuándo guardó Connect esta versión del pago (ISO 8601).
`cobertura`	objeto	sí	Qué cubre lo guardado. Payments search NO es una cartola: no incluye retiros, transferencias, saldo ni movimientos que no sean pagos recibidos.
`cobertura.desde`	string	null	sí
`cobertura.hasta`	string	null	sí
`cobertura.completa`	booleano	sí	true sólo si el histórico llegó al límite que permite Mercado Pago (los últimos 12 meses) y no quedó ninguna ventana sin leer. En false, una lista vacía o un total NO prueban que no haya pagos: dilo así.
`cobertura.ventanasSinLeer`	entero	sí	Cuántos tramos de tiempo no se pudieron leer completos (demasiados pagos o resultados inestables). Con alguno, 'completa' es false.
`cobertura.sincronizadoEn`	string	null	sí
`cursor`	string	null	sí

JSON Schema de salida

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "pagos": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "pagoId": {
            "type": "string",
            "description": "El id del pago en Mercado Pago, como texto: no lo conviertas a número."
          },
          "estado": {
            "type": "string",
            "description": "El estado del pago con el código de Mercado Pago: 'approved', 'pending', 'rejected', 'refunded', 'charged_back', 'cancelled'…"
          },
          "estadoDetalle": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "El detalle del estado ('accredited', 'partially_refunded'…). null si no vino."
          },
          "fechaCreacion": {
            "type": "string",
            "description": "Cuándo se creó el pago (ISO 8601, UTC)."
          },
          "fechaAprobacion": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Cuándo se aprobó (ISO 8601, UTC). null si Mercado Pago no la informó."
          },
          "fechaActualizacion": {
            "type": "string",
            "description": "La última actualización que Connect leyó del pago (ISO 8601, UTC). Un pago puede cambiar después (reembolso, contracargo)."
          },
          "fechaLiberacion": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Cuándo Mercado Pago libera o liberó el dinero (ISO 8601, UTC). null si Mercado Pago no la informó."
          },
          "estadoLiberacion": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "El estado de liberación del dinero según Mercado Pago. null si no vino."
          },
          "moneda": {
            "type": "string",
            "description": "La moneda del pago (ISO 4217, por ejemplo 'CLP'). Siempre presente."
          },
          "monto": {
            "type": "string",
            "description": "El monto cobrado, en decimal como texto (por ejemplo \"15990\" o \"1250.5\") y en la moneda de 'moneda'. No lo sumes con importes de otra moneda."
          },
          "montoReembolsado": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Lo reembolsado de este pago, en decimal como texto y en la moneda de 'moneda'. null cuando Mercado Pago no lo informó: null NO es cero."
          },
          "montoNetoRecibido": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Lo que recibe la cuenta después de comisiones, según Mercado Pago, en decimal como texto y en la moneda de 'moneda'. null cuando Mercado Pago no lo informó: null NO es cero."
          },
          "comisiones": {
            "type": "object",
            "properties": {
              "estado": {
                "type": "string",
                "enum": [
                  "declaradas",
                  "sin_comisiones_declaradas",
                  "desconocidas"
                ],
                "description": "'declaradas': Mercado Pago informó el detalle. 'sin_comisiones_declaradas': informó un detalle vacío y el neto recibido es igual al monto, así que la comisión es cero. 'desconocidas': no la informó o no se pudo leer; NO la trates como cero."
              },
              "totalReceptor": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "La suma de las comisiones que paga quien recibe el pago, en decimal como texto y en la moneda de 'moneda'. null cuando Mercado Pago no lo informó: null NO es cero."
              },
              "detalle": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "tipo": {
                      "type": "string",
                      "description": "El tipo de comisión con el nombre de Mercado Pago (por ejemplo 'mercadopago_fee' o 'financing_fee')."
                    },
                    "monto": {
                      "type": "string",
                      "description": "El importe de esa comisión, en decimal como texto (por ejemplo \"15990\" o \"1250.5\") y en la moneda de 'moneda'. No lo sumes con importes de otra moneda."
                    },
                    "pagador": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Quién la paga según Mercado Pago: 'collector' (quien recibe) o 'payer' (quien paga). null si no lo informó."
                    }
                  },
                  "required": [
                    "tipo",
                    "monto",
                    "pagador"
                  ],
                  "additionalProperties": false
                },
                "description": "Cada comisión informada por Mercado Pago. Vacío cuando el estado no es 'declaradas'."
              }
            },
            "required": [
              "estado",
              "totalReceptor",
              "detalle"
            ],
            "additionalProperties": false,
            "description": "Las comisiones del pago según Mercado Pago. Revisa 'estado' antes de usar el total: desconocidas NO es cero."
          },
          "medioPago": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "El medio de pago ('visa', 'account_money'…)."
          },
          "tipoMedioPago": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "El tipo de medio ('credit_card', 'debit_card', 'account_money'…)."
          },
          "tipoOperacion": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "El tipo de operación según Mercado Pago ('regular_payment', 'money_transfer'…)."
          },
          "cuotas": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ],
            "description": "En cuántas cuotas pagó el comprador. null si no vino."
          },
          "referenciaExterna": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "La referencia que puso el integrador de la venta (por ejemplo un número de orden), tal cual. Puede no existir."
          },
          "descripcion": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "La descripción del pago, tal cual. Puede no existir."
          },
          "sincronizadoEn": {
            "type": "string",
            "description": "Cuándo guardó Connect esta versión del pago (ISO 8601)."
          }
        },
        "required": [
          "pagoId",
          "estado",
          "estadoDetalle",
          "fechaCreacion",
          "fechaAprobacion",
          "fechaActualizacion",
          "fechaLiberacion",
          "estadoLiberacion",
          "moneda",
          "monto",
          "montoReembolsado",
          "montoNetoRecibido",
          "comisiones",
          "medioPago",
          "tipoMedioPago",
          "tipoOperacion",
          "cuotas",
          "referenciaExterna",
          "descripcion",
          "sincronizadoEn"
        ],
        "additionalProperties": false
      },
      "description": "Los pagos RECIBIDOS por la cuenta conectada, del más nuevo al más antiguo por fecha de creación."
    },
    "cobertura": {
      "type": "object",
      "properties": {
        "desde": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Desde cuándo están guardados TODOS los pagos de la cuenta, según su fecha de última actualización (ISO 8601). null si nunca se sincronizó."
        },
        "hasta": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Hasta cuándo están guardados todos los pagos (ISO 8601). Lo posterior aún no se lee: no es saldo ni movimiento en tiempo real."
        },
        "completa": {
          "type": "boolean",
          "description": "true sólo si el histórico llegó al límite que permite Mercado Pago (los últimos 12 meses) y no quedó ninguna ventana sin leer. En false, una lista vacía o un total NO prueban que no haya pagos: dilo así."
        },
        "ventanasSinLeer": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "Cuántos tramos de tiempo no se pudieron leer completos (demasiados pagos o resultados inestables). Con alguno, 'completa' es false."
        },
        "sincronizadoEn": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Cuándo terminó la última sincronización que guardó datos (ISO 8601). null si nunca."
        }
      },
      "required": [
        "desde",
        "hasta",
        "completa",
        "ventanasSinLeer",
        "sincronizadoEn"
      ],
      "additionalProperties": false,
      "description": "Qué cubre lo guardado. Payments search NO es una cartola: no incluye retiros, transferencias, saldo ni movimientos que no sean pagos recibidos."
    },
    "cursor": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Puntero a la página siguiente. Si viene distinto de null hay más filas: vuelve a llamar reenviándolo tal cual en 'cursor'. Un null significa que no queda nada por traer."
    }
  },
  "required": [
    "pagos",
    "cobertura",
    "cursor"
  ],
  "additionalProperties": false
}

Errores de esta tool

Código	HTTP	Reintentable	Qué hacer
`connection_disabled`	403	no	Reactívala en /connections o usa otra conexión del mismo sistema.
`connection_not_found`	404	no	Usa uno de los connectionId que lista el error, o revisa la conexión en /connections. No hace falta reactivar nada.
`alcance_not_enabled`	403	no	Habilita el alcance en /connections o quítalo del input de la sincronización.

Toda llamada puede devolver además los códigos transversales (validation_error, unauthorized, scope_not_granted, rate_limited, entre otros): el detalle vive en el catálogo de errores.

Próximos pasos

mercadopago.conexion.sincronizar: la tool que escribe los datos que esta lectura devuelve.
Sincronizar y consultar: por qué leer datos reales son dos pasos.