Statement Download

The API created for statement download aims to automate access to bank statements, integrating it into other applications (e.g., accounting systems, archiving solutions). This way, statements of accounts held at Raiffeisen Bank are easily accessible, which is essential for supporting audit, archiving, and accounting processes.

Synchronous Download (two-step process)

The statement download happens in two steps:

Query statement metadata (POST /statement/metadata) – Query the list of available statements for the specified period
Download statement (POST /statement/download) – Request the download link for the selected statement

1. Query statement metadata

By querying metadata, we get the list of available statements for the given account and period.

Request parameters

JSON field	Required	Type	Pattern / Max length	Note
iban	Yes	string	`^HU[0-9]{2}120[0-9]{16}0000[0-9]{1}$`	The IBAN number of the account to query
dateFrom	Yes	string	-	Start date (YYYY-MM-DD format). Cannot be older than 1 year.
dateTo	Yes	string	-	End date (YYYY-MM-DD format)
consentList	Yes	array	-	List of consent identifiers — always a 2-element array

Response fields

JSON field	Type	Note
allDocRecordCount	number	Number of statements found by the query
documents []	array	Document block, each document returns the following attributes
docId	number	Unique identifier of the statement (needed for download)
genDate	string	Date of statement generation
fileOrigName	string	Original file name of the statement
iban	string	Account number related to the statement
externalId	string	Identifier of the statement

2. Download statement

To download the statement, the docId value received from the metadata query must be used.

Important

Before downloading, the metadata query must be completed, as the service identifies the account based on the docId. If the metadata query has not been performed, the service will respond with a DOCUMENT_REGISTRY_NOT_FOUND error.

Request parameters

JSON field	Required	Type	Pattern / Max length	Note
docId	Yes	number	-	Document identifier received from the metadata query
consentList	Yes	array	-	List of consent identifiers — always a 2-element array

Response fields

JSON field	Type	Note
docId	number	Unique identifier of the statement
genDate	string	Date of statement generation (YYYY-MM-DD)
iban	string	Account number related to the statement
externalId	string	Identifier of the statement
fileOrigName	string	Original file name of the statement
metaList []	array	List of meta information
metaName	string	Name of the meta data (e.g., `CERTIFIED`, `STATEMENT_NO`)
metaValue	string	Value of the meta data
downloadUrl	string	Download link of the statement. The statement PDF can be downloaded via this URL.
urlExpiresAt	string	Expiry time of the `downloadUrl` (ISO 8601). The link is valid until this time — the download must be performed immediately.

Meaning of metaList elements:

metaName	metaValue	Description
`CERTIFIED`	`Y` / `N`	Whether the statement is electronically signed
`STATEMENT_NO`	Statement number	The number of the statement

Important

The received downloadUrl in the response is a short-lived, pre-signed link — valid until the time indicated in the urlExpiresAt field (approximately 1 minute). The statement can be downloaded in PDF format by sending a GET request to the URL or by opening the link in a browser. The download must be performed immediately after receiving the response.

Asynchronous Download (for large files)

For large statements, the asynchronous process is recommended: the first call immediately returns a processId, and the status polling endpoint shows the processing status and — when complete — the download link.

Important

Before starting the asynchronous download, the metadata query must be completed, as the service identifies the account based on the docId. If the metadata query has not been performed, the service will respond with a DOCUMENT_REGISTRY_NOT_FOUND error.

Asynchronous process steps

Prerequisite — metadata query

Before starting the asynchronous download, 1. Query statement metadata must be performed. The required docId value must be extracted from the documents[].docId field of the metadata response. If this step is skipped, the service will respond with a DOCUMENT_REGISTRY_NOT_FOUND error.

Start the process (POST /statement/async/) – Immediately returns a processId
Query status (POST /statement/async/status) – The status and — if DONE — the download link can be queried based on the processId

Full process overview

Step 1 — Start the process POST /statement/async/

When the request arrives, the service checks the status in the following order:

Valid document exists (DONE, not expired) → 200, the processId is immediately pollable, the download link is already available
Active processing is running (IN_PROGRESS) → 200, the processId of the running process is returned
Nothing exists (or everything has expired) → 201, new processing starts, the processId is returned

Step 2 — Background processing (starts automatically after a 201 response)

The service performs the following in the background:

Retrieves the document from the banking backend
Uploads the PDF to storage
The process status changes to DONE, the downloadUrl becomes available

Step 3 — Query status POST /statement/async/status

The processing status can be monitored via polling (recommended interval: 2–5 seconds):

Status	Description	Next step
`IN_PROGRESS`	Processing in progress	Continue polling
`DONE`	Ready — download link available	Download from `downloadUrl`
`ERROR`	Processing failed	Start a new process with POST
`EXPIRED`	Stored document availability has expired (see: `documentExpiresAt`)	Start a new process with POST

Step 4 — Download PDF GET {downloadUrl}

The statement can be downloaded in PDF format by sending a GET request to the downloadUrl or by opening it in a browser. The link is short-lived — the download must be performed immediately. If the link has expired but the process is still in DONE status, call the status polling endpoint again for a fresh download link.

1. Start the process

Request parameters

JSON field	Required	Type	Note
docId	Yes	number	Document identifier received from the metadata query
consentList	Yes	array	List of consent identifiers — always a 2-element array

Response (201 Created — new process)

{ "processId": "550e8400-e29b-41d4-a716-446655440000" }

Response (200 OK — existing active process or valid document)

{ "processId": "550e8400-e29b-41d4-a716-446655440000" }

Cache optimization — 200 vs. 201

The service applies three-level caching to avoid unnecessary processing:

Valid document exists (DONE, not expired) → 200, same processId, the download link is immediately available at the status endpoint
Active process running (IN_PROGRESS) → 200, processId of the running process, continues to be pollable
Nothing exists (or everything has expired) → 201, new process starts

Only 1 active process can run for the same docId at a time — in the case of parallel POST calls, both clients receive the same processId (200).

2. Query status

POST /statement/async/status

Request parameters

JSON field	Required	Type	Note
processId	Yes	string (UUID)	Identifier received when the process was started
consentList	Yes	array	List of consent identifiers — always a 2-element array

Recommended polling strategy

Interval: every 2–5 seconds is sufficient; average processing time is 3–10 seconds
Timeout: do not poll for more than 5 minutes — if there is no DONE by then, an ERROR has likely occurred
ERROR status: the errorMessage field contains the error cause; a new process can be started with POST
EXPIRED status: the stored document availability has expired (the documentExpiresAt time has passed); a new process can be started with POST, which will re-fetch and upload the document

Response (IN_PROGRESS status)

{
  "processId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "IN_PROGRESS"
}

Response (DONE status)

{
  "processId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "DONE",
  "docId": 1234567,
  "genDate": "2026-01-15",
  "iban": "HU29120670080010034200100009",
  "externalId": "EXT-2026-001234",
  "fileOrigName": "statement_2026_01.pdf",
  "metaList": [
    { "metaName": "CERTIFIED", "metaValue": "Y" },
    { "metaName": "STATEMENT_NO", "metaValue": "4" }
  ],
  "downloadUrl": "https://s3.eu-central-1.amazonaws.com/...",
  "urlExpiresAt": "2026-01-15T10:31:00Z",
  "documentExpiresAt": "2026-01-16T23:30:00Z"
}

Response (ERROR status)

{
  "processId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "ERROR",
  "errorMessage": "Error description (if available)"
}

downloadUrl, urlExpiresAt and documentExpiresAt

The downloadUrl is a short-lived, pre-signed link — valid until the time indicated in the urlExpiresAt field (approximately 1 minute). The download must be performed immediately.

If the link has expired but the process status is still DONE, call the status polling endpoint again: the service always returns a fresh downloadUrl and fresh urlExpiresAt value — up until the documentExpiresAt time.

The documentExpiresAt indicates how long the document is available from storage. The document is typically available until ~23:30 UTC on the day following the upload. If this time has passed, the process enters EXPIRED status and a new process must be started with a POST call.

Document expiry and starting a new process

When the asynchronous process reaches DONE status, the downloaded document remains available from storage for a defined period — during this time, the status polling endpoint always returns a fresh downloadUrl, regardless of the urlExpiresAt expiry.

The documentExpiresAt field in the DONE response of the status query contains the time until which we store the document. This value is typically around ~23:30 UTC on the day following the upload — so a document processed today can be queried until ~23:30 UTC the next day, after which a new process must be started for that docId (new async POST call).

After expiry, the following process applies:

After the documentExpiresAt time passes, the process enters EXPIRED status (at the latest at the next status query)
Start a new process with the same docId (POST /statement/async/) — the new process re-fetches the document, and the documentExpiresAt shifts to the following day's 23:30 UTC
The processId of the newly started process is returned, which can be used to continue polling the status

When should a new process be started?

It is not necessary to actively monitor expiry: if the status endpoint responds with EXPIRED, that is an unambiguous signal that a new POST /statement/async/ call is needed with the same docId. The documentExpiresAt value can also be used to calculate in advance when this should be done.

Error codes

Error code	Description
`UNEXPECTED_ERROR`	Unexpected error
`ARGUMENT_NOT_VALID`	Invalid parameter (required field missing or format incorrect)
`INVALID_DATE_RANGE`	Invalid date range (e.g., `dateFrom` is later than `dateTo`)
`DATE_FROM_TOO_OLD`	Start date too old (maximum 1 year back can be queried)
`TECHUSER_HAS_NO_RIGHT`	The technical user does not have the right to the specified account, or does not have the right to query the statement of the specified docId account, or the HUFPAY right is not checked in the portal for the specified account
`DOCUMENT_ACCOUNT_MISMATCH`	The account number of the requested document does not match the authenticated account — please contact customer support
`STATEMENT_META_DATA_NOT_FOUND`	Statement metadata not found with the given parameters
`STATEMENT_NOT_FOUND`	Statement not found for the given `docId`, or it is incomplete in the backend
`DOCUMENT_REGISTRY_NOT_FOUND`	No account mapping found for the given `docId` — the metadata query must be performed first
`UPLOAD_FAILED`	Document upload to storage failed — please try again
`PROCESS_NOT_FOUND`	No asynchronous process found for the given `processId`
`PROCESS_FAILED`	Process execution failed — please try again or contact customer support

Synchronous Download (two-step process)​

1. Query statement metadata​

Request parameters​

Response fields​

2. Download statement​

Request parameters​

Response fields​

Asynchronous Download (for large files)​

Asynchronous process steps​

Full process overview​

1. Start the process​

Request parameters​

Response (201 Created — new process)​

Response (200 OK — existing active process or valid document)​

2. Query status​

Request parameters​

Recommended polling strategy​

Response (IN_PROGRESS status)​

Response (DONE status)​

Response (ERROR status)​

Document expiry and starting a new process​

Error codes​

Synchronous Download (two-step process)

1. Query statement metadata

Request parameters

Response fields

2. Download statement

Request parameters

Response fields

Asynchronous Download (for large files)

Asynchronous process steps

Full process overview

1. Start the process

Request parameters

Response (201 Created — new process)

Response (200 OK — existing active process or valid document)

2. Query status

Request parameters

Recommended polling strategy

Response (IN_PROGRESS status)

Response (DONE status)

Response (ERROR status)

Document expiry and starting a new process

Error codes