API Reference›Subaccounts

Subaccounts

Subaccounts let you split payments between your platform and the merchants or sellers on it. They are the foundation of marketplace and multi-vendor payment flows — each subaccount maps to a business that has its own settlement bank account and percentage of every charge.

Provider support

Subaccounts are currently supported by Paystack (primary) and Flutterwave. You must have at least one of these providers configured under Provider Keys before creating a subaccount.

Endpoints

POST/v1/subaccounts— Create a subaccount

GET/v1/subaccounts— List subaccounts (paginated)

GET/v1/subaccounts/:id— Retrieve a single subaccount

Create a Subaccount

Registers a new subaccount with the provider and stores the returned subaccount code against your merchant record. The subaccount code is used when routing a payment split.

POST

/v1/subaccounts

Creates a subaccount for a business and returns the provider-assigned subaccount code.

Request body

Parameter	Type	Required	Description
`business_name`	`string`	Required	Trading or legal name of the sub-merchant.
`settlement_bank`	`string`	Required	CBN bank code for the settlement account (e.g. "058" for GTBank).
`account_number`	`string`	Required	10-digit NUBAN bank account number belonging to the sub-merchant.
`percentage_charge`	`number`	Optional	Percentage of each charge to credit to this subaccount. Value between 0 and 100. Defaults to 0.
`description`	`string`	Optional	A short description of the subaccount or the business.
`primary_contact_email`	`string`	Optional	Email address of the primary contact for this subaccount.
`primary_contact_name`	`string`	Optional	Full name of the primary contact.
`primary_contact_phone`	`string`	Optional	Phone number of the primary contact (international format recommended).
`provider_id`	`string`	Optional	Force a specific provider: paystack, flutterwave. Omit to use your default configured provider.

Example requestbash

curl -X POST https://api.popfab.io/v1/subaccounts \
  -H "Authorization: Bearer sk_test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "business_name": "Ada Stores",
    "settlement_bank": "058",
    "account_number": "0123456789",
    "percentage_charge": 20,
    "description": "Online fashion retailer",
    "primary_contact_email": "ada@adastores.com",
    "primary_contact_name": "Ada Okafor",
    "primary_contact_phone": "+2348011223344"
  }'

201 Created — Subaccount objectjson

{
  "provider_subaccount_code": "ACCT_xyz123",
  "business_name": "Ada Stores",
  "settlement_bank": "058",
  "account_number": "0123456789",
  "percentage_charge": 20,
  "active": true
}

ℹ

To split a payment to a subaccount, include the subaccount_code in your payment request's metadata and configure a routing rule to apply it, or use the routing_override field.

List Subaccounts

GET

/v1/subaccounts

Returns a cursor-paginated list of your subaccounts, newest first.

Query parameters

Parameter	Type	Required	Description
`limit`	`integer`	Optional	Results per page. Default 20, max 100.
`cursor`	`string`	Optional	Pagination cursor from a previous response next_cursor field.

List subaccountsbash

curl "https://api.popfab.io/v1/subaccounts?limit=50" \
  -H "Authorization: Bearer sk_test_YOUR_API_KEY"

Get a Subaccount

GET

/v1/subaccounts/:id

Retrieves a single subaccount by its POPFAB ID.

Get subaccount by IDbash

curl https://api.popfab.io/v1/subaccounts/ppfb_sub_01HXA3KBZQM4Z3YWN5E6R7VP8S \
  -H "Authorization: Bearer sk_test_YOUR_API_KEY"

Provider Capability

Provider	Create	List	Split Payments
Paystack	✓	✓	✓
Flutterwave	✓	✓	✓
Monnify	—	—	—
Squad	—	—	—
Interswitch	—	—	—

← Virtual AccountsNext: Recurring Charges →