Paystack Split Payments Explained

A split payment on Paystack is a single customer transaction where the collected amount goes to more than one bank account at settlement. The customer pays once. They see one charge on their card, one M-Pesa prompt, or one bank transfer reference. Behind the scenes, Paystack divides the money between your main Paystack account and one or more subaccounts, then settles each party into their own bank account.

Without splits, a marketplace or multi-party platform would collect all the money into one account, then manually transfer each vendor's share later. That approach creates three problems that grow worse with scale:

• You hold other people's money. In most African jurisdictions, collecting and holding funds on behalf of third parties without the appropriate license raises regulatory questions. Splits remove you from the money flow entirely.
• You build a payout system. Every vendor payout is a transfer you have to initiate, track, and reconcile. Every failed transfer becomes a support ticket. Splits eliminate this by having Paystack settle vendors directly.
• You carry the risk. If a vendor's bank account changes, if a transfer fails, if your balance is insufficient for payouts, you own the problem. With splits, Paystack handles settlement to each party independently.

The simplest way to think about it: splits move the money routing from your application layer to Paystack's infrastructure layer. You tell Paystack who gets what. Paystack does the rest.

Here is what happens from the moment a customer initiates a split payment to the moment every party has money in their bank account.

Step 1: You initialize the transaction with split parameters. When calling the Initialize Transaction endpoint, you pass either a subaccount code (for a two-party split) or a split_code (for multi-split). You can optionally override the split ratio and set the fee bearer.

Step 2: The customer pays. The customer completes payment through the Paystack checkout or your custom payment form. From the customer's perspective, nothing is different from a regular payment. They do not see the split details.

Step 3: Paystack processes the charge. The full amount is collected from the customer. At this point, the money is with Paystack.

Step 4: Paystack calculates the split. Based on the split configuration you passed during initialization (percentage or flat, and the bearer setting), Paystack calculates how much goes to each party. It deducts the processing fee from the designated bearer's portion.

Step 5: Paystack sends the webhook. The charge.success event fires. The webhook payload includes the full split breakdown: which subaccount received what amount, the fee deducted, and who bore the fee. Your webhook handler should verify these amounts match your expectations.

Step 6: Settlement. On the normal settlement cycle for your market, Paystack settles each party directly. The subaccount's share goes to the subaccount's bank account. Your commission goes to your main Paystack balance (and from there to your settlement bank account). Neither party depends on the other for their settlement.

The settlement cycle varies by country and can change. Do not hardcode assumptions about settlement timing into your product logic. If you need to know when a specific settlement landed, use the Settlements API or check the dashboard.

When you initialize a split transaction, these are the parameters that control the split behavior.

subaccount

The subaccount code (like ACCT_abc123xyz) that identifies the vendor or partner receiving a share of this transaction. When you pass this parameter, Paystack creates a two-party split between the subaccount and your main account.

// Two-party split: vendor gets their share, you keep the rest
const response = await fetch('https://api.paystack.co/transaction/initialize', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.PAYSTACK_SECRET_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'buyer@example.com',
    amount: 500000, // 5,000 NGN in kobo
    subaccount: 'ACCT_abc123xyz',
  }),
});

split_code

For multi-split transactions (three or more parties), you pass a split_code instead of a subaccount. The split code references a Transaction Split object that you created beforehand, which defines all the participating subaccounts and their shares.

transaction_charge

An amount in the smallest currency unit (kobo, pesewas, cents) that your main account takes as a flat fee from this transaction. When you pass this parameter, it overrides the percentage-based split defined on the subaccount. The subaccount gets the transaction amount minus your flat charge (and minus the processing fee, depending on bearer).

bearer

Controls which party absorbs the Paystack processing fee. Three options: account (your main account pays the fee), subaccount (the vendor pays the fee), or all (the customer pays the fee on top of the product price). The default depends on your Paystack configuration, but most integrations set it explicitly per transaction to avoid surprises.

These four parameters give you complete control over every split transaction. The subaccount or split_code says who gets money. The transaction_charge or the subaccount's percentage_charge says how much. The bearer says who absorbs the Paystack fee.

The math is straightforward, but getting it wrong causes real financial problems. Here is how Paystack calculates the split for each type.

Percentage split calculation

If the subaccount's percentage_charge is 80 and the customer pays 10,000 NGN:

• Subaccount's share: 10,000 x 80% = 8,000 NGN
• Your share (the residual): 10,000 - 8,000 = 2,000 NGN
• Paystack fee: deducted from whichever party is the bearer

If the bearer is account, the fee comes out of your 2,000 NGN. If the bearer is subaccount, the fee comes out of the vendor's 8,000 NGN. If the bearer is all, Paystack adds the fee on top of the 10,000 NGN, so the customer pays more than the listed price.

Flat split calculation

If you pass transaction_charge: 200000 (2,000 NGN in kobo) and the customer pays 10,000 NGN:

• Your share: 2,000 NGN (the flat charge)
• Subaccount's share: 10,000 - 2,000 = 8,000 NGN
• Paystack fee: deducted from the bearer's portion

The outcome looks identical in this example, but the models diverge at different price points. At 5,000 NGN, a percentage split at 80/20 gives you 1,000 NGN, while a flat charge of 2,000 NGN still gives you 2,000 NGN. At 50,000 NGN, the percentage gives you 10,000 NGN, while the flat charge still gives you 2,000 NGN.

Verifying the calculation

After a split transaction completes, verify the amounts by calling the Verify Transaction endpoint. The response includes the split breakdown:

// Verify the split amounts after payment
const verifyResponse = await fetch(
  'https://api.paystack.co/transaction/verify/' + reference,
  {
    headers: {
      Authorization: 'Bearer ' + process.env.PAYSTACK_SECRET_KEY,
    },
  }
);

const data = await verifyResponse.json();
// data.data.subaccount contains the subaccount details
// data.data.fees contains the fee amount
// data.data.fees_split contains the fee breakdown if applicable
console.log('Subaccount share:', data.data.subaccount);
console.log('Fee charged:', data.data.fees);

Always verify. Do not assume your expected amounts are what Paystack actually settled. Edge cases like rounding, fee changes, or currency conversion on cross-border payments can produce numbers that differ from your calculation by small amounts.

Paystack supports two split modes, and choosing the wrong one for your use case adds unnecessary complexity.

Single split (subaccount parameter)

One customer payment, two recipients: the subaccount and your main account. You pass the subaccount code directly when initializing the transaction. No setup step needed beyond creating the subaccount itself. This is what you use for most marketplace transactions where a buyer purchases from a single seller.

Multi-split (split_code parameter)

One customer payment, three or more recipients. You first create a Transaction Split object that defines all participating subaccounts and their shares. Then you pass the resulting split_code when initializing the transaction. This requires a two-step process (create split group, then use it), but it is the only way to route money to multiple subaccounts in a single charge.

When to use which

• Single seller marketplace (customer buys from one vendor per transaction): single split
• Food delivery (restaurant + rider + platform): multi-split
• Referral systems (vendor + referrer + platform): multi-split
• Multi-vendor cart where you split into separate per-vendor transactions: single split on each transaction
• Multi-vendor cart where you charge once and distribute: multi-split

A common mistake is using multi-split when single split would work. If there is only one subaccount per transaction, single split is simpler, requires fewer API calls, and has fewer moving parts. Save multi-split for cases where the money genuinely needs to reach three or more bank accounts from a single charge.

When a split transaction succeeds, the charge.success webhook payload contains everything you need to record the split in your system.

// Webhook handler: extract split details from charge.success
app.post('/webhooks/paystack', (req, res) => {
  // Verify the webhook signature first (critical for security)
  var hash = crypto
    .createHmac('sha512', process.env.PAYSTACK_SECRET_KEY)
    .update(JSON.stringify(req.body))
    .digest('hex');

  if (hash !== req.headers['x-paystack-signature']) {
    return res.status(401).send('Invalid signature');
  }

  var event = req.body;

  if (event.event === 'charge.success') {
    var data = event.data;

    // The split details are in the transaction data
    console.log('Transaction reference:', data.reference);
    console.log('Total amount (kobo):', data.amount);
    console.log('Fee (kobo):', data.fees);

    // Subaccount info (for single split)
    if (data.subaccount) {
      console.log('Subaccount code:', data.subaccount.subaccount_code);
      console.log('Subaccount share:', data.subaccount.share);
    }

    // For multi-split, check the split object
    if (data.split) {
      console.log('Split code:', data.split.split_code);
    }

    // Store these amounts in your database for reconciliation
    // Compare against your expected split to catch discrepancies
  }

  res.status(200).send('OK');
});

The key fields to extract and store:

• amount: The total amount the customer paid (in the smallest currency unit)
• fees: The Paystack processing fee for this transaction
• subaccount.subaccount_code: Which subaccount participated in the split
• subaccount.share: The subaccount's calculated share of the transaction

Store both your expected split and the actual split from the webhook. Run a comparison. If they differ, flag the transaction for review. Small differences due to rounding are normal. Large differences suggest a configuration error that you need to fix before it affects more transactions.

These are the things that trip up developers who are new to Paystack split payments.

"The customer can see the split." No. The customer sees a single payment for the full amount. They have no visibility into how the money is divided between your account and the subaccount. The split is purely a backend settlement concern.

"Split payments settle faster." No. Split payments follow the same settlement schedule as regular payments. The only way to change settlement timing is to configure the subaccount's settlement schedule (auto or manual) or to work with Paystack on custom settlement terms for your business.

"I can split to any bank account." Not directly. You can only split to subaccounts, and subaccounts must be in the same country as your Paystack business registration. You cannot split a Nigerian transaction to a Kenyan bank account. For cross-border distribution, you would use splits domestically and transfers for the international leg.

"I can change the split after the customer pays." No. The split is locked when the transaction is initialized. Once the customer pays, the split ratio cannot be modified. If you realize the split was wrong, your options are to refund and re-charge (bad customer experience) or to settle internally with the vendor outside of Paystack.

"Refunds reverse the split." Partially. When you refund a split transaction, the refund comes from your main Paystack balance. The subaccount's share is not automatically clawed back. If the subaccount has already been settled, you are out of pocket. Build hold periods or dispute windows into your product to mitigate this.

"I need splits for every marketplace." Not necessarily. If you have a small number of vendors who trust you and you prefer controlling the payout timing, you can collect all money into your account and use Paystack Transfers to pay vendors. Splits are better at scale and when you want to avoid holding vendor funds, but they are not the only option.

Splits are the right tool when your platform routes payments between multiple parties and you want Paystack to handle the settlement logistics. Specifically, they shine when:

• You have many vendors or partners who each need their own bank settlement
• You want to avoid holding other people's money in your account
• Your commission model is a consistent percentage or flat fee per transaction
• You want to eliminate the operational burden of running a payout system

Splits are not the right tool when:

• Your payout logic is complex and conditional (pay the vendor only if they complete a verification step three days after the transaction)
• You need to aggregate multiple transactions before paying a vendor (pay weekly totals rather than per-transaction)
• You need cross-border payouts where the vendor is in a different country than your Paystack registration
• You need to deduct amounts from vendor payouts for returns, penalties, or fees that are calculated after the transaction

In those cases, Paystack Transfers give you more control. You collect the full amount into your account, calculate what each vendor is owed on your own schedule, and initiate transfers when ready. The trade-off is that you now hold vendor funds (with the regulatory implications that carries) and you own the payout infrastructure.

Many mature platforms use both: splits for the standard flow and transfers for edge cases like refund recovery, bonuses, or adjustments that do not fit the split model.

For the complete picture of how split payments fit into marketplace architecture, including subaccount management, fee configuration, and real-world build patterns, see the Paystack split payments and marketplaces complete guide.

Split payments are one piece of the payment engineering puzzle. Understanding them deeply means understanding settlement, reconciliation, webhooks, and the business models they enable.

If you want to learn payment integration as part of a full-stack engineering program, the McTaba bootcamp covers payment systems with real Paystack integrations. Every student ships code that handles real money.

Create a free McTaba account