Guides

Creating a Sub account

Sub-Account Creation API

This endpoint allows you to create a new sub-account under your institution. You can create two types of sub-accounts: institution sub-accounts and customer sub-accounts.

Endpoint: POST /v2/sub-accounts

Request Parameters

Common Parameters (Both Sub-Account Types)

ParameterTypeRequiredDescription
classificationenum✅Type of sub-account to create: "institution" or "customer".
currencystring✅Currency code of the sub-account (ISO 4217, e.g., "USD", "EUR", "NGN", "KES").
client_referencestring❌Your custom reference identifier for this sub-account (max length: 64).
settlement_account_idstring (UUID)❌ID of the institution's main account to settle into in the same currency. When external deposits to this sub-account, they will be automatically settled into the provided settlement account.

Institution Sub-Account Specific Parameters

ParameterTypeRequiredDescription
classificationenum✅Must be set to "institution".
identifierstring✅A unique identifier for the institution sub-account (max length: 64).

Customer Sub-Account Specific Parameters

ParameterTypeRequiredDescription
classificationenum✅Must be set to "customer".
customer_idstring (UUID)✅Unique identifier of the customer for whom the sub-account is being created.

Example Requests

Create an Institution Sub-Account

{
  "classification": "institution",
  "identifier": "procurement-123",
  "currency": "NGN",
  "client_reference": "proc-123",
  "settlement_account_id": "abcdef12-3456-7890-abcd-ef1234567890"
}

Create a Customer Sub-Account

{
  "classification": "customer",
  "customer_id": "abcdef12-3456-7890-abcd-ef1234567890",
  "currency": "NGN",
  "client_reference": "customer-456",
  "settlement_account_id": "fedcba98-7654-3210-fedc-ba9876543210"
}

Response

Upon successful creation, the API returns a 201 Created status and the details of the newly created sub-account.

{
  "data": {
    "id": "abcdef12-3456-7890-abcd-ef1234567890",
    "state": "ACTIVE",
    "created_date": "2023-05-14T10:30:45Z",
    "updated_date": "2023-05-14T10:35:22Z",
    "currency": "NGN",
    "currency_precision": 2,
    "type": "VIRTUAL_EXTERNAL",
    "name": "Procurement Department",
    "balance": {
      "available": 0,
      "pending": 0
    },
    "deposit_addresses": [
      {
        "type": "NUBAN",
        "data": {
          "nip_code": "115829",
          "bank_code": "778604",
          "bank_name": "Waza Bank",
          "account_name": "Institution - Procurement Department",
          "account_number": "4999774722"
        }
      }
    ],
    "settlement_account_id": "abcdef12-3456-7890-abcd-ef1234567890",
    "parent_account_id": "12345678-1234-1234-1234-123456789012",
    "client_reference": "proc-123"
  }
}

Requirements

Requirements for creating sub-accounts vary by currency and customer type.

Nigerian Naira (NGN)

Business Customers

PropertyTypeDescription
business.incorporation_numberstringCompany registration/incorporation number
business.incorporation_datestringDate of company incorporation (YYYY-MM-DD )
country_data.ng.bvnstringBank Verification Number (BVN)

Kenyan Shilling (KES)

Business Customers

PropertyTypeDescription
business.phone_numberstringBusiness phone number
emailstringEmail address

Individual Customers

PropertyTypeDescription
individual.phone_numberstringIndividual phone number
emailstringEmail address


📘

With settlement_account_id specified

  • The currency of the sub-account must match the currency of the settlement account
  • All deposit from external sources will be routed and settled to the specified settlement_account_id which must be main account of type VIRTUL_EXTERNAL.
  • The payment object of deposit will include an on_behalf_of_account_id property that hints at the funds being routed into it from the a sub-account.
  • Use this option if you want to manage a single pool main account with sub-accounts acting as different routes to deposit funds through

🚧

Note

PENDING_DEPOSIT_ADDRESS occurs when we cannot generate details instantly (e.g., due to bank service failures) and will transition to ACTIVE when complete.

Notes

  • Institution sub-accounts are useful for segregating funds for different departments or purposes within your organization.