> ## Documentation Index
> Fetch the complete documentation index at: https://doc.seerbit.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Sub-account creation
> Register the parties you settle to, and get a sub-account code for each.
**Ideal for**: Paying more than one party out of a single customer payment — a marketplace paying its sellers, a platform taking commission, a business settling across branches or departments.
## How it works
A **sub-account** is a settlement destination you register once. It represents whoever gets paid — a seller, a partner, a department — and has its own bank details and a `subAccountCode`.
A **split** is what you send at payment time. It names which sub-accounts share a given payment and how much each receives.
Register each party once, on this page. You get back a `subAccountCode` for each.
At payment time, reference those codes — either through a pre-configured split rule, or inline per transaction. See [split settlement](/platforms/split-settlement).
Funds reach each sub-account directly. You do not receive the whole amount and pay people out afterwards.
> **Sub-accounts are not payouts.** A split settles automatically as part of the payment. If you need to send money to someone independently of a customer payment, use [payouts](/online-payments/payment-features/payout) instead.
## Prerequisites
> Before you begin, ensure you have the following:
* SeerBit Merchant Account - Sign up at [dashboard.seerbit.com](https://dashboard.seerbit.com/#/auth/register)
* **API Keys** - Retrieve your Public Key and Secret Key from your merchant dashboard under **Settings > API Keys**.
* Public Key (starts with SBTESTPUBK\* for test environment or SBPUBK\* for live)
* Secret Key (starts with SBTESTSECK\* for test environment or SBSECK\* for live)
## Authentication
Sub-account calls are authenticated with a **bearer token**, generated from your public and secret keys.
```bash theme={null}
POST https://seerbitapi.com/api/v2/encrypt/keys
```
How to generate the token, and which credential every other SeerBit API expects.
## Creating a sub-account
Once you have your Bearer token, you can create sub-accounts for your business operations.
POST
```bash theme={null}
https://seerbitapi.com/api/v2/sub-accounts
```
#### Request Headers
| Name | Type | Description | Required |
| - | - | - | - |
| Content Type | `string` | Must be **application/json** | Yes |
| Authorization | `string` | Bearer token obtained from the encryption endpoint. | Yes |
#### Request Parameters
| Name | Type | Description | Required |
| - | - | - | - |
| publicKey | `string` | Merchant public key (starts with SBPUBK\_) | Yes |
| subAccountName | `string` | Name to identify this sub-account | Yes |
| bankCode | `string` | CBN bank code (e.g., 057 for Zenith, 033 for UBA). | Yes |
| bankName | `string` | Full name of the bank | Yes |
| bankAccountNumber | `string` | 10-digit account number for settlements | Yes |
| email | `string` | Contact email address for notifications | Yes |
| bankAccountName | `string` | Account name as registered with the bank | Yes |
| subPocket | `boolean` | Pocket ID - Required when **isSubPocket** is true | Conditional |
| isSubPocket | `string` | Set to true to link this sub-account to a pocket, **false** otherwise | Yes |
| currency | `string` | The transaction currency (e.g., NGN, USD). | Yes |
##### Complete Request Example cURL
```bash theme={null}
curl --location 'https://seerbitapi.com/api/v2/sub-accounts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer oAX1OeAlwNt9BI5VEwBLlxtWgL2WaLT9kTc4EMaaZgXMfdhHXaqqVgapnQSOO4OZM2oLRPtqjJzwNLEEGqFSvam8MFz06U4fl/5TVwfWLMsRHq4mML9ExIaXRVn3bVm8' \
--data-raw '{
"publicKey": "SBTESTPUBK_9sN3TuLgW6a9redEfY48cKKkUa09Pz2u",
"subAccountName": "Lagos Retail Store",
"bankCode": "057",
"bankName": "Zenith Bank",
"bankAccountNumber": "1234567890",
"phoneNumber": "08012345678",
"email": "lagos.store@example.com",
"bankAccountName": "LAGOS RETAIL LIMITED",
"subPocket": "PKT_ABC123XYZ",
"isSubPocket": true,
"currency": "NGN"
}'
```
##### Response Examples
```json 201:Created theme={null}
{
"status": "SUCCESS",
"data": {
"code": "00",
"subAccount": {
"subAccountCode": "lagos-retail-store-Qx7aL9",
"subAccountName": "Lagos Retail Store",
"bankCode": "057",
"bankName": "Zenith Bank",
"bankAccountNumber": "1234567890",
"email": "lagos.store@example.com",
"isSubPocket": true,
"subPocket": "PKT_ABC123XYZ",
"status": "ACTIVE",
"createdAt": "2026-01-26T10:30:00.000Z"
},
"message": "Sub-account created successfully"
}
}
```
```json 400:Bad Request theme={null}
{
"status": "ERROR",
"data": {
"code": "E01",
"message": "Invalid bank code provided. Please use a valid CBN bank code."
}
}
```
```json 401:Unauthorized theme={null}
{
"status": "ERROR",
"data": {
"code": "E02",
"message": "Invalid or expired Bearer token. Please generate a new token."
}
}
```
## Integration notes and best practices
### Authentication token management
* **Token Validity**: Bearer tokens have a limited lifespan. Implement token refresh logic in your application.
* **Secure Storage**: Store your Secret Key securely. Never expose it in client-side code or version control systems.
* **Token Format**: Always prefix your token with Bearer in the Authorization header (note the space).
### Sub-account configuration
1. Public Key
* Public keys start with **SBPUBK\_** prefix.
* Available in your dashboard under **Settings > API Keys**.
* Replace **YOUR\_PUBLIC\_KEY** with your actual merchant public key.
2. Bank Code Verification
* Use the official CBN (Central Bank of Nigeria) bank codes.
* Common bank codes:
* 057 - Zenith Bank
* 033 - United Bank for Africa (UBA)
* 058 - Guaranty Trust Bank (GTB)
* 011 - First Bank of Nigeria
* 032 - Union Bank
* Contact SeerBit support for a complete list of supported banks
3. Pocket Integration:
* When **isSubPocket** is set to `true`, the subPocket field becomes **mandatory**.
* Ensure the **Pocket ID** exists and is active before linking
* Pocket IDs can be obtained from the SeerBit Pocket API
* If you're not using pockets, set **isSubPocket** to `false` and omit the **subPocket** field
4. Account Name Validation:
* The **bankAccountName** must match the registered account name with the bank.
* Account name mismatches may cause settlement failures
* Verify account details before creating the sub-account.
### Common use cases
1. **Marketplace Settlement**
Create sub-accounts for each vendor on your marketplace to automatically split payments.
2. **Franchise Management**
Set up sub-accounts for each franchise location to track and settle payments independently.
3. **Multi-Business Management**
Manage multiple business units with separate settlement accounts under one parent merchant account.
## Splitting settlement to sub-accounts
Once your sub-accounts exist, you split a payment across them at payment time — either with a `splitCode` referencing a rule you configured in advance, or with a `splits` object defined inline per transaction.
Both split modes, with payloads, the `splits` object fields and worked examples.
## Notes
* **Register a sub-account before you reference it.** A split naming a `subAccountCode` that does not exist will fail.
* **Use the `redirectLink` from the payment response** to send the customer to the SeerBit checkout and complete the transaction.
* **Transaction fees are handled by the checkout.** Who bears the fee is a dashboard setting, and the hosted checkout calculates it — do not add the fee to `amount` yourself. See [transaction fees](/online-payments/integrations/standard-checkout#transaction-fees). Within a split, `transactionFee` decides which party absorbs it.
* **Sub-accounts settle directly.** Each party's share reaches their own account; the full amount does not pass through yours first.
* Sub-accounts created with test keys only work in test mode. See [test and live modes](/test-and-live).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.