# Cuentas del API Bancario

> Operaciones de cuentas del API Bancario: validación, listado, saldos y estados de cuenta.

- kind: api-operation
- status: stable
- api_version: 1.0.0
- last_verified: 2026-09-02
- url: https://www.tilopay.com/developers/api-bancario/cuentas

El grupo `Accounts` cubre la cuenta como recurso: validar una cuenta destino antes de
transferir, listar las cuentas accesibles, consultar saldos y pedir estados de cuenta.

```http
POST /api/public/v1/accounts/validate
GET  /api/public/v1/accounts
GET  /api/public/v1/accounts/balances
GET  /api/public/v1/accounts/balance
POST /api/public/v1/accounts/statements
GET  /api/public/v1/accounts/statements/{request_id}
```

## Reglas del recurso [#reglas]

**Alcance.** El listado devuelve sólo las cuentas que autoriza el token; no se envía
`tenant_id` ni `owner_id` como parámetro.

**Validación previa.** Validá la cuenta destino antes de crear un pago: la operación
confirma que la cuenta existe y es apta, y devuelve los datos del titular que el servicio
expone.

**Estados de cuenta asincrónicos.** La generación se solicita con un `POST` que acepta
`Idempotency-Key` y devuelve un `request_id`; después consultás ese `request_id` hasta que
el resultado esté disponible. Ver
[reintentos seguros](/developers/api-bancario/convenciones#reintentos).

**Paginación.** `GET /api/public/v1/accounts` y `GET /api/public/v1/accounts/balances`
usan `limit` y `offset`, y devuelven `pagination` con `limit`, `offset` y `total`.

## Operaciones [#operaciones]

### List balances for accessible accounts [#get-accounts-balances]

```http
GET /api/public/v1/accounts/balances
```

Host: `https://api-baas-sandbox.tilopay.com` — requiere `Authorization: Bearer <access_token>`.

Returns paginated account balances (`account`, `amounts`, `as_of`). This endpoint checks
the current balance in real time and may respond more slowly than `GET /accounts`.
For account attributes without amounts, use `GET /accounts`.

Optional filters use the public account identification standard: `type` + `value`
(identifier scheme + value). `type` is not the internal account classification.

**Parámetros**

| Parámetro | En | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
| `X-Correlation-Id` | header | string | — | Optional client-supplied correlation id for end-to-end tracing. Echoed back as `correlation_id` in the response envelope. If omitted, the API generates one and still returns it. |
| `limit` | query | integer | — | — |
| `offset` | query | integer | — | — |
| `type` | query | string | — | Optional filter by account **identifier scheme** (e.g. `IBAN`). Not the internal account classification. |
| `value` | query | string | — | Optional filter by account identifier value (partial match supported for list endpoints). |

**200** — The request was processed successfully.

`response_code`: `OK`

Campos de `data`:

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `items` | array<object> | sí | — |
| `items[].account` | object | sí | — |
| `items[].account.currency` | string | — | — |
| `items[].account.type` | string | sí | — |
| `items[].account.value` | string | sí | — |
| `items[].amounts` | object | sí | — |
| `items[].amounts.available` | string | sí | — |
| `items[].amounts.inbound_in_transit` | string | sí | — |
| `items[].amounts.outbound_in_transit` | string | sí | — |
| `items[].amounts.posted` | string | sí | — |
| `items[].as_of` | string | sí | — |
| `pagination` | object | sí | — |
| `pagination.limit` | integer | sí | — |
| `pagination.offset` | integer | sí | — |
| `pagination.total` | integer | sí | — |

**Respuestas de error**

| HTTP | response_code | Descripción |
|---|---|---|
| 400 | `INVALID_REQUEST` | Invalid request. Check the required fields and try again. |
| 401 | `UNAUTHORIZED` | Unauthorized. Verify your session or credentials. |
| 403 | `FORBIDDEN`, `ACCOUNT_ACCESS_DENIED` | You do not have permission to perform this action. |
| 404 | `NOT_FOUND` | The requested resource was not found. |
| 429 | `TOO_MANY_REQUESTS` | Too many requests. Please retry after a short delay. |
| 500 | `INTERNAL_ERROR` | An unexpected error occurred. Please try again later. |
| 502 | — | Dependency error |
| 503 | `SERVICE_UNAVAILABLE` | A required service is temporarily unavailable. Please try again later. |

### List accessible accounts without balances [#get-accounts]

```http
GET /api/public/v1/accounts
```

Host: `https://api-baas-sandbox.tilopay.com` — requiere `Authorization: Bearer <access_token>`.

Returns paginated accessible accounts without querying current balances.
Each item is account attributes only (`account.type`, `account.value`, `account.currency`).
`amounts` and `as_of` are not included; use `GET /accounts/balances` or `POST /accounts/balance`.

Optional filters use the public account identification standard: `type` + `value`
(identifier scheme + value). `type` is not the internal account classification.

**Parámetros**

| Parámetro | En | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
| `X-Correlation-Id` | header | string | — | Optional client-supplied correlation id for end-to-end tracing. Echoed back as `correlation_id` in the response envelope. If omitted, the API generates one and still returns it. |
| `limit` | query | integer | — | — |
| `offset` | query | integer | — | — |
| `type` | query | string | — | Optional filter by account **identifier scheme** (e.g. `IBAN`). Not the internal account classification. |
| `value` | query | string | — | Optional filter by account identifier value (partial match supported for list endpoints). |

**200** — The request was processed successfully.

`response_code`: `OK`

Campos de `data`:

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `items` | array<object> | sí | — |
| `items[].account` | object | sí | — |
| `items[].account.currency` | string | — | — |
| `items[].account.type` | string | sí | — |
| `items[].account.value` | string | sí | — |
| `pagination` | object | sí | — |
| `pagination.limit` | integer | sí | — |
| `pagination.offset` | integer | sí | — |
| `pagination.total` | integer | sí | — |

**Respuestas de error**

| HTTP | response_code | Descripción |
|---|---|---|
| 400 | `INVALID_REQUEST` | Invalid request. Check the required fields and try again. |
| 401 | `UNAUTHORIZED` | Unauthorized. Verify your session or credentials. |
| 403 | `FORBIDDEN` | You do not have permission to perform this action. |
| 404 | `NOT_FOUND` | The requested resource was not found. |
| 429 | `TOO_MANY_REQUESTS` | Too many requests. Please retry after a short delay. |
| 500 | `INTERNAL_ERROR` | An unexpected error occurred. Please try again later. |
| 502 | — | Dependency error |
| 503 | `SERVICE_UNAVAILABLE` | A required service is temporarily unavailable. Please try again later. |

### Get account balance [#post-accounts-balance]

```http
POST /api/public/v1/accounts/balance
```

Host: `https://api-baas-sandbox.tilopay.com` — requiere `Authorization: Bearer <access_token>`.

Returns a single account snapshot with `amounts` and `as_of`.
For account attributes without balances, use `GET /accounts`.

**Parámetros**

| Parámetro | En | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
| `X-Correlation-Id` | header | string | — | Optional client-supplied correlation id for end-to-end tracing. Echoed back as `correlation_id` in the response envelope. If omitted, the API generates one and still returns it. |

**Cuerpo del request**

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `account` | object | sí | — |
| `account.type` | string | sí | Account **identifier scheme**. Only `IBAN` is supported here. This is not the internal account classification (e.g. operational). Values: IBAN |
| `account.value` | string | sí | IBAN (spaces allowed; normalized server-side) |

**200** — The request was processed successfully.

`response_code`: `OK`

Campos de `data`:

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `account` | object | sí | — |
| `account.currency` | string | — | — |
| `account.type` | string | sí | — |
| `account.value` | string | sí | — |
| `amounts` | object | sí | — |
| `amounts.available` | string | sí | — |
| `amounts.inbound_in_transit` | string | sí | — |
| `amounts.outbound_in_transit` | string | sí | — |
| `amounts.posted` | string | sí | — |
| `as_of` | string | sí | — |

**Respuestas de error**

| HTTP | response_code | Descripción |
|---|---|---|
| 400 | `INVALID_REQUEST` | Invalid request. Check the required fields and try again. |
| 401 | `UNAUTHORIZED` | Unauthorized. Verify your session or credentials. |
| 403 | `FORBIDDEN`, `ACCOUNT_ACCESS_DENIED` | You do not have permission to perform this action. |
| 404 | `ACCOUNT_NOT_FOUND` | Account not found. |
| 422 | `ACCOUNT_NOT_CONFIGURED`, `UNPROCESSABLE_ENTITY` | This account is not mapped in the system. Please contact support to configure it correctly. |
| 429 | `TOO_MANY_REQUESTS` | Too many requests. Please retry after a short delay. |
| 500 | `INTERNAL_ERROR` | An unexpected error occurred. Please try again later. |
| 502 | `PROVIDER_ERROR` | Unable to complete the request with the payment provider. Please try again later. |
| 503 | `SERVICE_UNAVAILABLE` | A required service is temporarily unavailable. Please try again later. |

### Request account statement generation [#post-accounts-statements]

```http
POST /api/public/v1/accounts/statements
```

Host: `https://api-baas-sandbox.tilopay.com` — requiere `Authorization: Bearer <access_token>`.

Creates an asynchronous account statement request for a date range (max 60 days).
Identify the account with `account.type` + `account.value` (identifier scheme + value,
e.g. IBAN). This follows the public account identification standard.
`account.type` is not the internal account classification.
Returns `{request_id, status: PENDING}` immediately.
Poll `GET /accounts/statements/{request_id}` for status; when `DONE`, the response includes a signed `download_url`.

**Parámetros**

| Parámetro | En | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
| `X-Correlation-Id` | header | string | — | Optional client-supplied correlation id for end-to-end tracing. Echoed back as `correlation_id` in the response envelope. If omitted, the API generates one and still returns it. |
| `Idempotency-Key` | header | string | — | — |

**Cuerpo del request**

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `account` | object | sí | — |
| `account.type` | string | sí | Account **identifier scheme**. Only `IBAN` is supported here. This is not the internal account classification (e.g. operational). Values: IBAN |
| `account.value` | string | sí | IBAN (spaces allowed; normalized server-side) |
| `date_from` | string (date-time) | sí | RFC 3339 timestamp accepted on requests. UTC `Z` or a numeric offset is allowed. Optional fractional seconds are accepted and truncated to seconds. |
| `date_to` | string | sí | RFC 3339 (max 60 days after date_from) |
| `notify_email` | boolean | — | — |

**200** — The request was processed successfully.

`response_code`: `OK`

Campos de `data`:

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `request_id` | string | sí | — |
| `status` | string | sí | — |

**202** — Statement request accepted.

Campos de `data`:

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `request_id` | string (uuid) | sí | — |
| `status` | string | sí | Values: PENDING, PROCESSING, DONE, ERROR |

**Respuestas de error**

| HTTP | response_code | Descripción |
|---|---|---|
| 400 | `INVALID_REQUEST` | Invalid request. Check the required fields and try again. |
| 401 | `UNAUTHORIZED` | Unauthorized. Verify your session or credentials. |
| 403 | `FORBIDDEN`, `ACCOUNT_ACCESS_DENIED` | You do not have permission to perform this action. |
| 404 | `NOT_FOUND` | The requested resource was not found. |
| 409 | `IDEMPOTENCY_CONFLICT` | Idempotency conflict: the same Idempotency-Key was reused with a different request body, or a previous request is still in progress. |
| 429 | `TOO_MANY_REQUESTS` | Too many requests. Please retry after a short delay. |
| 500 | `INTERNAL_ERROR` | An unexpected error occurred. Please try again later. |
| 502 | — | Dependency error |
| 503 | `SERVICE_UNAVAILABLE` | A required service is temporarily unavailable. Please try again later. |

### Get account statement request status [#get-accounts-statements-request-id]

```http
GET /api/public/v1/accounts/statements/{request_id}
```

Host: `https://api-baas-sandbox.tilopay.com` — requiere `Authorization: Bearer <access_token>`.

Returns request status. When `DONE`, includes a GCS signed `download_url` (48h from generation) and `expires_at`.
When `ERROR`, includes a generic `message` without internal details.
Unknown or unauthorized `request_id` returns 404.

**Parámetros**

| Parámetro | En | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
| `X-Correlation-Id` | header | string | — | Optional client-supplied correlation id for end-to-end tracing. Echoed back as `correlation_id` in the response envelope. If omitted, the API generates one and still returns it. |
| `request_id` | path | string (uuid) | sí | — |

**200** — The request was processed successfully.

`response_code`: `OK`

Campos de `data`:

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `download_url` | string | — | — |
| `expires_at` | string | — | — |
| `message` | string | — | — |
| `request_id` | string | sí | — |
| `status` | string | sí | — |

**Respuestas de error**

| HTTP | response_code | Descripción |
|---|---|---|
| 401 | `UNAUTHORIZED` | Unauthorized. Verify your session or credentials. |
| 403 | `FORBIDDEN` | You do not have permission to perform this action. |
| 404 | `NOT_FOUND` | The requested resource was not found. |
| 429 | `TOO_MANY_REQUESTS` | Too many requests. Please retry after a short delay. |
| 500 | `INTERNAL_ERROR` | An unexpected error occurred. Please try again later. |
| 503 | `SERVICE_UNAVAILABLE` | A required service is temporarily unavailable. Please try again later. |