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