Sub-account creation

This feature is designed for companies offering embedded financial experiences or managing distinct client portfolios, providing full visibility and control across all connected accounts.

Key Benefits & Behavior

Embedded Experience: Offer a Verto-like experience (wallets and local accounts) directly to your users.
Oversight: Maintain complete control and visibility while extending transactional capabilities downstream.
Compliance: Each sub-account operates safely under the parent company's compliance framework.

Sub-Accounts Structure

Parent Account
│
├── Sub-Account
│   ├── NGN Wallet
│   │   └── Local Account
│   ├── KES Wallet
│   │   └── Local Account
│
└── Sub-Account
    ├── KES Wallet
    │   └── Local Account
    ├── NGN Wallet
        └── Local Account

How to Create Sub-Accounts

Before creating a sub-account:

Ensure your Parent Account has been explicitly enabled for sub-account creation by an authorised Verto representative. Contact your account manager for this step.
Review the Restricted Industries list to ensure your downstream client’s industry classification is supported.
Gather the legal entity name, jurisdiction, industry category, and registry or identification number for the customer.

There are two distinct ways to create sub accounts via Verto

Method 1: Through the Verto Dashboard (Non-Technical / Operations)

Log in to your Parent Account.
Navigate to Linked Accounts → Add Sub-Account.
Fill in the required details: Legal Name, Industry Category, Registration Number, and External ID.
Click Update. The sub-account will be created. You will be redirected to a new page to submit KYB/KYC info on your sub account. At this point, the sub-account will have a KYC PENDING status.
Upload the required compliance documents (e.g., Certificate of Incorporation, UBO IDs, Proof of Address, etc) to initiate onboarding.

Method 2: Through the Verto API (Technical / Engineers)

Developers can programmatically provision sub-accounts through a dedicated API workflow. Each sub-account represents an entity (client or subsidiary) operating under the parent company’s compliance framework.

For the complete API specification and test console, visit this link

Endpoint

POST [https://api-company-sandbox.vertofx.com/sub-accounts]

This endpoint allows partners to create sub-accounts directly via API.

Headers

Key	Value	Description
`Authorization`	`Bearer <token>`	JWT access token for authentication.
`Content-Type`	`application/json`	Required.
`Accept`	`application/json`	Required.

Required Body Parameters

Field	Type	Required	Description
`name`	string	✅	Legal name of the company (as registered).
`country`	string	✅	Country where the sub-account is registered (ISO Alpha-2 format).
`subCategory`	string	✅	Company’s industry classification.
`identificationNumber`	string	✅	Registration or incorporation number issued by the local authority.
`taxIdOrEin`	string	❌	Tax identification number or equivalent (if applicable).
`externalId`	string	❌	The company reference ID in your system (for internal mapping).
`accountType`	string	✅	Defines the sub account's relationship type, and is tied to the use-case: Use `SUB_CLIENT` (Fintech cases) or `PARTNER_REFERRED` (Platform cases).

[!IMPORTANT] Strict Validation on subCategory Ensure to validate subCategory before sending the request.

To avoid a 400 Bad Request (Invalid input Please provide a valid company sub-category)error, normalize your internal mapping to match Verto's exact casing and spacing before hitting the API.

Review the Supported Industries List: Supported industries

Supported Account Types

Value	Description
`PARTNER_REFERRED`	Used when the end-client has a direct financial relationship with Verto.
`SUB_CLIENT`	Used when the end-client's relationship with Verto is through a licensed/regulated financial services provider. (Strictly only for Fintech use cases).

Example Request

{
  "name": "string",
  "country": "United Kingdom",
  "subCategory": "Agriculture and farming",
  "identificationNumber": "string",
  "taxIdOrEin": "string",
  "externalId": "string",
  "accountType": "PARTNER_REFERRED"
}

Example Response 201

{
  "id": "string",
  "externalId": "string",
  "parentCompanyId": "string",
  "name": "string",
  "country": null,
  "category": "string",
  "subCategory": "string",
  "identificationNumber": "string",
  "taxIdOrEin": "string",
  "accountType": "PARTNER_REFERRED",
  "companyReference": "string",
  "companyStatus": "CREATED",
  "linkedStatus": "PENDING",
  "linkedAt": "2025-11-12T15:58:37.175Z",
  "createdAt": "2025-11-12T15:58:37.175Z",
  "updatedAt": "2025-11-12T15:58:37.175Z"
}

Response Codes

Code	Meaning	Description
`201 Created`	✅	Sub-account successfully created.
`400 Bad Request`	❌	Missing or invalid fields in the request.
`401 Unauthorized`	❌	Invalid or expired token.
`403 Forbidden`	❌	Insufficient permissions.
`404 Not Found`	❌	Parent account not found.
`500 Internal Server Error`	❌	Unexpected system error

If you receive a 400 Bad Request for an invalid company sub-category, check that your submitted subCategory matches the supported industries list exactly, including spacing and capitalization.

⚓
NOTE: Store the returned id from the response, as you will need it for downstream onboarding, wallet setup, and scoped transactions.

Next Steps

Creating a sub-account is only the first step and does not mean the account is ready for immediate use.

Upon creation, its initial status is KYC PENDING. To activate the account, you must submit the required compliance information via the Add Onboarding Data endpoint. Refer to the Sub-account Onboarding guide .

The sub-account will remain unusable for wallets or downstream operations until it is officially reviewed and its status updated to approved by our onboarding team.