rexedge/paystack-splits

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",
  }),
});