Sub-account creation

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.

Create your sub-accounts

Split the payment between them

At payment time, reference those codes — either through a pre-configured split rule, or inline per transaction. See split settlement.

SeerBit settles each party

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 instead.

Prerequisites

Before you begin, ensure you have the following:

SeerBit Merchant Account - Sign up at dashboard.seerbit.com
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.

POST https://seerbitapi.com/api/v2/encrypt/keys

Authentication

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

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

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

{  
"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"  
}  
}  

{
"status": "ERROR",  
"data": {  
	"code": "E01",  
	"message": "Invalid bank code provided. Please use a valid CBN bank code."  
}
}

{  
"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

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.
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
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
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

Marketplace Settlement
Create sub-accounts for each vendor on your marketplace to automatically split payments.
Franchise Management
Set up sub-accounts for each franchise location to track and settle payments independently.
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.

Split settlement

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. 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.

Get Started

Accept Payments

Payment Methods

After a Payment

Payouts & Wallets

Platforms & Marketplaces

In-Store Payments

Reference

How it works

Prerequisites

Authentication

Authentication

Creating a sub-account

Request Headers

Request Parameters

Complete Request Example cURL

Response Examples

Integration notes and best practices

Authentication token management

Sub-account configuration

Common use cases

Splitting settlement to sub-accounts

Split settlement

Notes

​How it works

​Prerequisites

​Authentication

Authentication

​Creating a sub-account

​Request Headers

​Request Parameters

Complete Request Example cURL

Response Examples

​Integration notes and best practices

​Authentication token management

​Sub-account configuration

​Common use cases

​Splitting settlement to sub-accounts

Split settlement

​Notes

How it works

Prerequisites

Authentication

Creating a sub-account

Request Headers

Request Parameters

Integration notes and best practices

Authentication token management

Sub-account configuration

Common use cases

Splitting settlement to sub-accounts

Notes