​
Overview

EU Rails (powered by Fiat Republic) gives you two kinds of bank accounts:
  • Fiat accounts — real currency accounts that hold funds. A fiat account flagged as a master account can have virtual accounts linked beneath it.
  • Virtual accounts — sub-accounts with their own unique IBANs, linked to a master fiat account. Funds received on a virtual account’s IBAN flow up to the master account, so they’re ideal for segregating customer balances.

List fiat accounts

Page through every fiat account you own.

Create a fiat account

Open a new fiat account in a supported currency.

List virtual accounts

Page through virtual accounts and their parents.

Create a virtual account

Add a segregated sub-account under a master.

​
Account types & capabilities

Which account endpoints you can call depends on your business relationship type.
RelationshipFiat accountsPayeesEnd usersVirtual accounts
LINKED_BUSINESS (B2B)✓✓✗✗
LINKED_MEMBER (B2C platform)✓✓✓✓
LINKED_BUSINESS suits corporate treasury and supplier payments. LINKED_MEMBER is the full platform tier for marketplaces, neobanks, and payment service providers that serve their own end customers. To change your relationship type, contact support.

​
Fiat account object

A fiat account is identified by an internal id (a UUID) — always use this in your own systems. The provider-side fr_account_id is exposed for reference but should not be treated as your primary key.
​
id
string
Unique Balansas identifier (UUID). Use this everywhere.
​
fr_account_id
string
Banking partner account ID (reference only).
​
account_name
string
Display name (1–200 characters).
​
currency
string
ISO currency. One of USD, EUR, GBP, CHF, CAD, AUD.
​
balance
number
Current balance. Read-only — updated by transactions.
​
status
string
Account lifecycle status. See Lifecycle & statuses.
​
is_master
boolean
When true, the account can have virtual accounts linked beneath it.
​
iban
string
IBAN, when assigned by the provider.
​
bic
string
BIC / SWIFT code, when assigned.
​
linked_business_id
string
Linked business ID (UUID, nullable).
​
fr_owner_business_id
string
Banking partner business ID of the owner.
​
created_at
string
ISO 8601 timestamp.
​
updated_at
string
ISO 8601 timestamp.

​
Creating a fiat account

The create request takes only accountName and currency; ibanCountry and umbrellaLinkId are optional.
​
accountName
string
required
Display name (1–200 characters).
​
currency
string
required
One of USD, EUR, GBP, CHF, CAD, AUD.
​
ibanCountry
string
2-letter ISO country code to request the IBAN in.
​
umbrellaLinkId
string
UUID. Provision under a Balansas-managed master business in PPA Mode.
curl -X POST https://stagingapi.balansas.com/functions/v1/customer-api/fiat-accounts \
  -H "x-api-key: sk_test_xxxxxxxxxxxxxxxxxxxx" \
  -H "X-CSRF-Token: <64-char-hex>" \
  -H "Content-Type: application/json" \
  -d '{ "accountName": "Operating EUR", "currency": "EUR" }'

​
Virtual account object

A virtual account inherits its currency from its master and exposes its own IBAN for inbound funds.
​
id
string
Unique Balansas identifier (UUID).
​
fr_virtual_account_id
string
Banking partner virtual account ID (reference only).
​
account_name
string
Display name (1–200 characters).
​
currency
string
Inherited from the master fiat account.
​
master_fiat_account_id
string
Parent master fiat account ID (UUID, required).
​
end_user_id
string
Linked end user (UUID, nullable).
​
status
string
Account lifecycle status. See Lifecycle & statuses.
​
iban
string
Virtual account IBAN. Funds received here flow to the master account.

​
Creating a virtual account

​
accountName
string
required
Display name (1–200 characters).
​
masterFiatAccountId
string
required
UUID of an existing master fiat account you own.
​
currency
string
required
One of USD, EUR, GBP, CHF, CAD, AUD. Set it to match the master.
​
endUserId
string
UUID. Link the virtual account to a specific end user for segregation.
​
ibanCountry
string
IBAN jurisdiction. One of DE, DK, GB, LU. Defaults from your business profile if omitted.
​
umbrellaLinkId
string
UUID. The master account must itself be a PPA-mode account under the same link. See PPA Mode.
Only master fiat accounts (is_master: true) can parent virtual accounts, and only LINKED_MEMBER accounts may create them.

​
Lifecycle & statuses

Account status reflects where the account sits in its lifecycle. A newly created account starts in processing while the banking partner provisions it, then becomes active once it can transact. Accounts can be blocked (cannot transact, recoverable) or closed (terminal).
StatusMeaning
processingBeing provisioned by the banking partner; not yet usable.
activeProvisioned and ready to send and receive.
blockedTemporarily prevented from transacting.
closedPermanently closed; terminal.
Always reject-list against known terminal/blocked states rather than allow-listing active only — the provider may introduce intermediate states.

​
Balances

The balance field on the account object is the last value Balansas observed. It is updated by transactions and provider events, so it may briefly lag a deposit that has just landed.
Treat balance as a display hint, not a pre-flight authorization. For balance-dependent decisions (such as a payment), rely on the live transaction result rather than a possibly-stale cached balance.