Freeze Sub-Account

It temporarily freezes a sub-account to prevent transactions to or from the account. This is useful for situations such as suspected fraud, compliance issues, or at the customer's request.

Endpoint: POST /v2/sub-accounts/{id}/freeze

Path Parameters

Parameter	Type	Required	Description
id	string (UUID)	✅	Unique identifier of the sub-account to freeze.

Request Body Parameters

Parameter	Type	Required	Description
reason	enum	✅	Reason for freezing the account. Valid values: "FRAUD", "OTHER".

Example Request

{
  "reason": "FRAUD"
}

Example Response

{
  "data": {
    "id": "abcdef12-3456-7890-abcd-ef1234567890",
    "state": "FROZEN",
    "client_reference": "proc-123"
  }
}

Freeze Sub-Account by Client Reference

Freeze a sub-account using your client reference instead of the account ID.

Endpoint: POST /v2/sub-accounts/by-client-reference/{client_reference}/freeze

Path Parameters

Parameter	Type	Required	Description
client_reference	string	✅	Your custom reference for the sub-account.

Request Body Parameters

Parameter	Type	Required	Description
reason	enum	✅	Reason for freezing the account. Valid values: "FRAUD", "COMPLIANCE", "AML", "CUSTOMER_REQUEST", "SUSPICIOUS_ACTIVITY", "OTHER".

Example Response

{
  "data": {
    "id": "abcdef12-3456-7890-abcd-ef1234567890",
    "state": "FROZEN",
    "client_reference": "proc-123"
  }
}

Unfreeze Sub-Account

Removes the freeze on a sub-account to allow transactions.

Endpoint: POST /v2/sub-accounts/{id}/unfreeze

Path Parameters

Parameter	Type	Required	Description
id	string (UUID)	✅	Unique identifier of the sub-account to unfreeze.

Example Response

{
  "data": {
    "id": "abcdef12-3456-7890-abcd-ef1234567890",
    "state": "ACTIVE",
    "client_reference": "proc-123"
  }
}

Unfreeze Sub-Account by Client Reference

Unfreeze a sub-account using your client reference instead of the account ID.

Endpoint: POST /v2/sub-accounts/by-client-reference/{client_reference}/unfreeze

Path Parameters

Parameter	Type	Required	Description
client_reference	string	✅	Your custom reference for the sub-account.

Example Response

{
  "data": {
    "id": "abcdef12-3456-7890-abcd-ef1234567890",
    "state": "ACTIVE",
    "client_reference": "proc-123"
  }
}

Sub-Account Pooled Balance Operations

Get Pooled Sub-Account Balances by Currency

Retrieves the combined balance information for all sub-accounts in a specific currency.

Endpoint: GET /v2/sub-accounts/pooled-balances/{currency}

Path Parameters

Parameter	Type	Required	Description
currency	string	✅	Currency code (ISO 4217, e.g., "USD", "EUR", "NGN") to get pooled balances for.

Response Object

Property	Type	Description
id	string (UUID)	ID of the master account for this currency.
currency	string	Currency code of the pooled balances.
total_available	number	Total available balance across all sub-accounts in this currency in minor units (cents/pence).
total_pending	number	Total pending balance across all sub-accounts in this currency in minor units (cents/pence).
total_sub_accounts	number	Total number of sub-accounts in this currency.

Example Response

{
  "data": {
    "id": "12345678-1234-1234-1234-123456789012",
    "currency": "NGN",
    "total_available": 5250000,
    "total_pending": 5350000,
    "total_sub_accounts": 5
  }
}

Get All Pooled Sub-Account Balances

Retrieves the combined balance information for all sub-accounts across all currencies.

Endpoint: GET /v2/sub-accounts/pooled-balances/all

Response Object

An array of pooled balance objects:

Property	Type	Description
id	string (UUID)	ID of the master account for this currency.
currency	string	Currency code of the pooled balances.
total_available	number	Total available balance across all sub-accounts in this currency in minor units (cents/pence).
total_pending	number	Total pending balance across all sub-accounts in this currency in minor units (cents/pence).
total_sub_accounts	number	Total number of sub-accounts in this currency.

Example Response

{
  "data": [
    {
      "id": "12345678-1234-1234-1234-123456789012",
      "currency": "USD",
      "total_available": 5250000,
      "total_pending": 5350000,
      "total_sub_accounts": 5
    },
    {
      "id": "87654321-4321-4321-4321-210987654321",
      "currency": "EUR",
      "total_available": 3150000,
      "total_pending": 3200000,
      "total_sub_accounts": 3
    },
    {
      "id": "13579246-2468-1357-9246-135792468024",
      "currency": "NGN",
      "total_available": 750000000,
      "total_pending": 760000000,
      "total_sub_accounts": 2
    }
  ]
}