​
Overview

A transaction records a fund movement on EU Rails — an internal transfer between your accounts, an external payment to a payee, an incoming deposit, or an outgoing withdrawal. Transactions are immutable: once created they cannot be updated or deleted. Their status field reflects the current processing state.

​
List transactions

GET /transactions returns your transactions, newest first, in the standard paginated envelope. 
curl "https://stagingapi.balansas.com/functions/v1/customer-api/transactions?status=completed&limit=50&page=1" \
  -H "x-api-key: sk_test_xxxxxxxxxxxxxxxxxxxx"

​
Filtering & pagination

GET /transactions accepts the following query parameters:
​
status
string
Filter by status: pending, completed, failed, or compliance_review.
​
transaction_type
string
Filter by type: payment, transfer_out, deposit, or withdrawal.
​
limit
integer
Results per page. Default 50, maximum 100.
​
page
integer
1-based page number. Default 1.
Results are always ordered by created_at descending. The meta.pagination object echoes page, limit, and the total matching count. See Pagination for the shared convention.

​
The transaction object

​
id
string (uuid)
Unique Balansas identifier. Always use this internal ID when referencing a transaction.
​
fr_transaction_id
string
Banking partner transaction/payment ID. May be null while a transaction is still pending.
​
transaction_type
string
payment (external), transfer_out (internal outgoing), deposit (incoming funds), or withdrawal (outgoing withdrawal).
​
amount
number
Transaction amount (positive decimal).
​
currency
string
ISO currency code (EUR, GBP, USD).
​
status
string
Current processing state (see below).
​
from_account_id
string (uuid)
Source account UUID. Nullable.
​
to_account_id
string (uuid)
Destination account UUID for internal transfers. Nullable (external payments use payee_id).
​
from_account_type
string
FIAT_ACCOUNT or VIRTUAL_ACCOUNT. Nullable.
​
to_account_type
string
FIAT_ACCOUNT, VIRTUAL_ACCOUNT, or PAYEE. Nullable.
​
description
string
Transaction description. Nullable.
​
reference
string
Payment reference. Nullable.
​
counterparty_name
string
External counterparty name. Nullable.
​
counterparty_account
string
External counterparty account / IBAN. Nullable.
​
fee_amount
number
Fee charged for this transaction. Nullable.
​
fee_currency
string
Currency of the fee. Nullable.
​
virtual_account_id
string (uuid)
Associated virtual account when the source is virtual. Nullable.
​
payee_id
string (uuid)
Associated payee for external payments. Nullable.
​
balance_before
number
Account balance before the transaction. Nullable.
​
balance_after
number
Account balance after the transaction. Nullable.
​
direction
string
debit or credit. Nullable.
​
completed_at
string (timestamp)
When the transaction completed. Nullable.
​
created_at
string (timestamp)
ISO 8601 creation time.

​
Statuses

Created and awaiting processing. The fr_transaction_id may not be populated yet.
Held for AML / KYC compliance review before it can proceed.
Successfully processed. completed_at is set.
Could not be processed (insufficient funds, validation error, provider rejection, etc.).
Always check status to confirm completion. A pending transaction may not yet carry an fr_transaction_id. Subscribe to payment.* events via Webhooks to receive status changes without polling.

List EU Rails transactions

Full contract and request playground.

Pagination

The shared page / limit / total convention.