Paystack Split Payments and Marketplaces: Complete Guide

A split payment is a single customer transaction where the money goes to more than one recipient. The customer pays once. Paystack divides the funds between your main account and one or more subaccounts at settlement time.

Without split payments, marketplace operators collect all the money into one account, then manually transfer each vendor's share. That creates three problems: you hold other people's money (which carries regulatory risk in most African jurisdictions), you have to build and maintain a payout system, and every failed transfer becomes a support ticket. Paystack splits eliminate all three by settling each party directly.

The use cases show up everywhere in African tech:

• A food delivery app splits each order between the restaurant, the delivery rider, and the platform
• A freelance marketplace takes a commission and routes the rest to the freelancer
• An event ticketing platform splits ticket sales between the organizer and the platform
• A multi-vendor e-commerce store sends each product's revenue to the correct seller
• A SACCO or chama collects contributions and distributes them across member accounts
• A school fees platform splits tuition between the school's main account and individual departments

In all these cases, the alternative is collecting everything into one account and running batch transfers later. That approach works at small scale, but it is slow, error-prone, and in some jurisdictions it raises questions about holding funds on behalf of third parties without a license. Splits solve this at the infrastructure level by removing you from the money flow entirely.

The mechanics are straightforward. You create subaccounts for the parties who need to receive money. When a customer pays, you tell Paystack which subaccount gets what share. Paystack processes the payment, calculates the split, and settles each party into their own bank account on the normal settlement cycle. Your commission (the portion not allocated to subaccounts) lands in your main Paystack balance.

For the foundational concepts behind how splitting works on Paystack, including the settlement timeline and what happens under the hood, read Paystack split payments explained.

Before you can split a payment, you need a subaccount. A subaccount represents a third party who receives a share of the payment. It stores the party's bank account details, their default commission rate, and a settlement configuration. Every vendor, seller, freelancer, or partner in your marketplace gets one.

Creating a subaccount is a single API call:

// Node.js: Create a subaccount
const response = await fetch('https://api.paystack.co/subaccount', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PAYSTACK_SECRET_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    business_name: 'Mama Oliech Kitchen',
    settlement_bank: '058',        // Bank code (use the List Banks endpoint to get codes)
    account_number: '0123456789',
    percentage_charge: 80,          // Subaccount gets 80%, you keep 20%
    description: 'Restaurant partner on FoodRush',
  }),
});

const data = await response.json();
// data.data.subaccount_code => "ACCT_abc123xyz"
// Store this code in your database alongside the vendor record.

Key things to understand about subaccounts:

• The subaccount_code is your handle. You pass it when initializing split transactions. Store it in your database alongside the vendor's user record. You will reference it every time that vendor receives a payment.
• percentage_charge is the default split ratio. If you set it to 80, the subaccount gets 80% and your main account gets 20% on every transaction that uses this subaccount. You can override this per transaction.
• Bank details must be valid. Paystack verifies the account number against the bank when you create the subaccount. If they do not match, creation fails. Use the Resolve Account endpoint (GET /bank/resolve?account_number=...&bank_code=...) to validate details before attempting creation.
• You can update subaccounts. If a vendor changes banks, PUT to /subaccount/{id_or_code} with the new details. Pending settlements continue to the old account; new transactions use the updated details.
• Settlement is direct. Paystack settles the subaccount's share directly to their bank account. The money does not pass through your main Paystack balance. This is the key difference between splits and manual payouts.
• One vendor, one subaccount. Do not create multiple subaccounts for the same vendor. If you need to change the split ratio, update the existing subaccount or override it per transaction.

To get bank codes for any Paystack-supported country, call GET /bank?country=nigeria (or kenya, ghana, south_africa). Paystack returns the full list of supported banks with their codes. For a deep walkthrough of subaccount creation, updates, listing, and all the edge cases, see the subaccounts on Paystack complete guide.

When you create a subaccount or initialize a split transaction, you choose how the money gets divided. Paystack gives you two split types: percentage and flat.

Percentage split

The subaccount receives a percentage of the transaction amount. If the percentage_charge is 80 and the customer pays 10,000 NGN, the subaccount gets 8,000 NGN and your main account gets 2,000 NGN (before fees, depending on bearer configuration).

Percentage splits are the standard model for marketplaces. They scale naturally with transaction size: your 20% commission on a 10,000 NGN order is 2,000 NGN, and your 20% on a 50,000 NGN order is 10,000 NGN. No manual adjustment needed as order values grow.

Flat split

Your main account takes a fixed amount from every transaction, regardless of the transaction size. If you set a flat charge of 500 NGN (50,000 kobo) and the customer pays 10,000 NGN, you keep 500 NGN and the subaccount gets 9,500 NGN (before fees).

Flat splits make sense when your platform charges a fixed service fee per transaction. Booking fees, processing fees, listing fees. If the value you provide to the vendor does not scale with the order amount, a flat fee is more honest and easier to explain.

Choosing between them

• If your platform adds value proportional to the transaction size (more expensive items need more support, logistics, or marketing), use percentage.
• If your platform provides the same service regardless of transaction size (listing a 2,000 NGN item costs you the same as listing a 200,000 NGN item), use flat.
• If you want the simplicity of percentage but need a floor (never earn less than 200 NGN per transaction), you will need to calculate the split on your server and override per transaction. Paystack does not support "percentage with minimum" natively.

Per-transaction override

The split type set on the subaccount is the default. You can override it on any individual transaction by passing transaction_charge when initializing:

// Override the default percentage split with a flat charge for this transaction
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: 1000000, // 10,000 NGN in kobo
    subaccount: 'ACCT_abc123xyz',
    transaction_charge: 200000, // Your main account keeps 2,000 NGN (flat)
    // Omit transaction_charge to use the subaccount's default percentage_charge
  }),
});

When you pass transaction_charge (an amount in the smallest currency unit), it overrides the percentage split with a flat charge for that specific transaction. This lets you use percentage splits as the default but switch to flat for promotional offers, special pricing tiers, or high-value orders where a percentage commission would feel excessive to the vendor.

For a detailed comparison with worked margin calculations across different transaction sizes, read percentage vs flat split configuration on Paystack.

Standard split divides a payment between your main account and one subaccount. Multi-split divides a payment among your main account and multiple subaccounts in a single transaction. This is what you need when a payment touches three or more parties.

To use multi-split, you create a Transaction Split object that defines which subaccounts participate and what share each one gets:

// Create a multi-split group
const response = await fetch('https://api.paystack.co/split', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PAYSTACK_SECRET_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Food Order Split - Order #1042',
    type: 'percentage',           // or 'flat'
    currency: 'NGN',
    subaccounts: [
      {
        subaccount: 'ACCT_restaurant_123',
        share: 70,                // Restaurant gets 70%
      },
      {
        subaccount: 'ACCT_rider_456',
        share: 10,                // Rider gets 10%
      },
    ],
    bearer_type: 'account',       // Main account bears the Paystack fee
    bearer_subaccount: '',
  }),
});

const data = await response.json();
// data.data.split_code => "SPL_xyz789"
// The remaining 20% (100 - 70 - 10) goes to your main account

Then pass the split_code when initializing the transaction:

const txResponse = 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: 'customer@example.com',
    amount: 500000, // 5,000 NGN in kobo
    split_code: 'SPL_xyz789',
    reference: `order_1042_${Date.now()}`,
  }),
});

When this transaction succeeds, Paystack splits the 5,000 NGN: 3,500 NGN to the restaurant, 500 NGN to the rider, and 1,000 NGN to your main account (the residual after all subaccount shares are allocated). Each party gets settled directly into their bank account.

Important details about multi-split:

• The residual goes to you. If the subaccount shares add up to 80%, your main account gets the remaining 20%. If they add up to 100%, you get nothing (which is valid but unusual).
• Split groups are reusable. If the same restaurant and rider handle multiple orders, you can reuse the split group. But in practice, most food delivery and marketplace orders have different participant combinations, so you often create a new split group per order.
• You can update split groups. Add or remove subaccounts from an existing split group using POST /split/{id}/subaccount/add and POST /split/{id}/subaccount/remove.
• Flat multi-split works differently. With type: 'flat', each subaccount's share is an amount in the smallest currency unit, not a percentage. The subaccounts get their fixed amounts, and your main account gets whatever is left.

For the full API reference, edge cases around rounding, and patterns for creating dynamic multi-split groups per order, see multi-split payments explained.

Every Paystack transaction has a processing fee. In a split payment, someone has to absorb that fee. The bearer parameter (or bearer_type in multi-split) determines who. This is one of the most consequential decisions in your marketplace architecture because it directly affects every party's take-home amount on every transaction.

There are three options:

1. Account (default)

Your main account absorbs the Paystack fee. The subaccount receives their full calculated share, and the fee is deducted from your portion. This is the most common setup for marketplaces that want to offer vendors a clean, predictable payout. The vendor sees exactly what they expected; you absorb the cost of payment processing as part of your operating expenses.

2. Subaccount

The subaccount absorbs the fee. The fee is deducted from the subaccount's share before settlement. Your main account receives its full calculated share. This shifts the cost of payment processing to the vendor. Some platforms use this model when the vendor relationship allows it or when the platform needs to protect thin margins.

3. All (customer bears the fee)

Paystack increases the transaction amount to cover the processing fee, so the customer pays the fee on top of the product price. Neither your main account nor the subaccount is reduced. When you set bearer: 'all', Paystack calculates the surcharge automatically. Note that passing the fee to the customer may not be permitted in all jurisdictions or for all business types. Check Paystack's terms for your specific market before using this option.

Here is how you set it per transaction:

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: 1000000, // 10,000 NGN in kobo
    subaccount: 'ACCT_abc123xyz',
    bearer: 'subaccount', // Subaccount absorbs the Paystack fee
  }),
});

Getting the bearer wrong is one of the most expensive mistakes in marketplace development. If you intend for the vendor to bear the fee but leave the default (account), every transaction eats into your commission. On a 15% commission with high-volume, low-value transactions, the processing fee can consume a significant chunk of your margin. Model your unit economics with actual fee amounts at your expected transaction sizes before you ship.

For a detailed breakdown with worked examples showing the exact settlement amounts under each bearer option across different transaction sizes, read who bears the fee: split payment fee configuration.

A two-sided marketplace connects buyers and sellers, takes a cut of each transaction, and routes the rest to the seller. Paystack splits are built for exactly this pattern. Here is the architecture from seller onboarding to settlement.

Step 1: Onboard sellers

When a seller signs up on your platform, collect their business name and bank details. Validate the bank details using Paystack's Resolve Account endpoint, then create a subaccount and store the subaccount_code in your database alongside their user record.

The onboarding flow deserves careful thought. You need to handle cases where a seller's bank is not on Paystack's supported list, decide whether to verify the seller's identity (via Paystack's identity verification or your own KYC) before allowing them to receive payments, and build a UI that makes the bank details collection feel trustworthy. For a complete onboarding workflow with validation steps, see onboarding sellers to a Paystack marketplace.

Step 2: Initialize transactions with the split

When a buyer purchases from a seller, look up the seller's subaccount code and pass it when initializing the transaction:

// Buyer purchases from a seller on your marketplace
const order = await db.orders.findById(orderId);
const seller = await db.sellers.findById(order.sellerId);

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.email,
    amount: order.totalInKobo,
    subaccount: seller.paystackSubaccountCode,
    bearer: 'account',  // Platform absorbs the Paystack fee
    reference: `mkt_${order.id}_${Date.now()}`,
    metadata: {
      order_id: order.id,
      seller_id: seller.id,
      custom_fields: [
        {
          display_name: 'Order',
          variable_name: 'order_id',
          value: order.id,
        },
      ],
    },
  }),
});

Step 3: Handle the webhook

When the payment succeeds, the charge.success webhook payload includes the split details: the subaccount code, the amount each party received, and the fee deduction. Verify the signature, confirm the split amounts match your expectations, and update the order status in your database.

Step 4: Settlement happens automatically

Paystack settles the seller's share directly to their bank account on the normal settlement cycle. You do not need to trigger a transfer or move money manually. Your commission lands in your main Paystack balance on the same cycle.

For the complete architecture with database schema design, webhook handling, dispute flows, and the edge cases that trip up most marketplace builders, read building a two-sided marketplace on Paystack.

True escrow means holding funds in a neutral account until both parties confirm the transaction is complete. A buyer pays, the money sits in escrow, the seller delivers, the buyer confirms, and only then does the money release. Paystack does not offer true escrow. What it does offer is delayed settlement, which you can use to approximate escrow behavior within important limits.

How delayed settlement works

When you create a subaccount, you can set a settlement_schedule. The key option for escrow-like flows is manual settlement, where Paystack holds the subaccount's share until you explicitly trigger settlement through the API or dashboard. This gives you a window between payment and payout.

The flow looks like this: a buyer pays, the money is held (not settled to the subaccount), the seller ships or delivers, the buyer confirms receipt on your platform, and then your backend triggers settlement to the subaccount. That is escrow-like behavior built on top of splits.

The limits you must understand

• Holding periods are not indefinite. Paystack has policies about how long funds can be held before settlement. You cannot hold a subaccount's money for months. Check Paystack's current terms for maximum hold durations in your market.
• Release is one-directional. Once you release funds to a subaccount, you cannot pull them back. If a buyer raises a dispute after settlement, you need to handle the refund from your own balance or work out recovery with the vendor outside of Paystack.
• Refunds on settled splits are your problem. If you refund a split transaction after the subaccount has been settled, the refund comes from your main Paystack balance. You are out of pocket until you recover the vendor's portion through your own arrangement.
• You are not a licensed escrow service. Building an escrow-like flow on Paystack does not make you a regulated escrow provider. In Kenya, Nigeria, and other African markets, holding funds on behalf of third parties may require specific financial licensing depending on how the product is structured.

Delayed settlement works well for delivery-based marketplaces where there is a short window between payment and fulfillment: a few hours for food delivery, a few days for e-commerce shipping. It does not work well for long-duration holds like property deposits, milestone-based freelance contracts spanning weeks, or any situation where the hold period is unpredictable.

For a thorough analysis of what you can and cannot build with this pattern, read escrow-style flows on Paystack and their limits. For implementation patterns and code, see delayed settlement patterns for marketplaces.

Your commission is whatever the subaccount does not get. How you structure that commission defines your marketplace's business model and directly affects vendor acquisition and retention. Here are the models that work with Paystack splits.

Flat percentage commission

Set the subaccount's percentage_charge to 85, and you keep 15% of every transaction. Simple, predictable, easy to explain to vendors during onboarding. This is what most early-stage marketplaces start with because it requires zero per-transaction logic on your server.

Tiered percentage

Different sellers get different commission rates based on volume, category, or tenure. A new seller might be on 80/20, while a high-volume seller negotiates 92/8. You implement this by setting different percentage_charge values per subaccount, or by overriding the split on each transaction based on your tier logic.

Fixed service fee

You take a flat amount per transaction using transaction_charge. The vendor gets everything else. This works for platforms that charge a booking fee or listing fee rather than a revenue share. The vendor keeps more on high-value transactions, which can be a strong selling point during vendor recruitment.

Hybrid: percentage plus minimum

You want 15% of every transaction but no less than 200 NGN. Paystack does not support this natively with a single parameter. You implement it by calculating the commission on your server before initializing the transaction, then passing either the percentage (if 15% exceeds 200 NGN) or a flat transaction_charge of 200 NGN (if 15% would be less). This requires per-transaction logic but gives you the best of both models.

Multi-party commission

The platform takes a cut, a referral agent takes a cut, and the vendor gets the rest. Use multi-split with separate subaccounts for each party. This is common in insurance distribution, referral-based marketplaces, and platforms with regional sales agents who bring vendors onto the platform.

The key insight: Paystack gives you the split mechanics, but commission strategy is a business decision. Model your unit economics with realistic transaction sizes for your market, include the Paystack processing fee (and which party bears it), and make sure your commission covers your operating costs at your expected transaction volume. For a detailed walkthrough of each model with margin calculations, see commission models on Paystack splits.

Split payments appear in nearly every category of African tech product. Here is how each one maps to Paystack's split features and where the engineering challenges live.

Food delivery

A customer orders from a restaurant through your app. The payment splits three ways: the restaurant gets 70%, the delivery rider gets 10%, and your platform keeps 20%. You use multi-split with two subaccounts (restaurant and rider). The split group changes per order because the restaurant and rider combination is different each time. The tricky part is creating or selecting the right split group dynamically at checkout, and handling cases where the rider has not been assigned yet when the customer pays. See building a food delivery marketplace on Paystack.

Freelance marketplace

A client hires a freelancer through your platform. The freelancer's subaccount gets 85% and your platform keeps 15%. You use delayed settlement so the client can confirm delivery of the work before the freelancer gets paid. If the work is not delivered or does not meet requirements, you do not release the funds. The challenge is managing disputes and partial deliveries where the client wants a partial release. See building a freelance marketplace on Paystack.

Event ticketing

An organizer lists an event on your platform. Each ticket purchase splits between the organizer's subaccount and your platform. You might take a flat fee per ticket rather than a percentage, since a 15% commission on a 50,000 NGN VIP ticket feels very different to the organizer than 15% on a 2,000 NGN general admission ticket. Flat fees per ticket keep the model transparent and predictable for organizers. See building an events ticketing platform with splits.

Multi-vendor e-commerce

A store where multiple sellers list products, similar to how Jumia or Konga operate. Each seller has a subaccount. When a customer checks out a cart with items from three different sellers, you have two options: split the cart into separate transactions (one per seller, each with its own split) or use multi-split on a single transaction. Separate transactions are cleaner for refunds and per-seller tracking but mean the customer sees multiple charges on their statement. Multi-split is a single charge but makes partial refunds harder. See building a multi-vendor store with Paystack.

SACCOs and chamas

A chama contribution platform where members pay monthly dues. The payment can split between the chama's main account and individual member savings buckets (represented as subaccounts). This stretches the subaccount model since subaccounts are designed for business settlement rather than savings accounts, but it works for basic contribution splitting where each member's share goes directly to their bank account. For more complex chama structures (loans, rotating contributions, interest), you will likely need to supplement splits with transfers. See splitting payments for SACCOs and chamas.

In every case, the underlying Paystack pattern is the same: create subaccounts, choose percentage or flat, set the bearer, initialize transactions with the split parameters. The business logic around the split (when to release funds, how to handle disputes, what commission to charge, how to manage refunds) is where the real product engineering happens.

Reconciliation for split payments is harder than for regular transactions because you are tracking money flowing to multiple parties per transaction. A single customer payment creates settlement entries for your main account, one or more subaccounts, and a fee deduction. Here is how to keep it clean.

What Paystack gives you

For every split transaction, the verification response includes split details showing the breakdown: which subaccount received what amount, the fee deducted, and who bore the fee. The webhook payload contains the same data. Paystack also provides settlement reports per subaccount through the dashboard and API, showing when each settlement was made and for how much.

What you need to track on your end

• Transaction-level split details. Store the split breakdown for every transaction in your database. Record the intended split (what you expected based on your commission model) and the actual split (what Paystack confirmed in the verification response). Flag any discrepancies automatically.
• Subaccount balances. For each subaccount, track the total amount earned, the total amount settled by Paystack, and the outstanding balance awaiting settlement. Paystack settles on its own schedule, so there is always a lag between when a transaction succeeds and when the subaccount receives funds.
• Platform commission ledger. Your share of every split transaction. Sum these up per period and reconcile against your main Paystack balance and settlement reports. This is your revenue.
• Fee tracking. Record which party bore the Paystack fee on each transaction. If you use different bearer configurations for different vendors or transaction types, this can get complicated. A simple fee_bearer column on your transactions table saves hours of debugging later.

Daily reconciliation process

1. Pull your transaction list from Paystack for the period using GET /transaction?from=DATE&to=DATE
2. For each split transaction, compare the split amounts in Paystack's response against what you stored locally
3. Pull subaccount settlement reports and match against your expected settlements per subaccount
4. Check your main account settlement against your expected commission total for the period
5. Flag any discrepancies for manual review and investigation

At scale, you automate this with a daily job that pulls data from Paystack's API and your database, compares the numbers, and sends alerts when mismatches exceed a threshold. Even a simple script that runs on cron and sends a Slack notification for discrepancies will save you from the alternative: discovering a reconciliation problem weeks later when a vendor complains about a missing payment.

For a full reconciliation system design with code, database schema, and alerting patterns, see split payment reconciliation and subaccount reporting.

This guide is the hub for everything about split payments and marketplace payment flows on Paystack. Each topic has a dedicated deep-dive article with full code examples and production patterns. Here is how the cluster is organized.

Core split concepts

• Paystack split payments explained: How splits work under the hood, the settlement flow, and key terminology
• Subaccounts on Paystack complete guide: Creating, updating, listing, and managing subaccounts end to end
• Multi-split payments explained: Dividing one payment among three or more parties
• Percentage vs flat split configuration: Choosing and implementing the right split type for your model
• Who bears the fee: Configuring which party absorbs the Paystack processing fee

Marketplace architecture

• Building a two-sided marketplace on Paystack: End-to-end architecture for buyer-seller platforms
• Onboarding sellers to a Paystack marketplace: Vendor registration, bank validation, and subaccount creation flows
• Escrow-style flows and their limits: What you can and cannot build with delayed settlement
• Delayed settlement patterns for marketplaces: Hold-and-release implementation with code
• Commission models on Paystack splits: Percentage, flat, tiered, and hybrid pricing strategies with margin math

Real-world builds

• Building a food delivery marketplace: Multi-party splits for restaurants, riders, and platform
• Building a freelance marketplace: Delayed settlement for work-then-pay flows
• Building an events ticketing platform with splits: Per-ticket flat fees and organizer settlements
• Building a multi-vendor store: Cart splitting and multi-seller checkout patterns
• Splitting payments for SACCOs and chamas: Contribution collection and member distribution

Operations and migration

• Split payment reconciliation and subaccount reporting: Tracking money across multiple parties
• Migrating from manual payouts to Paystack splits: Moving from collect-then-transfer to automatic splitting
• Testing split payment logic safely: Validating split configurations in test mode before going live

For how split payments fit into the broader Paystack integration picture alongside webhooks, verification, transfers, and recurring billing, see the Paystack complete engineering guide.

Paystack updates their split payment features, settlement schedules, and supported markets periodically. We keep these guides updated when things change.

If you are building a marketplace on Paystack and want to learn the full stack from payment integration to deployment, the McTaba bootcamp covers payment systems as a core module. Every graduate ships code that moves real money.

Create a free McTaba account