Business Sub-Wallets
A sub-wallet (also called a business-issued wallet) is an additional wallet you can create under your own business — for example, to separate funds by purpose (payroll, vendor payments, project budgets) while still operating under the same business ID. Sub-wallets are funded from your main business wallet and can themselves be used as the source of a payout.
Related guides: Fund a Sub-Wallet · Bulk Fund Sub-Wallets · Pay Out From a Sub-Wallet
Create a Sub-Wallet
Request
POST {BASE_URL}/api/v1/business-sub-wallets
Required Parameters
| Parameter |
Type |
Description |
| businessId |
string |
Your business ID |
| walletName |
string |
A label for the sub-wallet (e.g. "Payroll Wallet") |
| currency |
string |
Currency code, e.g. NGN |
| reference |
string |
Your own unique reference for this sub-wallet. This is what you'll use later to fund it (see Bulk Fund Sub-Wallets), so choose something you can reliably look up |
| customer |
object |
Details of the sub-wallet's beneficial owner — see below |
| customer.name |
string |
Full name of the wallet's beneficial owner |
| customer.bvn |
string |
Bank Verification Number |
| customer.email |
string |
Valid email address |
| dob |
string |
Date of birth, format YYYY-MM-DD |
Other customer fields (optional):
| Field |
Type |
Description |
| customer.phone |
string |
International format, e.g. +2348012345678 |
| customer.externalId |
string |
Your own reference for this customer |
| customer.address |
object |
line1, line2, city, state, postalCode, countryCode |
| customer.nin |
string |
National Identification Number |
Optional Parameters
| Parameter |
Type |
Description |
| includeFundingAccount |
boolean |
Set to true to also provision a dedicated virtual bank account for this sub-wallet, using the customer details above. Defaults to false |
| notificationUrl |
string |
Callback URL for funding notifications on the account. Only used when includeFundingAccount=true |
- Path:
/api/v1/business-sub-wallets
- Method: POST
- Request Body:
{
"businessId": "your_business_id",
"walletName": "Payroll Wallet",
"reference": "PAYROLL-WALLET-001",
"currency": "NGN",
"customer": {
"name": "Jane Doe",
"bvn": "12345678901",
"email": "jane.doe@example.com",
"phone": "+2348012345678"
},
"dob": "1990-05-14",
"includeFundingAccount": false
}
Response
| Field |
Type |
Description |
| id |
string |
Sub-wallet record ID |
| businessId |
string |
Your business ID |
| walletId |
string |
The underlying wallet ID — use this wherever a wallet ID is expected (e.g. beneficiaryWalletId, walletId on transfer endpoints) |
| walletName |
string |
The label you gave the sub-wallet |
| customerName |
string |
The beneficial owner's name, as supplied in customer.name |
| email |
string |
The beneficial owner's email, as supplied in customer.email |
| reference |
string |
Your reference |
| currency |
string |
Currency of the sub-wallet |
| availableBalance |
double |
Current available balance |
| lienAmount |
double |
Amount currently on lien/hold |
| walletLimit |
object |
isPayoutAllowed, maxSinglePayout, minSinglePayout, maxDailyPayout |
| deleted |
boolean |
Whether the sub-wallet has been deleted |
| createdDate |
datetime |
Creation timestamp |
| lastUpdatedDate |
datetime |
Last update timestamp |
| fundingAccounts |
array |
accountName, accountNumber, bankName for each funding account provisioned (empty if none) |
{
"status": 200,
"message": "Success",
"data": {
"id": "sub-wallet-id",
"businessId": "your_business_id",
"walletId": "wallet_uuid",
"walletName": "Payroll Wallet",
"customerName": "Jane Doe",
"email": "jane.doe@example.com",
"reference": "PAYROLL-WALLET-001",
"currency": "NGN",
"availableBalance": 0.00,
"lienAmount": 0.00,
"walletLimit": {
"isPayoutAllowed": true,
"maxSinglePayout": 1000000.00,
"minSinglePayout": 100.00,
"maxDailyPayout": 5000000.00
},
"deleted": false,
"createdDate": "2026-01-01 01:01:01",
"lastUpdatedDate": "2026-01-01 01:01:01",
"fundingAccounts": []
}
}
Notes
- Your business must have sub-wallet creation enabled. If it isn't, this request is rejected — contact support to have it turned on.
customer.bvn and customer.email must both be non-blank — this is required for every sub-wallet, whether or not you request a funding account.- Requesting
includeFundingAccount=true additionally requires funding-account provisioning to be enabled on your business.
(businessId, reference) must be unique — creating a second sub-wallet with a reference you've already used returns a 409 Conflict.- A newly created sub-wallet always starts with a zero balance.
customer.bvn and dob are captured but not returned in any response — only customerName and email are echoed back.
Search / List Sub-Wallets
Request
GET {BASE_URL}/api/v1/business-sub-wallets?merchantId={merchantId}
Query Parameters
| Parameter |
Type |
Description |
| merchantId |
string |
Required |
| id |
string |
Filter by sub-wallet record ID |
| walletId |
string |
Filter by underlying wallet ID |
| walletName |
string |
Filter by exact wallet name |
| reference |
string |
Filter by exact reference |
| currency |
string |
Filter by currency |
| deleted |
boolean |
Filter by deleted status |
| businessIds |
string (array) |
Filter by business IDs |
| createdFrom |
date |
Filter by creation date (format: YYYY-MM-DD) |
| createdTo |
date |
Filter by creation date (format: YYYY-MM-DD) |
| lastUpdatedFrom |
date |
Filter by last-updated date (format: YYYY-MM-DD) |
| lastUpdatedTo |
date |
Filter by last-updated date (format: YYYY-MM-DD) |
| pageNo |
number |
Page number (default 1) |
| pageSize |
number |
Page size (default 30) |
Response
A paginated list — same shape as Fetch List of Transfer Requests (pageNo, pageSize, lastPage, totalNumberOfItems, content), where each item in content has the same shape as the Create a Sub-Wallet response, with availableBalance/lienAmount/walletLimit reflecting live values.
Search Sub-Wallet Transactions
Request
GET {BASE_URL}/api/v1/business-sub-wallets/transactions?merchantId={merchantId}
Query Parameters
| Parameter |
Type |
Description |
| merchantId |
string |
Required |
| id |
string |
Filter by transaction ID |
| transactionType |
string |
Filter by type (CREDIT, DEBIT, LIEN, REVERSAL, UNLIEN) |
| onusReference |
string |
Filter by system-generated reference |
| referenceId |
string |
Filter by the underlying transfer/payment ID |
| walletIds |
string (array) |
Filter by sub-wallet's underlying wallet IDs |
| businessIds |
string (array) |
Filter by business IDs |
| currency |
string |
Filter by currency |
| createdFrom |
date |
Filter by creation date (format: YYYY-MM-DD) |
| createdTo |
date |
Filter by creation date (format: YYYY-MM-DD) |
| pageNo |
number |
Page number (default 1) |
| pageSize |
number |
Page size (default 30) |
Response
A paginated list of transactions, same shape as Fetch Wallet Transactions.
Download Sub-Wallet Transactions
Request
GET {BASE_URL}/api/v1/business-sub-wallets/transactions/download?merchantId={merchantId}&recipientEmail={email}&recipientName={name}
Query Parameters
| Parameter |
Type |
Description |
| merchantId |
string |
Required |
| recipientEmail |
string |
Required. The generated report is emailed here — it is not returned in the response body |
| recipientName |
string |
Required |
| transactionType |
string |
Filter by type (CREDIT, DEBIT, LIEN, REVERSAL, UNLIEN) |
| walletId |
string |
Filter to a single sub-wallet's underlying wallet ID. Required if accountStatement=true |
| businessIds |
string (array) |
Filter by business IDs |
| currency |
string |
Filter by currency |
| createdFrom |
date |
Filter by creation date (format: YYYY-MM-DD) |
| createdTo |
date |
Filter by creation date (format: YYYY-MM-DD) |
| accountStatement |
boolean |
If true, generates a PDF statement for a single sub-wallet (requires walletId). If false (default), generates a CSV of matching transactions |
| address |
string |
Address to print on a PDF statement |
Response
This endpoint triggers report generation asynchronously — it returns immediately and the file is delivered by email to recipientEmail, not returned in the response body.
{
"status": 200,
"message": "Success",
"data": null
}
Notes
- If you supply
walletId, it must reference a sub-wallet you own (via a business under merchantId) — otherwise the request returns 404 Not Found.