# API bancario (BaaS)

> Herramientas del MCP para consultar el API bancario de Tilopay: cuentas, saldos, pagos y estados de cuenta. Se activan bajo solicitud y sólo para usuarios con credenciales del API bancario.

- kind: mcp-tool
- status: stable
- access: write
- last_verified: 2026-09-03
- url: https://www.tilopay.com/developers/agentes/mcp/api-bancario

<Callout type="warn">
**Estas herramientas no vienen activadas.** Se habilitan **bajo solicitud** y sólo funcionan
para usuarios con **credenciales del API bancario de Tilopay** registradas por Tilopay del lado
del servidor. Con el acceso MCP estándar el grupo no aparece; y si la herramienta se invoca sin
esas credenciales, responde que no existen. Para pedirlo, usá el
[formulario de solicitud](/developers/agentes/mcp#solicitud) e indicá que necesitás el API
bancario.
</Callout>

## Qué cubre [#que-cubre]

Once herramientas de consulta sobre el [API bancario](/developers/api-bancario): contextos
(assignments), diagnóstico de credenciales, cuentas, saldos, pagos, estados de cuenta y un
informe analítico de pagos.

**Ninguna de estas herramientas inicia, aprueba ni revierte transferencias.** Sólo extraen
información. La única que no es de lectura pura es `baas_request_statement`, que genera un
documento de consulta: no mueve dinero.

Las cuentas se identifican con `accountType: "IBAN"` más `accountValue`, las fechas son RFC 3339
(`2026-01-01T00:00:00Z`) y `assignmentId` se envía únicamente cuando el usuario tiene varios
contextos.

## Herramientas [#herramientas]

> Estas herramientas se activan bajo solicitud y sólo funcionan para usuarios con credenciales del API bancario de Tilopay. No forman parte del acceso MCP por defecto: Tilopay habilita el grupo caso por caso. Requiere: Credenciales del API bancario de Tilopay registradas por Tilopay para ese usuario.

### Contextos (assignments) del API bancario [#baas-list-assignments]

- `baas_list_assignments`
- Acceso: Sólo lectura

Lista los contextos tenant/cuenta (assignments) disponibles para las credenciales del API bancario del usuario. Úsalo cuando otra herramienta pida assignmentId.

**Parámetros**

Sin parámetros.

**Devuelve**

`{ assignments[] }`

assignments = contextos disponibles con assignment_id, tenant_code, owner_type, country_code y status.

### Diagnóstico del API bancario [#baas-diagnostics]

- `baas_diagnostics`
- Acceso: Sólo lectura

Verifica las credenciales del API bancario del usuario, el login, el intercambio de token y el acceso a cuentas. Úsalo cuando una consulta falle.

**Parámetros**

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `assignmentId` | string | — | Contexto (assignment) del API bancario; se envía sólo cuando hay varios |

**Devuelve**

`{ checks[], failed }`

checks = una fila por verificación (credenciales, login + assignments, cuentas) con ok y detalle; failed = cuántas fallaron. El correo de la credencial se devuelve enmascarado.

### Listar cuentas del API bancario [#baas-list-accounts]

- `baas_list_accounts`
- Acceso: Sólo lectura
- Operación del API: `GET /api/public/v1/accounts` — https://www.tilopay.com/developers/api-bancario/cuentas

Lista las cuentas accesibles del API bancario, sin saldos: tipo de identificador, valor y moneda.

**Parámetros**

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `accountType` | string | — | Filtro por esquema (IBAN) |
| `accountValue` | string | — | Filtro por identificador |
| `limit` | integer | — | Tamaño de página, entre 1 y 100 |
| `cursor` | string | — | Cursor de la página anterior |
| `assignmentId` | string | — | Contexto (assignment) del API bancario; se envía sólo cuando hay varios |

**Devuelve**

`{ result }`

result = respuesta del API bancario tal cual.

### Saldos de las cuentas del API bancario [#baas-list-balances]

- `baas_list_balances`
- Acceso: Sólo lectura
- Operación del API: `GET /api/public/v1/accounts/balances` — https://www.tilopay.com/developers/api-bancario/cuentas

Lista los saldos en tiempo real de las cuentas accesibles: cuenta, montos y fecha de corte.

**Parámetros**

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `accountType` | string | — | Filtro por esquema (IBAN) |
| `accountValue` | string | — | Filtro por identificador |
| `limit` | integer | — | Tamaño de página, entre 1 y 100 |
| `cursor` | string | — | Cursor de la página anterior |
| `assignmentId` | string | — | Contexto (assignment) del API bancario; se envía sólo cuando hay varios |

**Devuelve**

`{ result }`

result = respuesta del API bancario tal cual.

### Saldo de una cuenta [#baas-get-balance]

- `baas_get_balance`
- Acceso: Sólo lectura
- Operación del API: `GET /api/public/v1/accounts/balance` — https://www.tilopay.com/developers/api-bancario/cuentas

Obtiene el saldo actual de una cuenta del API bancario identificada por IBAN.

**Parámetros**

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `accountType` | string (IBAN) | — | Esquema del identificador de la cuenta (IBAN) |
| `accountValue` | string | sí | Identificador de la cuenta (IBAN) |
| `assignmentId` | string | — | Contexto (assignment) del API bancario; se envía sólo cuando hay varios |

**Devuelve**

`{ result }`

result = respuesta del API bancario tal cual.

### Listar pagos del API bancario [#baas-list-payments]

- `baas_list_payments`
- Acceso: Sólo lectura
- Operación del API: `GET /api/public/v1/transactions/payments` — https://www.tilopay.com/developers/api-bancario/pagos

Consulta, sólo lectura, los pagos de una cuenta propia identificada por IBAN, con filtros de fecha, estado, moneda, método y dirección. Paginación por cursor.

**Parámetros**

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `accountType` | string (IBAN) | — | Esquema del identificador de la cuenta (IBAN) |
| `accountValue` | string | sí | Identificador de la cuenta (IBAN) |
| `dateFrom` | string | — | Desde, RFC 3339 (2026-01-01T00:00:00Z) |
| `dateTo` | string | — | Hasta, RFC 3339 |
| `status` | string (pending | processing | confirmed | posted | failed) | — | Estado público del pago |
| `currency` | string | — | Moneda ISO 4217 (CRC, USD) |
| `paymentMethodCode` | string (PIN | SINPE_MOVIL) | — | Método de pago |
| `direction` | string (OUT | IN) | — | OUT = envío, IN = recibido |
| `clientReference` | string | — | Referencia del comercio |
| `limit` | integer | — | Tamaño de página, máximo 100 (por defecto 20) |
| `cursor` | string | — | Cursor de la página anterior |
| `assignmentId` | string | — | Contexto (assignment) del API bancario; se envía sólo cuando hay varios |

**Devuelve**

`{ result }`

result = respuesta del API bancario tal cual, con su cursor de paginación.

### Buscar un pago [#baas-search-payment]

- `baas_search_payment`
- Acceso: Sólo lectura
- Operación del API: `POST /api/public/v1/transactions/payments/search` — https://www.tilopay.com/developers/api-bancario/pagos

Busca un pago dentro de una cuenta por exactamente uno de: paymentId (UUID), publicId (número) o clientReference. Si se envía más de uno, la herramienta devuelve error.

**Parámetros**

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `accountType` | string (IBAN) | — | Esquema del identificador de la cuenta (IBAN) |
| `accountValue` | string | sí | Identificador de la cuenta (IBAN) |
| `paymentId` | string | — | UUID interno del pago |
| `publicId` | string | — | Identificador público numérico |
| `clientReference` | string | — | Referencia del comercio |
| `assignmentId` | string | — | Contexto (assignment) del API bancario; se envía sólo cuando hay varios |

**Devuelve**

`{ result }`

result = respuesta del API bancario tal cual.

### Detalle de un pago [#baas-get-payment]

- `baas_get_payment`
- Acceso: Sólo lectura
- Operación del API: `GET /api/public/v1/transactions/payments/{payment_id}` — https://www.tilopay.com/developers/api-bancario/pagos

Obtiene el detalle de un pago del API bancario por su UUID interno, sólo lectura.

**Parámetros**

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `paymentId` | string | sí | UUID interno del pago |
| `assignmentId` | string | — | Contexto (assignment) del API bancario; se envía sólo cuando hay varios |

**Devuelve**

`{ result }`

result = respuesta del API bancario tal cual.

### Solicitar un estado de cuenta [#baas-request-statement]

- `baas_request_statement`
- Acceso: Escritura
- Operación del API: `POST /api/public/v1/accounts/statements` — https://www.tilopay.com/developers/api-bancario/cuentas

Solicita la generación de un estado de cuenta para una cuenta del API bancario, con rango máximo de 60 días. No mueve dinero: genera un documento de consulta y devuelve request_id con status PENDING.

**Parámetros**

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `accountType` | string (IBAN) | — | Esquema del identificador de la cuenta (IBAN) |
| `accountValue` | string | sí | Identificador de la cuenta (IBAN) |
| `dateFrom` | string | sí | Desde, RFC 3339 (2026-01-01T00:00:00Z) |
| `dateTo` | string | sí | Hasta, RFC 3339, como máximo 60 días después de dateFrom |
| `assignmentId` | string | — | Contexto (assignment) del API bancario; se envía sólo cuando hay varios |

**Devuelve**

`{ result }`

result = respuesta del API bancario con request_id y status. La herramienta solicita el documento sin notificación por correo.

### Estado de la solicitud de estado de cuenta [#baas-get-statement-status]

- `baas_get_statement_status`
- Acceso: Sólo lectura
- Operación del API: `GET /api/public/v1/accounts/statements/{request_id}` — https://www.tilopay.com/developers/api-bancario/cuentas

Consulta el estado de una solicitud de estado de cuenta. Cuando está DONE incluye el enlace de descarga firmado y su vencimiento.

**Parámetros**

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `requestId` | string | sí | request_id devuelto al solicitar el estado de cuenta |
| `assignmentId` | string | — | Contexto (assignment) del API bancario; se envía sólo cuando hay varios |

**Devuelve**

`{ result }`

result = respuesta del API bancario tal cual.

### Analista de pagos del API bancario [#baas-analyze-payments]

- `baas_analyze_payments`
- Acceso: Sólo lectura

Analiza, sólo lectura, los pagos de una cuenta en un rango de fechas y devuelve un informe en lenguaje natural: éxito, fallas, reversiones, montos netos y recomendaciones. Usa un modelo de lenguaje sobre las cifras calculadas.

**Parámetros**

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `accountType` | string (IBAN) | — | Esquema del identificador de la cuenta (IBAN) |
| `accountValue` | string | sí | Identificador de la cuenta (IBAN) |
| `dateFrom` | string | sí | Desde, RFC 3339 |
| `dateTo` | string | sí | Hasta, RFC 3339 |
| `currency` | string | — | Moneda ISO 4217 |
| `direction` | string (OUT | IN) | — | OUT = envío, IN = recibido |
| `question` | string | — | Enfoque específico del análisis |
| `maxItems` | integer | — | Máximo de pagos a analizar, entre 1 y 1000 (por defecto 300) |
| `assignmentId` | string | — | Contexto (assignment) del API bancario; se envía sólo cuando hay varios |

**Devuelve**

`{ summary }`

summary trae account, range, totals {count, succeeded, failed, reversed, pending, successRate}, byCurrency con succeededAmount, reversedAmount, netAmount y averageTicket, failureReasons y sample. El informe redactado viene en el texto. Si no hay pagos en el rango, avisa y no analiza.