Banking API accounts
API 1.0.0An MCP tool wraps this operation: Banking API (BaaS).
The Accounts group covers the account as a resource: validate a destination account
before transferring, list accessible accounts, check balances and request statements.
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}Resource rules#
Scope. The listing returns only the accounts the token authorizes; tenant_id and
owner_id are never sent as parameters.
Validate first. Validate the destination account before creating a payment: the operation confirms the account exists and is eligible, and returns the holder data the service exposes.
Asynchronous statements. Generation is requested with a POST that accepts
Idempotency-Key and returns a request_id; you then poll that request_id until the
result is available. See
safe retries.
Pagination. GET /api/public/v1/accounts and GET /api/public/v1/accounts/balances
use limit and offset, and return pagination with limit, offset and total.
Operations#
List balances for accessible accounts
GET /api/public/v1/accounts/balances
Host: https://api-baas-sandbox.tilopay.com — requires 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.
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
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). |
Response 200
The request was processed successfully.
response_code: OK
| Field | Type | Required | Description |
|---|---|---|---|
items | array<object> | yes | — |
items[].account | object | yes | — |
items[].account.currency | string | — | — |
items[].account.type | string | yes | — |
items[].account.value | string | yes | — |
items[].amounts | object | yes | — |
items[].amounts.available | string | yes | — |
items[].amounts.inbound_in_transit | string | yes | — |
items[].amounts.outbound_in_transit | string | yes | — |
items[].amounts.posted | string | yes | — |
items[].as_of | string | yes | — |
pagination | object | yes | — |
pagination.limit | integer | yes | — |
pagination.offset | integer | yes | — |
pagination.total | integer | yes | — |
Error responses
| HTTP | response_code | Description |
|---|---|---|
| 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 — requires 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.
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
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). |
Response 200
The request was processed successfully.
response_code: OK
| Field | Type | Required | Description |
|---|---|---|---|
items | array<object> | yes | — |
items[].account | object | yes | — |
items[].account.currency | string | — | — |
items[].account.type | string | yes | — |
items[].account.value | string | yes | — |
pagination | object | yes | — |
pagination.limit | integer | yes | — |
pagination.offset | integer | yes | — |
pagination.total | integer | yes | — |
Error responses
| HTTP | response_code | Description |
|---|---|---|
| 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 — requires Authorization: Bearer <access_token>.
Returns a single account snapshot with amounts and as_of. For account attributes without balances, use GET /accounts.
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
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 body
| Field | Type | Required | Description |
|---|---|---|---|
account | object | yes | — |
account.type | string | yes | Account identifier scheme. Only IBAN is supported here.
This is not the internal account classification
(e.g. operational).Values: IBAN |
account.value | string | yes | IBAN (spaces allowed; normalized server-side) |
Response 200
The request was processed successfully.
response_code: OK
| Field | Type | Required | Description |
|---|---|---|---|
account | object | yes | — |
account.currency | string | — | — |
account.type | string | yes | — |
account.value | string | yes | — |
amounts | object | yes | — |
amounts.available | string | yes | — |
amounts.inbound_in_transit | string | yes | — |
amounts.outbound_in_transit | string | yes | — |
amounts.posted | string | yes | — |
as_of | string | yes | — |
Error responses
| HTTP | response_code | Description |
|---|---|---|
| 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 — requires Authorization: Bearer <access_token>. Accepts 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.
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
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 | — | — |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
account | object | yes | — |
account.type | string | yes | Account identifier scheme. Only IBAN is supported here.
This is not the internal account classification
(e.g. operational).Values: IBAN |
account.value | string | yes | IBAN (spaces allowed; normalized server-side) |
date_from | string (date-time) | yes | 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 | yes | RFC 3339 (max 60 days after date_from) |
notify_email | boolean | — | — |
Response 200
The request was processed successfully.
response_code: OK
| Field | Type | Required | Description |
|---|---|---|---|
request_id | string | yes | — |
status | string | yes | — |
Response 202
Statement request accepted.
| Field | Type | Required | Description |
|---|---|---|---|
request_id | string (uuid) | yes | — |
status | string | yes | —Values: PENDING, PROCESSING, DONE, ERROR |
Error responses
| HTTP | response_code | Description |
|---|---|---|
| 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 — requires 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.
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
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) | yes | — |
Response 200
The request was processed successfully.
response_code: OK
| Field | Type | Required | Description |
|---|---|---|---|
download_url | string | — | — |
expires_at | string | — | — |
message | string | — | — |
request_id | string | yes | — |
status | string | yes | — |
Error responses
| HTTP | response_code | Description |
|---|---|---|
| 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. |
Last verified: 2026-09-02 · Owner: equipo-integraciones