Payments
Split a payment across multiple subaccounts
In a nutshell
Divide a payment between your main account and several subaccounts with a saved split or a dynamic split.
There are two ways to divide a payment between your main account and several subaccounts:
- Saved split: create the split once, then pass its
split_codeon every payment you want to divide the same way. - Dynamic split: send the split with each payment, for when the division changes from one payment to the next.
Before you start, create a subaccount for each partner. The examples use Oasis Foods (ACCT_6uujpqtzmnufzkw) and Lekki Bakes (ACCT_hdl8abxl8drhrl3). Paystack generates different codes for your subaccounts.
Copy linkCreate a split
Send the split's name, type, currency, and subaccount shares to Create Split. In this example, Oasis Foods gets 50% of each payment, Lekki Bakes gets 30%, and your main account keeps the remaining 20%:
POSTapi.paystack.co/split
curl https://api.paystack.co/split \
-H "Authorization: Bearer $PAYSTACK_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Marketplace order split",
"type": "percentage",
"currency": "ZAR",
"subaccounts": [
{
"subaccount": "ACCT_6uujpqtzmnufzkw",
"share": 50
},
{
"subaccount": "ACCT_hdl8abxl8drhrl3",
"share": 30
}
],
"bearer_type": "account"
}' \
-X POSTconst https = require("https");
const params = JSON.stringify({
"name": "Marketplace order split",
"type": "percentage",
"currency": "ZAR",
"subaccounts": [
{
"subaccount": "ACCT_6uujpqtzmnufzkw",
"share": 50
},
{
"subaccount": "ACCT_hdl8abxl8drhrl3",
"share": 30
}
],
"bearer_type": "account"
});
const options = {
hostname: "api.paystack.co",
port: 443,
path: "/split",
method: "POST",
headers: {
Authorization: `Bearer ${process.env.PAYSTACK_SECRET_KEY}`,
"Content-Type": "application/json",
},
};
const req = https.request(options, (res) => {
let data = "";
res.on("data", (chunk) => {
data += chunk;
});
res.on("end", () => {
console.log(res.statusCode, JSON.parse(data));
});
});
req.on("error", (error) => {
console.error(error);
});
req.write(params);
req.end();<?php
$fields = [
"name" => "Marketplace order split",
"type" => "percentage",
"currency" => "ZAR",
"subaccounts" => [
[
"subaccount" => "ACCT_6uujpqtzmnufzkw",
"share" => 50,
],
[
"subaccount" => "ACCT_hdl8abxl8drhrl3",
"share" => 30,
],
],
"bearer_type" => "account",
];
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.paystack.co/split",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode($fields),
CURLOPT_HTTPHEADER => array(
"Authorization: Bearer " . getenv("PAYSTACK_SECRET_KEY"),
"Content-Type: application/json",
"Cache-Control: no-cache",
),
));
$response = curl_exec($curl);
echo curl_getinfo($curl, CURLINFO_HTTP_CODE) . " " . $response;
?>Set type to percentage or flat. Every share in the split uses that type. The share values must follow these limits, or Paystack rejects the request:
type | Each share is | Shares must total |
|---|---|---|
percentage | A whole-number percentage | 100 or less. Your main account gets the rest. |
flat | An amount in the currency's subunit. See supported currencies. | No more than the amount of the payment you use the split on. |
Save the split_code (SPL_RcScyW5jp2) and id (2703655). Pass the split_code on each payment and the id when you change the split.
You can also create and manage splits on the Transaction splits page of your Dashboard.
Copy linkChoose who pays the Paystack fee
Set bearer_type when you create a split or pass a split object.
bearer_type | Who pays the fee |
|---|---|
all | Your main account and every subaccount pay an equal part of the fee. |
all-proportional | Each party pays a part of the fee in proportion to its share of the payment. |
account | Your main account pays the whole fee. |
subaccount | The subaccount in bearer_subaccount pays the whole fee. Pass bearer_subaccount with this value, and use a subaccount that's in the split. |
Default fee bearer
If you leave out bearer_type, your main account and every subaccount pay an equal part of the fee.
Copy linkCollect a payment with the split
Pass the split_code to Initialize Transaction:
POSTapi.paystack.co/transaction/initialize
curl https://api.paystack.co/transaction/initialize \
-H "Authorization: Bearer $PAYSTACK_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"amount": 2000000,
"split_code": "SPL_RcScyW5jp2"
}' \
-X POST
const https = require("https");
const params = JSON.stringify({
"email": "[email protected]",
"amount": 2000000,
"split_code": "SPL_RcScyW5jp2"
});
const options = {
hostname: "api.paystack.co",
port: 443,
path: "/transaction/initialize",
method: "POST",
headers: {
Authorization: `Bearer ${process.env.PAYSTACK_SECRET_KEY}`,
"Content-Type": "application/json",
},
};
const req = https.request(options, (res) => {
let data = "";
res.on("data", (chunk) => {
data += chunk;
});
res.on("end", () => {
console.log(res.statusCode, JSON.parse(data));
});
});
req.on("error", (error) => {
console.error(error);
});
req.write(params);
req.end();
<?php
$fields = [
"email" => "[email protected]",
"amount" => 2000000,
"split_code" => "SPL_RcScyW5jp2",
];
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.paystack.co/transaction/initialize",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode($fields),
CURLOPT_HTTPHEADER => array(
"Authorization: Bearer " . getenv("PAYSTACK_SECRET_KEY"),
"Content-Type: application/json",
"Cache-Control: no-cache",
),
));
$response = curl_exec($curl);
echo curl_getinfo($curl, CURLINFO_HTTP_CODE) . " " . $response;
?>
To split a repeat payment from a saved card, pass the same split_code to Charge Authorization:
POSTapi.paystack.co/transaction/charge_authorization
curl https://api.paystack.co/transaction/charge_authorization \
-H "Authorization: Bearer $PAYSTACK_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"authorization_code": "AUTH_12abc345de",
"email": "[email protected]",
"amount": 2000000,
"split_code": "SPL_RcScyW5jp2"
}' \
-X POSTconst https = require("https");
const params = JSON.stringify({
"authorization_code": "AUTH_12abc345de",
"email": "[email protected]",
"amount": 2000000,
"split_code": "SPL_RcScyW5jp2"
});
const options = {
hostname: "api.paystack.co",
port: 443,
path: "/transaction/charge_authorization",
method: "POST",
headers: {
Authorization: `Bearer ${process.env.PAYSTACK_SECRET_KEY}`,
"Content-Type": "application/json",
},
};
const req = https.request(options, (res) => {
let data = "";
res.on("data", (chunk) => {
data += chunk;
});
res.on("end", () => {
console.log(res.statusCode, JSON.parse(data));
});
});
req.on("error", (error) => {
console.error(error);
});
req.write(params);
req.end();<?php
$fields = [
"authorization_code" => "AUTH_12abc345de",
"email" => "[email protected]",
"amount" => 2000000,
"split_code" => "SPL_RcScyW5jp2",
];
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.paystack.co/transaction/charge_authorization",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode($fields),
CURLOPT_HTTPHEADER => array(
"Authorization: Bearer " . getenv("PAYSTACK_SECRET_KEY"),
"Content-Type: application/json",
"Cache-Control: no-cache",
),
));
$response = curl_exec($curl);
echo curl_getinfo($curl, CURLINFO_HTTP_CODE) . " " . $response;
?>Copy linkUse a dynamic split
A saved split divides every payment the same way. Use a dynamic split when the division depends on the payment itself.
For example, a customer's 2000000 order includes 1200000 of food from Oasis Foods and 500000 of pastries from Lekki Bakes. The next order has different amounts, so a saved split can't describe it. Instead, you send the shares for this order with the payment.
To do this, pass a split object instead of a split_code. You don't need to create the split first. Initialize Transaction, Charge Authorization, and Paystack Popup all accept a split object.
| Field | Required | Description |
|---|---|---|
name | Yes | Name of the split, for example the order number. |
type | Yes | percentage or flat. |
currency | Yes | Currency of the split. Use the payment's currency. |
subaccounts | Yes | Array of objects, each with a subaccount code and its share. |
bearer_type | No | Who pays the Paystack fee. See Choose who pays the Paystack fee. |
bearer_subaccount | When bearer_type is subaccount | Code of the subaccount that pays the fee. |
The shares follow the same limits as a saved split.
This request splits that order. It uses a flat split, so each share is an amount in the currency's subunit (cents), and 2000000 is ZAR 20,000:
POSTapi.paystack.co/transaction/initialize
curl https://api.paystack.co/transaction/initialize \
-H "Authorization: Bearer $PAYSTACK_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"amount": 2000000,
"split": {
"name": "Order 1042 split",
"type": "flat",
"currency": "ZAR",
"bearer_type": "account",
"subaccounts": [
{
"subaccount": "ACCT_6uujpqtzmnufzkw",
"share": 1200000
},
{
"subaccount": "ACCT_hdl8abxl8drhrl3",
"share": 500000
}
]
}
}' \
-X POSTconst https = require("https");
const params = JSON.stringify({
"email": "[email protected]",
"amount": 2000000,
"split": {
"name": "Order 1042 split",
"type": "flat",
"currency": "ZAR",
"bearer_type": "account",
"subaccounts": [
{
"subaccount": "ACCT_6uujpqtzmnufzkw",
"share": 1200000
},
{
"subaccount": "ACCT_hdl8abxl8drhrl3",
"share": 500000
}
]
}
});
const options = {
hostname: "api.paystack.co",
port: 443,
path: "/transaction/initialize",
method: "POST",
headers: {
Authorization: `Bearer ${process.env.PAYSTACK_SECRET_KEY}`,
"Content-Type": "application/json",
},
};
const req = https.request(options, (res) => {
let data = "";
res.on("data", (chunk) => {
data += chunk;
});
res.on("end", () => {
console.log(res.statusCode, JSON.parse(data));
});
});
req.on("error", (error) => {
console.error(error);
});
req.write(params);
req.end();<?php
$fields = [
"email" => "[email protected]",
"amount" => 2000000,
"split" => [
"name" => "Order 1042 split",
"type" => "flat",
"currency" => "ZAR",
"bearer_type" => "account",
"subaccounts" => [
[
"subaccount" => "ACCT_6uujpqtzmnufzkw",
"share" => 1200000,
],
[
"subaccount" => "ACCT_hdl8abxl8drhrl3",
"share" => 500000,
],
],
],
];
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.paystack.co/transaction/initialize",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode($fields),
CURLOPT_HTTPHEADER => array(
"Authorization: Bearer " . getenv("PAYSTACK_SECRET_KEY"),
"Content-Type: application/json",
"Cache-Control: no-cache",
),
));
$response = curl_exec($curl);
echo curl_getinfo($curl, CURLINFO_HTTP_CODE) . " " . $response;
?>Oasis Foods gets 1200000 and Lekki Bakes gets 500000. Your main account gets the remaining 300000 and pays the Paystack fee from it, because bearer_type is account.
Copy linkChange a split
Pass the split's id to these endpoints:
- To add a subaccount, or change the share of a subaccount already in the split, call Add Subaccount to Split with the
subaccountcode and itsshare. - To remove a subaccount, call Remove Subaccount from Split with its
subaccountcode. - If the subaccount you're removing is the
bearer_subaccount, call Update Split first to change it. - To rename the split, change
bearer_typeorbearer_subaccount, or deactivate the split, call Update Split. Setactivetofalseto deactivate it.
You can't change a split's type
To change the type, deactivate the split and create one with the new type.
Copy linkConfirm the split
When a payment with a split succeeds, the charge.success event includes a split object:
formula: the split configuration Paystack applied.shares: the amount each party received, in the currency's subunit.integration: your main account, in both objects.
This event is for payment nms6uvr1pl, initialized with SPL_RcScyW5jp2:
{
"event": "charge.success",
"data": {
"id": 697123356,
"status": "success",
"reference": "nms6uvr1pl",
"amount": 2000000,
"currency": "ZAR",
"paid_at": "2026-10-09T13:54:57.000Z",
"split": {
"id": 2703655,
"name": "Marketplace order split",
"split_code": "SPL_RcScyW5jp2",
"formula": {
"type": "percentage",
"bearer_type": "account",
"subaccounts": [
{ "subaccount_code": "ACCT_6uujpqtzmnufzkw", "name": "Oasis Foods", "share": 50 },
{ "subaccount_code": "ACCT_hdl8abxl8drhrl3", "name": "Lekki Bakes", "share": 30 }
],
"integration": 20
},
"shares": {
"paystack": 58100,
"subaccounts": [
{ "subaccount_code": "ACCT_6uujpqtzmnufzkw", "amount": 1000000 },
{ "subaccount_code": "ACCT_hdl8abxl8drhrl3", "amount": 600000 }
],
"integration": 341900
}
}
}
}Because the split uses bearer_type: "account", your main account pays the Paystack fee (shares.paystack) from its 20% share. Each subaccount receives its full share.
The fee in this example uses standard pricing for ZAR local card payments. Your fee depends on your pricing and the payment channel.
Use the charge.success webhook as your primary signal to fulfill orders, grant access, or update your database. The customer can close the page before your callback runs, but the webhook still arrives.
Add your webhook URL on the Paystack Dashboard, and verify the signature on every event with your webhook signing secret.