ClearBank.Accounts (ClearBank v1.0.0)

GBP Account management — real and virtual accounts.

Real accounts

When you join ClearBank, four accounts are provisioned automatically:

Operational Account
General Segregation Account
Bacs Suspense Account
Mandated Minimum Balance Account

You can create additional real accounts of most types via create/2.

Virtual accounts

Virtual accounts exist on your platform; their funds sit in a parent real account at ClearBank. You are responsible for reconciliation. Each has a virtual IBAN (vIBAN).

Account types

Atom	API value	Purpose
`:your_funds`	`YourFunds`	Operational: your own institution funds
`:client_money_pooled`	`ClientMoneyPooled`	CASS 7 pooled client money
`:client_money_designated`	`ClientMoneyDesignated`	CASS 7 designated per client
`:segregated_pooled`	`SegregatedPooled`	Pooled customer funds
`:segregated_designated`	`SegregatedDesignated`	Designated per customer
`:safeguarded_pooled`	`SafeguardedPooled`	FCA CASS 15 safeguarding
`:safeguarded_designated`	`SafeguardedDesignated`	CASS 15 designated
`:client_suspense`	`ClientSuspense`	Embedded Banking partners only

Note: From 7 May 2026, all FCA-regulated payment/e-money institutions must hold at least one safeguarded account. Submit a CASS 15-compliant letter to ClearBank annually.

Summary

Types

account_type()

Functions

create(client, params)

Creates a new real GBP account.

create_virtual(client, account_id, params)

Creates a new virtual account under a real account.

get(client, account_id)

Returns a single real GBP account by ID.

get_virtual(client, account_id, virtual_account_id)

Returns a specific virtual account.

list(client, opts \\ [])

Returns all real GBP accounts for your institution.

list_virtual(client, account_id, opts \\ [])

Returns all virtual accounts under a real account.

update(client, account_id, params)

Amends a real GBP account (e.g. rename, enable/disable CoP).

update_virtual(client, account_id, virtual_account_id, params)

Amends a virtual account.

Types

account_type()

@type account_type() ::
  :your_funds
  | :client_money_pooled
  | :client_money_designated
  | :segregated_pooled
  | :segregated_designated
  | :safeguarded_pooled
  | :safeguarded_designated
  | :client_suspense

Functions

create(client, params)

@spec create(
  ClearBank.Client.t(),
  keyword()
) :: ClearBank.HTTP.result()

Creates a new real GBP account.

Required params

:account_name - display name for the account
:account_type - one of the account type atoms above

Optional params

:sort_code - override sort code (if permitted)
:usage_type - :payments | :savings
:minimum_balance - minimum balance enforcement

Examples

{:ok, account} = ClearBank.Accounts.create(client,
  account_name: "Client Pool GBP",
  account_type: :segregated_pooled
)

create_virtual(client, account_id, params)

@spec create_virtual(ClearBank.Client.t(), String.t(), keyword()) ::
  ClearBank.HTTP.result()

Creates a new virtual account under a real account.

Required params

:account_name - display name

Optional params

:owner - owner reference string (for your records)
:sort_code - override sort code if permitted

Examples

{:ok, virtual} = ClearBank.Accounts.create_virtual(client, "acct-uuid",
  account_name: "Customer ABC Virtual"
)

get(client, account_id)

@spec get(ClearBank.Client.t(), String.t()) :: ClearBank.HTTP.result()

Returns a single real GBP account by ID.

Examples

{:ok, account} = ClearBank.Accounts.get(client, "acct-uuid")

get_virtual(client, account_id, virtual_account_id)

@spec get_virtual(ClearBank.Client.t(), String.t(), String.t()) ::
  ClearBank.HTTP.result()

Returns a specific virtual account.

Examples

{:ok, virtual} = ClearBank.Accounts.get_virtual(client, "acct-uuid", "virt-uuid")

list(client, opts \\ [])

@spec list(
  ClearBank.Client.t(),
  keyword()
) :: ClearBank.HTTP.result()

Returns all real GBP accounts for your institution.

Options

:page_number - page (default: 1)
:page_size - results per page (default: 50)

Examples

{:ok, accounts} = ClearBank.Accounts.list(client)
{:ok, accounts} = ClearBank.Accounts.list(client, page_number: 1, page_size: 20)

list_virtual(client, account_id, opts \\ [])

@spec list_virtual(ClearBank.Client.t(), String.t(), keyword()) ::
  ClearBank.HTTP.result()

Returns all virtual accounts under a real account.

Examples

{:ok, virtuals} = ClearBank.Accounts.list_virtual(client, "acct-uuid")

update(client, account_id, params)

@spec update(ClearBank.Client.t(), String.t(), keyword()) :: ClearBank.HTTP.result()

Amends a real GBP account (e.g. rename, enable/disable CoP).

Examples

{:ok, _} = ClearBank.Accounts.update(client, "acct-uuid",
  account_name: "New Name"
)

update_virtual(client, account_id, virtual_account_id, params)

@spec update_virtual(ClearBank.Client.t(), String.t(), String.t(), keyword()) ::
  ClearBank.HTTP.result()

Amends a virtual account.

Examples

{:ok, _} = ClearBank.Accounts.update_virtual(client, "acct-uuid", "virt-uuid",
  account_name: "Updated Name"
)