Paystack Transaction Splits API — create, update, and manage multi-party payment splits across subaccounts. Configure percentage or flat-amount splits with flexible bearer types (subaccount, account, all-proportional, all). Add or remove subaccounts from split groups. Use this skill whenever implementing revenue sharing between multiple parties, marketplace commission structures, multi-vendor payment distribution, or any flow that divides a single payment among multiple recipients. Also use when you see references to split_code, SPL_ prefixed codes, bearer_type, or the /split endpoint.

Paystack Transaction Splits

The Transaction Splits API lets you split payment settlements across your main account and one or more subaccounts. More flexible than simple subaccount splits.

Depends on: paystack-setup for the paystackRequest helper.
Related: paystack-subaccounts for creating subaccounts used in splits.

Endpoints

Method	Endpoint	Description
POST	`/split`	Create a split
GET	`/split`	List splits
GET	`/split/:id`	Fetch a split
PUT	`/split/:id`	Update a split
POST	`/split/:id/subaccount/add`	Add/update subaccount in split
POST	`/split/:id/subaccount/remove`	Remove subaccount from split

Create Split

POST /split

Param	Type	Required	Description
`name`	string	Yes	Name of the split
`type`	string	Yes	`percentage` or `flat`
`currency`	string	Yes	Currency code (e.g. `NGN`)
`subaccounts`	array	Yes	Array of `{ subaccount, share }` objects
`bearer_type`	string	Yes	Who bears Paystack fees (see table below)
`bearer_subaccount`	string	No	Subaccount code (required if bearer_type is `subaccount`)

Bearer Types

Type	Description
`subaccount`	A specific subaccount bears fees
`account`	The main account bears all fees
`all-proportional`	Fees are split proportionally among all parties
`all`	Each party bears fees on their share

Percentage Split

const split = await paystackRequest<{
  split_code: string;
  name: string;
  type: string;
}>("/split", {
  method: "POST",
  body: JSON.stringify({
    name: "Marketplace 70-30",
    type: "percentage",
    currency: "NGN",
    subaccounts: [
      { subaccount: "ACCT_6uujpqtzmnufzkw", share: 70 },
    ],
    bearer_type: "all-proportional",
    // Main account gets remaining 30%
  }),
});
// split.data.split_code → "SPL_RcScyW5jp2"

Flat Split

await paystackRequest("/split", {
  method: "POST",
  body: JSON.stringify({
    name: "Fixed Distribution",
    type: "flat",
    currency: "NGN",
    subaccounts: [
      { subaccount: "ACCT_6uujpqtzmnufzkw", share: 50000 },  // ₦500 flat
      { subaccount: "ACCT_eg4sob4590pq9vb", share: 30000 },  // ₦300 flat
    ],
    bearer_type: "account",
  }),
});

List Splits

GET /split

Param	Type	Required	Description
`name`	string	No	Filter by split name
`active`	boolean	No	Filter active/inactive
`sort_by`	string	No	Sort field (default: `createdAt`)
`perPage`	integer	No	Records per page (default: 50)
`page`	integer	No	Page number (default: 1)
`from`	datetime	No	Start date
`to`	datetime	No	End date

const splits = await paystackRequest("/split?active=true");

Fetch Split

GET /split/:id

const split = await paystackRequest(`/split/${splitId}`);

Update Split

PUT /split/:id

Param	Type	Required	Description
`name`	string	Yes	Updated split name
`active`	boolean	Yes	Enable or disable
`bearer_type`	string	No	Updated bearer type
`bearer_subaccount`	string	No	Updated bearer subaccount

await paystackRequest(`/split/${splitId}`, {
  method: "PUT",
  body: JSON.stringify({
    name: "Updated Marketplace Split",
    active: true,
    bearer_type: "all-proportional",
  }),
});

Add/Update Subaccount in Split

POST /split/:id/subaccount/add

Add a new subaccount or update the share of an existing one.

Param	Type	Required	Description
`subaccount`	string	Yes	Subaccount code
`share`	integer	Yes	Share amount (percentage or flat depending on split type)

await paystackRequest(`/split/${splitId}/subaccount/add`, {
  method: "POST",
  body: JSON.stringify({
    subaccount: "ACCT_eg4sob4590pq9vb",
    share: 20,
  }),
});

Remove Subaccount from Split

POST /split/:id/subaccount/remove

await paystackRequest(`/split/${splitId}/subaccount/remove`, {
  method: "POST",
  body: JSON.stringify({
    subaccount: "ACCT_eg4sob4590pq9vb",
  }),
});

Using Splits in Transactions

Pass the split_code when initializing a transaction:

await paystackRequest("/transaction/initialize", {
  method: "POST",
  body: JSON.stringify({
    email: "[email protected]",
    amount: 500000,
    split_code: "SPL_RcScyW5jp2",
  }),
});

paystack-splits