Cuentas del API Bancario

API 1.0.0

Una herramienta del MCP envuelve esta operación: Herramientas bancarias.

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.

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#

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.

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#

List balances for accessible accounts

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).

Respuesta 200

The request was processed successfully.

response_code: OK

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 /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).

Respuesta 200

The request was processed successfully.

response_code: OK

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 /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).Valores: IBAN
`account.value`	string	sí	IBAN (spaces allowed; normalized server-side)

Respuesta 200

The request was processed successfully.

response_code: OK

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 /api/public/v1/accounts/statements

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

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).Valores: 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	—	—

Respuesta 200

The request was processed successfully.

response_code: OK

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

Respuesta 202

Statement request accepted.

Campo	Tipo	Obligatorio	Descripción
`request_id`	string (uuid)	sí	—
`status`	string	sí	—Valores: 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 /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í	—

Respuesta 200

The request was processed successfully.

response_code: OK

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.

Última verificación: 2026-09-02 · Responsable: equipo-integraciones

Ver como Markdown crudo