> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payaza.africa/llms.txt
> Use this file to discover all available pages before exploring further.
# Sub Accounts
> Create and manage Payaza sub-accounts for internal business units. Sub-accounts are strictly for segmenting operations within your own organization — not for onboarding external customers or merchants.
## Overview
Sub-accounts allow you to create isolated Payaza accounts under your main merchant account for **internal business units** — for example, your Finance department, Admin team, or separate cost centers. Each sub-account operates independently for collections and payouts while remaining fully visible and controllable from your main account.
Sub-accounts are designed strictly for **internal organizational use**. They
are not intended for onboarding external customers, clients, or third-party
merchants. Using sub-accounts for external merchant onboarding violates
Payaza's compliance requirements and may result in account suspension.
Approved use cases:
* **Finance department** — separate ledger for finance team operations and disbursements
* **Admin unit** — isolated account for operational expenses and vendor payments
* **Cost centers** — segment revenue and spend by internal division or project
***
## Key Requirements
Use your **public API key** encoded in Base64. See the [Authentication
guide](/guides/authentication) for setup instructions.
Set these headers on every request:
```json theme={null}
{
"Authorization": "Payaza ",
"X-TenantID": "test",
"Content-Type": "application/json"
}
```
Switch `X-TenantID` to `live` when operating in the production environment.
***
## Endpoints
| Method | Endpoint | Description |
| ------ | --------------------------------------------------------------------------------- | ----------------------------------------- |
| `POST` | `/payaza-account/api/v1/subaccounts/merchant` | Create a new sub-account |
| `GET` | `/payaza-account/api/v1/subaccounts/merchant/enquiry/{payazaSubAccountReference}` | Retrieve sub-account details by reference |
***
## How it works
Call the Create endpoint with the sub-account name and the required business
details. On success, you receive a `payazaSubAccountReference` — store this
immediately against the relevant internal unit in your system.
Pass the `payazaSubAccountReference` in your transfer and collection
requests to route transactions to the correct internal unit.
Use the Enquiry endpoint with the sub-account reference to fetch the current
balance, account status, and account details at any time.
***
## Create a sub-account
```bash cURL theme={null}
curl --request POST \
--url https://api.payaza.africa/live/payaza-account/api/v1/subaccounts/merchant \
--header 'authorization: Payaza ' \
--header 'content-type: application/json' \
--header 'x-tenantid: test' \
--data '{
"mainAccountPayazaReference": "100000000",
"name": "Test Sub Account",
"currency": "NGN",
"country": "NGA"
}'
```
**Request parameters**
| Parameter | Type | Required | Description |
| ---------------------------- | -------- | -------- | ------------------------------------------------ |
| `mainAccountPayazaReference` | `string` | Yes | The account reference of the main Payaza account |
| `name` | `string` | Yes | The name of this subaccount |
| `currency` | `string` | Yes | The currency code |
| `country` | `string` | Yes | The country code in ISO 3166-1 alpha-3 format |
**Sample response**
```json theme={null}
{
"message": "New account created",
"status": true,
"data": [
{
"id": 1110,
"accountName": "Test Sub Account",
"accountStatus": "ACTIVE",
"accountBalance": 0,
"escrowBalance": 0,
"businessFk": 11407,
"currency": "NGN",
"owner": "PAYAZA",
"country": "NGA",
"creationReference": "DC625576B5BF426A94CB6B1D868C0",
"actionStatus": "ACTIVE",
"payazaAccountReference": "2010000120",
"pnc": false,
"pnd": false,
"virtualAccounts": [
{
"accountNumber": "9977719429",
"accountName": "MERCHANT(Test Sub Account)",
"bankCode": "000023"
}
]
}
]
}
```
***
## Retrieve sub-account details
```bash cURL theme={null}
curl --request GET \
--url https://api.payaza.africa/live/payaza-account/api/v1/subaccounts/merchant/enquiry/{{payazaSubAccountReference}} \
--header 'Authorization: Payaza ' \
--header 'X-TenantID: test'
```
| Parameter | Type | Required | Description |
| --------------------------- | -------- | -------- | --------------------------------------------------------------------- |
| `payazaSubAccountReference` | `string` | Yes | The account reference of the Payaza sub account that has been created |
**Sample response**
```json theme={null}
{
"message": "Account enquiry response",
"status": true,
"data": [
{
"id": 1110,
"accountName": "Test Sub Account",
"payazaAccountReference": "2010000120",
"status": "ACTIVE",
"accountBalance": 0,
"businessId": 11407,
"currency": "NGN",
"country": "NGA",
"organizationName": "PAYAZA",
"productCode": "PAYOUT-SUB-NGN",
"productNumber": "201",
"postNoCredit": false,
"postNoDebit": false,
"originatorName": null,
"pauseTransactions": null,
"hasVirtualAccounts": true,
"virtualAccounts": [
{
"accountNumber": "9977719429",
"accountName": "MERCHANT(Test Sub Account)",
"bankCode": "000023",
"bankId": 2789
}
],
"createdDate": "2023-11-09T13:05:15.611669"
}
],
"pageDetail": {
"sorted": false,
"pageNumber": 0,
"pageSize": 0,
"paged": false,
"totalPages": 0,
"totalElements": 0,
"last": false,
"size": 0,
"number": 0,
"numberOfElements": 0,
"offset": null
},
"totalCount": 0,
"responseCode": null
}
```
***
## Compliance requirements
Sub-accounts are subject to your organization's KYB (Know Your Business) approval. The following rules apply:
* Sub-accounts must map to **real, identifiable internal units** within your organization
* Each sub-account must have a documented owner or responsible team
* Transaction flows through sub-accounts are audited — ensure all activity aligns with the stated purpose of the unit
* Do not create sub-accounts as pass-through accounts for unrelated third parties
Contact [support@payaza.africa](mailto:support@payaza.africa) if you need clarification on what constitutes an approved sub-account use case before proceeding.
***
## Best practices
* Map each sub-account to exactly one internal unit — never share a reference across unrelated departments
* Store `payazaSubAccountReference` durably in your database immediately after creation — it cannot be recovered if lost
* Use the Enquiry endpoint to verify a sub-account's status before routing live transactions to it
* Scope system access so that only the authorized team can initiate transactions from each sub-account
***
## What's next
Send payouts from your Payaza account or sub-account to a beneficiary.
View balances and account references across all currencies.