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: "customer@email.com",
    amount: 500000,
    split_code: "SPL_RcScyW5jp2",
  }),
});