Sub Accounts

Overview

Sub-accounts allow you to create segregated accounts under your main institution account. This enables you to manage funds for different purposes or customers while maintaining them under your primary account structure. Sub-accounts are particularly useful for:

Creating virtual accounts for specific customers
Segregating funds for different business purposes
Managing funds on behalf of customers
Tracking balances and transactions separately

There are two main types of sub-accounts:

Institution sub-accounts - For your business purposes
Customer sub-accounts - For managing funds on behalf of your customers

Sub-accounts share the same currency as their parent account and can be configured to settle deposits to a separate main account (typically the parent main account).

The SubAccount Object

Property	Type	Required	Description
id	string (UUID)	✅	Unique identifier for the sub-account.
state	enum	✅	Current state of the sub-account (ACTIVE, FROZEN, CLOSED).
created_date	string (datetime)	✅	Date and time when the sub-account was created.
updated_date	string (datetime)	✅	Date and time when the sub-account was last updated.
currency	string	✅	Currency code of the sub-account (ISO 4217).
currency_precision	number	✅	Precision of the account currency, e.g. 2 for USD, meaning a balance value of 10000 is $100.00.
type	enum	✅	Type of the sub-account (VIRTUAL_EXTERNAL).
name	string	✅	Name of the sub-account holder.
balance	object	✅	Current balance information for the sub-account.
balance.available	number	✅	Available balance in minor units (cents/pence).
balance.pending	number	✅	Total value of pending transactions in minor units (cents/pence)
deposit_addresses	array	✅	List of payment methods or deposit addresses associated with this sub-account.
settlement_account_id	string (UUID)	❌	ID of the settlement account associated with this sub-account.
parent_account_id	string (UUID)	✅	ID of the parent VIRTUAL_MASTER tracking account associated with this sub-account.
customer	object	❌	Customer associated with this sub-account (only present for customer sub-accounts).
customer.id	string (UUID)	❌	ID of the customer associated with this sub-account.
customer.name	string	❌	Name of the customer associated with this sub-account.
customer.type	enum	❌	Type of the customer associated with this sub-account (INDIVIDUAL, BUSINESS).
customer.client_reference	string	❌	Client reference of the customer associated with this sub-account.
client_reference	string	❌	Your custom reference identifier for this sub-account.

📘
Account states:

PENDING_DEPOSIT_ADDRESS: We're still processing deposit details generation

ACTIVE: Account is fully operational

CLOSED: Account has been closed

FROZEN: Account is temporarily suspended

🚧
Note on PENDING_DEPOSIT_ADDRESS state
This state can occur when we cannot generate details instantly (e.g., due to bank service failures) and will transition to ACTIVE when complete. You should use the banking.sub-account.activated event as this guarantees the account is created and ready for use

Updated 2 months ago