gln_retrieve_transactions

Declared in <galanthus/c_api/gln_capi.h>.

GLN_API gln_status_t GLN_CALL gln_retrieve_transactions(
    gln_backend_t*                         in_backend,
    const gln_list_transactions_request_t* in_request,
    gln_backend_result_t**                 out_result);

Family: Backend operations
Return type: gln_status_t

Purpose

gln_retrieve_transactions asks a backend for transaction history for one account IBAN and returns a gln_backend_result_t envelope.

The request accepts optional inclusive date filters plus limit_or_zero and page_token_or_null fields. Treat limit and page-token handling as backend capability: a backend may enforce them, ignore unsupported pagination controls, or report a next-page token when another page is available.

Backend support is operation-specific. Use gln_check_backend_operation_support to check whether a backend supports this operation before calling it. Unsupported operations return an envelope whose status is GLN_ERR_NOT_SUPPORTED.

When To Use

Use this operation after choosing an account row from gln_retrieve_accounts or an embedded account from gln_retrieve_bank_info.

Treat transaction page tokens as backend-owned opaque values when a backend provides them. A NULL token means the returned result does not advertise another page.

Call Contract

GLN_OK from the function means an envelope was produced in *out_result; it does not mean the backend operation succeeded. Inspect the envelope with gln_get_backend_result_outcome, gln_get_backend_result_status, and gln_get_backend_result_kind.

out_result == NULL is the no-envelope invalid-argument case. In that case the function returns GLN_ERR_INVALID_ARG directly.

For gln_list_transactions_request_t, iban is required and must be non-empty. from_date_or_null and to_date_or_null are inclusive date filters accepted as YYYY-MM-DD or YYYYMMDD; accepted values are normalized before the backend request is dispatched.

limit_or_zero and page_token_or_null are accepted request fields, not a guarantee that every backend enforces page size or page-token semantics. Negative limits are rejected. Positive limits request a maximum row count, and non-empty page tokens are forwarded through the client request shape for backends that support them.

Backends that do not support wire-level pagination return the rows they materialize without synthesizing backend-enforced pages.

The parameter table is binding for required handles and output slots.

Return

Returns GLN_OK when the call produced a gln_backend_result_t envelope in out_result. Operation success, caller action, provider rejection, and operation errors are reported inside that envelope.

Type	Nullability	Ownership
`gln_status_t`	value	value

Parameters

Name	Direction	Type	Nullability	Ownership
`in_backend`	input	`gln_backend_t*`	nonnull	borrowed
`in_request`	input	`const gln_list_transactions_request_t*`	nonnull	borrowed
`out_result`	output	`gln_backend_result_t**`	nonnull	transferred_out

Success Result

Successful operation envelopes have outcome GLN_BACKEND_OUTCOME_SUCCESS, status GLN_OK, and kind GLN_BACKEND_RESULT_KIND_TRANSACTIONS.

Borrow the typed success view with gln_get_backend_result_transactions.

Use gln_get_backend_result_transactions only when the envelope outcome is GLN_BACKEND_OUTCOME_SUCCESS and the kind is GLN_BACKEND_RESULT_KIND_TRANSACTIONS.

Action-required envelopes carry interrupt details and a continuation instead of this typed success view. Resume the operation and read the accessor only after a success envelope is produced.

Rows expose required status, remote name, remote IBAN, purpose, and source-format fields plus optional booking/value dates, amount, currency, and references. Optional accessors return NULL when the provider did not supply that field for the row.

gln_get_transactions_next_page_token returns a borrowed next-page token only when the backend result carries one. NULL means this result does not advertise another page; current FinTS results return NULL.

Outcomes

GLN_BACKEND_OUTCOME_SUCCESS: read the GLN_BACKEND_RESULT_KIND_TRANSACTIONS typed view.
GLN_BACKEND_OUTCOME_ACTION_REQUIRED: FinTS read flows can require caller action, usually a TAN or decoupled step. Inspect gln_get_backend_result_interrupt_info, take the continuation with gln_take_backend_result_continuation, and resume with gln_resume_continuation.
GLN_BACKEND_OUTCOME_REJECTED: inspect gln_get_backend_result_status and gln_get_backend_result_error for provider rejection details.
GLN_BACKEND_OUTCOME_ERROR: inspect gln_get_backend_result_status and gln_get_backend_result_error. Other backends use this outcome with status GLN_ERR_NOT_SUPPORTED.

Ownership And Lifetime

The envelope returned through out_result is caller-owned and must be released with gln_destroy_backend_result.

Typed views, result rows or fields, borrowed strings, and the JSON string are borrowed from the envelope. They become invalid when the envelope is destroyed. Copy strings or row data before destroying the envelope when the caller needs to keep them.

For action-required envelopes, gln_get_backend_result_interrupt_info returns borrowed interrupt details. gln_take_backend_result_continuation transfers continuation ownership to the caller; destroy that continuation with gln_destroy_continuation after it has been saved or resumed.

Example

gln_list_transactions_request_t request = {0};
gln_default_list_transactions_request(&request);
request.iban = account_iban;
request.from_date_or_null = "2026-04-01";
request.to_date_or_null = "2026-04-30";
request.limit_or_zero = 200;

gln_backend_result_t* result = NULL;
gln_status_t rc = gln_retrieve_transactions(backend, &request, &result);
if (rc != GLN_OK) {
    return rc;
}

gln_backend_outcome_t outcome = gln_get_backend_result_outcome(result);
if (outcome == GLN_BACKEND_OUTCOME_SUCCESS &&
    gln_get_backend_result_kind(result) == GLN_BACKEND_RESULT_KIND_TRANSACTIONS) {
    const gln_transactions_t* transactions =
        gln_get_backend_result_transactions(result);
    for (size_t i = 0; i < gln_get_transactions_count(transactions); ++i) {
        const gln_transaction_t* tx = gln_get_transaction_at(transactions, i);
        consume_transaction(
            gln_get_transaction_booking_date(tx),
            gln_get_transaction_amount(tx),
            gln_get_transaction_currency(tx),
            gln_get_transaction_purpose(tx));
    }
}
else if (outcome == GLN_BACKEND_OUTCOME_ACTION_REQUIRED) {
    const gln_interrupt_info_t* interrupt = gln_get_backend_result_interrupt_info(result);
    gln_continuation_t* continuation = gln_take_backend_result_continuation(result);
    handle_read_interrupt(interrupt, continuation);
    gln_destroy_continuation(continuation);
}
else {
    handle_read_failure(
        gln_get_backend_result_status(result),
        gln_get_backend_result_error(result));
}

gln_destroy_backend_result(result);