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