# 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.
{/* AUTO-GENERATED by @emisso/codegen. DO NOT EDIT. */}
| | |
| ------------------- | ------------------------------------------------------------------ |
| **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`](/docs/referencia/conexiones/estado-consultar).
## Qué hace [#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 [#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
```json
{
"$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 [#ejemplo]
```bash title="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"}}'
```
```json title="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):**
```json
{
"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 [#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í | El detalle del estado ('accredited', 'partially\_refunded'…). null si no vino. |
| `pagos[].fechaCreacion` | string | sí | Cuándo se creó el pago (ISO 8601, UTC). | |
| `pagos[].fechaAprobacion` | string | null | sí | Cuándo se aprobó (ISO 8601, UTC). null si Mercado Pago no la informó. |
| `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í | Cuándo Mercado Pago libera o liberó el dinero (ISO 8601, UTC). null si Mercado Pago no la informó. |
| `pagos[].estadoLiberacion` | string | null | sí | El estado de liberación del dinero según Mercado Pago. null si no vino. |
| `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í | 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. |
| `pagos[].montoNetoRecibido` | string | null | sí | 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. |
| `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í | 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. |
| `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í | El medio de pago ('visa', 'account\_money'…). |
| `pagos[].tipoMedioPago` | string | null | sí | El tipo de medio ('credit\_card', 'debit\_card', 'account\_money'…). |
| `pagos[].tipoOperacion` | string | null | sí | El tipo de operación según Mercado Pago ('regular\_payment', 'money\_transfer'…). |
| `pagos[].cuotas` | entero | null | sí | En cuántas cuotas pagó el comprador. null si no vino. |
| `pagos[].referenciaExterna` | string | null | sí | La referencia que puso el integrador de la venta (por ejemplo un número de orden), tal cual. Puede no existir. |
| `pagos[].descripcion` | string | null | sí | La descripción del pago, tal cual. Puede no existir. |
| `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í | 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ó. |
| `cobertura.hasta` | string | null | sí | 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. |
| `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í | Cuándo terminó la última sincronización que guardó datos (ISO 8601). null si nunca. |
| `cursor` | string | null | sí | 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. |
JSON Schema de salida
```json
{
"$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 [#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](/docs/referencia/errores).
## Próximos pasos [#próximos-pasos]
* [`mercadopago.conexion.sincronizar`](/docs/referencia/mercadopago/conexion-sincronizar): la tool que escribe los datos que esta lectura devuelve.
* [Sincronizar y consultar](/docs/conceptos/sincronizar-consultar): por qué leer datos reales son dos pasos.