Platform Concepts

Banking & Accounts

Understand how Penny structures accounts and external banking relationships.

Penny separates the accounts that hold and control funds inside the platform from external bank accounts registered with Penny. A Business Entity (the legal or operating entity under a Business) owns each account: its Linked Accounts, its Capital Accounts, and the Control Accounts that govern how those Capital Accounts may be spent. Every account response carries a type field (capital, control, or linked), so you can always tell which kind of account you’re looking at. See Business & Access for how a Business Entity fits into the wider organization structure.

bank channelscopesBusinessOWNERBusiness EntityACCOUNT OWNERLinked AccountEXTERNALCapital AccountCAPITALControl AccountCONTROL · OPTIONALTransactionACTIVITY

Capital Accounts

A Capital Account holds an actual settled balance. This is the owning Business Entity’s real money inside Penny, and the financial context used throughout banking and issuing workflows for balances, transactions, transfers, and card funding.

What it’s for: any workflow that needs to know how much money is here (reading a balance, funding the cards in a Program, or moving money between two parts of the same business) reads and writes against a Capital Account.

How it behaves:

  • Nested: a parent Capital Account can have child accounts underneath it, so one funding source can be split across departments or products while still rolling up to a single parent.
  • Auto-topped-up: configure a source Capital Account, a threshold_amount, and a top_up_amount, and Penny moves funds automatically when the balance drops below the threshold, instead of you polling balances and transferring manually.
  • Alerted: set low_balance_notification.threshold_amount and receive an account.low_balance_alert webhook when the balance drops below it.
  • Transferable: POST /accounts/capital/transfer moves funds from one Capital Account to another and produces two transfer-type transactions, one on each account, visible in the same activity history as everything else.

See Accounts for the full request/response reference and account status lifecycle.

Control Accounts

A Control Account holds no balance of its own. It scopes spend against one Capital Account and exists to answer one question: how much is allowed to move through here, and how fast?

What it’s for: it’s the layer you attach to cards, cardholders, or business units when several of them need to share one budget without each needing a separate pool of money. A card and its cardholder can point at the same Control Account and share one limit, backed by a single Capital Account’s balance.

How it behaves:

  • Every Control Account references exactly one Capital Account (capital_account_id). That’s where the money it authorizes against lives; no funds are moved into the Control Account.
  • Control Accounts can nest under a parent Control Account, mirroring how Capital Accounts can nest, so a limit can be subdivided further (for example, a company-wide budget split across teams).
  • A Control Account can carry its own Spend Control — the rule set that decides whether a given authorization is allowed to proceed.

Control Accounts add a second layer to a Transaction’s account context: the Capital Account tells you where the money is, and the Control Account (when present) tells you what it was allowed to be used for.

The exact relationship between an account, its controls, and transaction authorization is covered in Spend Controls.

Linked Accounts

A Linked Account is an external bank account you register with Penny as a source of incoming funds. When Penny receives funds from a registered Linked Account, it routes them to your Capital Account.

What it’s for: identifying where incoming funds come from, without treating that external bank account as a Capital Account in its own right. Funds received from a Linked Account appear on the Capital Account as an inbound transaction with a bank channel that names the Linked Account.

How it behaves:

  • A new Linked Account may start in pending_approval. Penny routes funds from it once its status is approved.
  • Account and routing numbers (or IBANs) are masked by default. Fetching the account individually with reveal_sensitive=true is the only way to see the real value; list results are always masked.
  • Deleting a Linked Account marks it deleted rather than erasing the record, preserving its history while Penny stops accepting it as a source of funds.

Details of where to send funds are coming soon.

See Linking an Account for the full registration, lookup, and lifecycle walkthrough.

How money moves

The diagram above shows account structure: who owns what. The diagram below shows the direction money moves:

incoming funds (bank)transfer / auto top-upscopes spendLinked AccountEXTERNALCapital AccountPARENTCapital AccountCHILD · NESTEDControl AccountCONTROL · NO BALANCE

Funds received from a Linked Account are how new money enters your Capital Account from outside Penny. Transfers and auto top-ups move money between Capital Accounts. Auto top-up is configuration, not a one-time action: it runs again whenever the account’s balance drops below its threshold. A Control Account never receives funds; spend through it is drawn directly from its Capital Account’s balance.

Account status and lifecycle

Every account (Capital, Control, or Linked) carries a status that governs whether it can be used. Capital and Control Accounts share the same lifecycle: active, deactivated, suspended, deleting, and deleted. Activating and deactivating both apply immediately. Deleting is asynchronous: the delete request returns the account in deleting along with a Task that completes the removal, so you can poll GET /tasks/{task_id} or re-fetch the account to confirm. Linked Accounts use their own statuses: created, pending_approval, approved, rejected, suspended, and deleted.

Account activity

Every Capital or Control Account exposes its own ledger and transaction history, so activity can always be traced back to the specific account it happened against.

Use:

  • Transactions to understand the state and lifecycle of financial activity. A Transaction’s account_id is always the one account it affected. Card spend scoped by a Control Account can also be listed through that Control Account (GET /accounts/control/{account_id}/transactions), and funds received from a Linked Account name it in the bank channel’s linked_account_id.
  • Ledger Entries to understand the resulting balance impact of that activity.

See Transactions & Ledger.