Sign in

Payments

Split a payment across multiple subaccounts

View as Markdown

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_code on 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 POST
const 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;
?>
{
  "status": true,
  "message": "Split created",
  "data": {
    "id": 2703655,
    "name": "Marketplace order split",
    "type": "percentage",
    "currency": "ZAR",
    "split_code": "SPL_RcScyW5jp2",
    "active": true,
    "bearer_type": "account",
    "is_dynamic": false,
    "subaccounts": [
      {
        "subaccount": {
          "subaccount_code": "ACCT_6uujpqtzmnufzkw",
          "business_name": "Oasis Foods",
          "settlement_bank": "Guaranty Trust Bank",
          "currency": "ZAR",
          "account_number": "0123456047"
        },
        "share": 50
      },
      {
        "subaccount": {
          "subaccount_code": "ACCT_hdl8abxl8drhrl3",
          "business_name": "Lekki Bakes",
          "settlement_bank": "Guaranty Trust Bank",
          "currency": "ZAR",
          "account_number": "0198765432"
        },
        "share": 30
      }
    ],
    "total_subaccounts": 2,
    "createdAt": "2026-10-02T11:38:47.506Z",
    "updatedAt": "2026-10-02T11:38:47.506Z"
  }
}

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:

typeEach share isShares must total
percentageA whole-number percentage100 or less. Your main account gets the rest.
flatAn 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_typeWho pays the fee
allYour main account and every subaccount pay an equal part of the fee.
all-proportionalEach party pays a part of the fee in proportion to its share of the payment.
accountYour main account pays the whole fee.
subaccountThe 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;
?>
{
  "status": true,
  "message": "Authorization URL created",
  "data": {
    "authorization_url": "https://checkout.paystack.com/nkdks46nymizns7",
    "access_code": "nkdks46nymizns7",
    "reference": "nms6uvr1pl"
  }
}

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 POST
const 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;
?>
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "id": 696105928,
    "status": "success",
    "reference": "cn65lf4ixmkzvda",
    "amount": 2000000,
    "currency": "ZAR",
    "gateway_response": "Approved",
    "channel": "card",
    "transaction_date": "2026-10-09T11:45:03.000Z",
    "authorization": {
      "authorization_code": "AUTH_12abc345de",
      "channel": "card",
      "reusable": true
    }
  }
}

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.

FieldRequiredDescription
nameYesName of the split, for example the order number.
typeYespercentage or flat.
currencyYesCurrency of the split. Use the payment's currency.
subaccountsYesArray of objects, each with a subaccount code and its share.
bearer_typeNoWho pays the Paystack fee. See Choose who pays the Paystack fee.
bearer_subaccountWhen bearer_type is subaccountCode 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 POST
const 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;
?>
{
  "status": true,
  "message": "Authorization URL created",
  "data": {
    "authorization_url": "https://checkout.paystack.com/p5n2xg8cul4ebsa",
    "access_code": "p5n2xg8cul4ebsa",
    "reference": "d9fj3kq0wr"
  }
}

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 subaccount code and its share.
  • To remove a subaccount, call Remove Subaccount from Split with its subaccount code.
  • If the subaccount you're removing is the bearer_subaccount, call Update Split first to change it.
  • To rename the split, change bearer_type or bearer_subaccount, or deactivate the split, call Update Split. Set active to false to 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.

Was this page helpful?