Accounts

Accounts are the fundamental units for managing funds within the platform. Each account represents a currency-specific container that tracks balances and facilitates various financial operations.

Core Characteristics

Feature	Description
Currency	Each account operates in exactly one currency (e.g., USD, EUR, GBP)
Balance Tracking	Maintains available and pending balances for a specific currency. For Master Accounts, this tracks the total balances in all related sub-accounts
Hierarchy	Can participate in parent-child relationships for organizational structure
Deposit Address	May have associated deposit addresses for receiving external funds

Account Object

Property	Type	Required	Description
id	string (UUID)	✅	Unique identifier for the account
state	enum	✅	Current state of the account (ACTIVE, FROZEN, CLOSED).
created_date	string (datetime)	✅	Date and time when the account was created.
updated_date	string (datetime)	✅	Date and time when the account was last updated.
currency	string	✅	Currency code of the 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 account (VIRTUAL_EXTERNAL).
name	string	✅	Name of the account holder.
balance	object	✅	Current balance information for the 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.

Deposit Address Object

Parameter	Type	Required	Description
id	string	✅	Unique identifier for the deposit address.
type	string	✅	Payment network type. Can be one of: `SWIFT` - International wire transfers `SEPA` - European transfers in EUR `ACH` - US domestic transfers `FASTER_PAYMENTS` - UK domestic transfers `FED_WIRE` - Same-day US transfers `NUBAN` - Nigerian bank transfers `BANK_ACCOUNT` - Any bank account type `MOBILE_MONEY` - Kenyan Mobile Money
data	object	✅	Contains payment network-specific details. Structure varies by type.
identifier	string	✅	The primary identifier for the deposit address (e.g., account number, IBAN).
account_holder_name	string	✅	Name of the account holder associated with this deposit address.

Account Address Data Examples - `deposit_address[n].data`

{
  "nip_code": "000017",
  "bank_code": "035",
  "bank_name": "Wema",
  "account_name": "Waza Technologies Inc.",
  "account_number": "9391282750"
}

{
    "bank_name": "The Lync Bank",
    "swift_bic": "TBGGB3L",
    "bank_address": {
      "city": " London",
      "line_1": "14 Emirates Street",
      "line_2": " The Big Building",
      "country": "GB",
      "postal_code": " E18 2TH"
    },
    "account_number": "GB63TBGH04142341255222"
}

{
    "iban": "GB29TBGG60161331926819",
    "bank_name": "The Lync Bank",
    "bic_swift": "TBGGB3L",
    "bank_address": {
      "city": " London",
      "line_1": "14 Emirates Street",
      "line_2": " The Big Building",
      "country": "GB",
      "postal_code": " E18 2TH"
    },
  }

{
    "bank_name": "The Lync Bank",
    "sort_code": "041234",
    "bank_address": {
      "city": " London",
      "line_1": "14 Emirates Street",
      "line_2": " The Big Building",
      "country": "GB",
      "postal_code": " E18 2TH"
    },
    "account_number": "41255089"
  }

{
    "bank_name": "First National Trust Bank",
    "account_type": "checking",
    "bank_address": {
      "city": "Chicago",
      "line_1": "245 Michigan Avenue",
      "line_2": "Suite 1200",
      "country": "US",
      "state": "IL",
      "postal_code": "60601"
    },
    "account_number": "7481592630",
    "routing_number": "071000013"
  }

{
    "bank_name": "Metropolitan National Bank",
    "bank_address": {
      "city": "Boston",
      "line_1": "350 State Street",
      "line_2": "Financial District",
      "country": "US",
      "state": "MA",
      "postal_code": "02109"
    },
    "account_number": "9257483610",
    "routing_number": "011401533"
  }

{
    "method": "PHONE",
    "details": {
      "phone_number": "+2547007000000"
    }
  }

{
    "method": "TILL",
    "details": {
      "till_number": "4433212"
    }
  }

{
    "method": "PAYBILL",
    "details": {
      "paybill_number": "4443112",
      "account_number": "2704600",
    }
  }

{
    "bank_code": "0003",
    "bank_name": "I&M Bank",
    "swift_bic": "IMBLKENA",
    "branch_name": "SARIT CENTER",
    "account_name": "Kiotapay",
    "country_code": "KE",
    "account_number": "514812724641985"
}

Account Types and Capabilities

Account Type	Primary Use Case	Key Capabilities	Limitations
VIRTUAL_EXTERNAL	General-purpose accounts for everyday banking operations	Receive external deposits Send outbound payments Initiate currency exchanges Hold and manage balances	N/A
VIRTUAL_WALLET	Dedicated account for internal fund management and conversion operations	Hold allocated funds Convert to/from other currencies Receive prefunding transfers Process withdrawals to external accounts	Cannot receive external deposits Limited to internal fund movements Requires manual prefunding
VIRTUAL_MASTER	Aggregate accounting for sub-account portfolios	Can Track pooled balances across all child subaccounts Facilitate reporting and oversight Provide a consolidated view of institutional funds	Cannot directly receive or send payments Balance is informational (sum of associated subaccounts) No direct deposit capability

Account Groupings

Grouping	Ownership	Types	Capabilities
Institution Main Accounts	Owned directly by the institution	`VIRTUAL_EXTERNAL`, `VIRTUAL_WALLET`	Payment capabilities including transfers and conversions `VIRTUAL_EXTERNAL` can receive deposits from external sources via deposit addresses `VIRTUAL_WALLET` can only receive prefunded deposits Primary accounts for institutional operations
Institution Master Accounts	Owned by the institution	`VIRTUAL_MASTER`	Serves as a parent account for related customer/institution subaccounts The balance represents the aggregate of all linked sub-accounts No direct payment operations
Customer Sub-Accounts	Owned by a customer of the institution	`VIRTUAL_EXTERNAL`	The parent account is always a `VIRTUAL_MASTER` account Can receive deposits. Can auto-settle deposits into a main account Other payment operations may be restricted based on configuration

📘
Deposit Capability
The presence of a deposit address on an account indicates that it can receive funds from external sources. Not all account types support deposit addresses.

Core Characteristics

Account Object

Deposit Address Object

Account Address Data Examples - deposit_address[n].data

Account Types and Capabilities

Account Groupings

Deposit Capability

Account Address Data Examples - `deposit_address[n].data`