In the Paynetics platform, an Account and a Balance are distinct objects. This separation is fundamental for correct integrations — particularly when initiating transfers, loading cards, or reading transaction data.
The Object Model
An Account is the container. It is associated with a specific User (consumer or business), belongs to a Program, and holds one or more Balances.
A Balance is the money holder. Each Balance holds funds in a single currency, is assigned a unique balance token, and is optionally assigned an external payment identifier (IBAN or account number) that third parties can send funds to.
This separation allows:
A single Account to hold multiple currency Balances (for example, EUR and GBP side by side)
Payment identifiers (IBANs, account numbers) to exist at Balance level rather than Account level, enabling separate inbound routing per currency
API calls to reference the precise Balance being debited or credited, eliminating ambiguity in multi-currency accounts
Why This Matters for Integrations
When you execute a transfer, issue a card load, or apply a fee via the Paynetics API, you reference a balance token — not an account token.
The account token identifies the Account (used for status changes, fetching account details, linking cards). The balance token identifies the specific currency Balance within that Account (used for all monetary operations).
Balance tokens are returned at Account creation time and are also available in Account details API responses.
Example: A consumer Account holds two Balances — one in EUR and one in GBP. To send a wire transfer from the EUR Balance, pass the EUR balance token in the transfer request. The GBP Balance is unaffected.
Multiple Balances
The number of Balances created for an Account at creation time is determined by the Program configuration. A single-currency Program creates one Balance; a multi-currency Program creates one Balance per enabled currency.
Additional Balances cannot be added to an Account after creation. The Program must support the required currencies before account creation.
See Programs for full Program configuration reference.
Balance Identifiers
Each Balance can have one of the following external identifiers, depending on its currency and Program configuration:
Currency | Identifier |
|---|---|
EUR | IBAN |
GBP | IBAN + Sort Code and Account Number |
BGN | IBAN |
USD | None (no dedicated external identifier) |
Identifier generation can be suppressed at Balance level via an API flag at Account creation time, even when the Program has IBAN generation enabled. This is useful for accounts that will only receive internal transfers.
Accounts and Cards
A card can only be linked to an Account with a single Balance in the card currency. If an Account holds multiple Balances (for example, EUR and GBP), a card cannot be directly linked to it.
To issue cards to a multi-currency user, use separate single-currency Accounts, or configure the Program to issue cards against a specific currency Account.
Virtual Account Balances
Virtual Accounts always follow the same currency structure as their linked Payment Account. Their Balances start at zero and cannot hold funds independently — debits and credits against a Virtual Account Balance are settled against the parent Payment Account Balance.
Virtual Account Balances can have their own IBAN, depending on Program configuration. This enables a single Payment Account to receive funds at multiple IBANs, separated by Virtual Account for reconciliation purposes.
See Account Types for the full explanation of Virtual Accounts.