Building a Multi-Vendor Store with Paystack
When a customer checks out with items from multiple vendors, create a Transaction Split group (POST /split) listing each vendor's subaccount and their flat share (item subtotal minus commission). Pass the resulting split_code when initializing the transaction. On charge.success, fulfill each vendor's order items. Paystack settles each vendor directly into their bank account.
Mixed-Cart Split Checkout
// Cart: items from multiple vendors
// [{ vendor_id, items, subtotal }]
app.post('/api/checkout', async (req, res) => {
var { cart, email } = req.body;
var commissionRate = 0.10;
var total = cart.reduce((s, v) => s + v.subtotal, 0);
// Build subaccounts list for the split
var splitSubaccounts = await Promise.all(
cart.map(async (vendorCart) => {
var vendor = await db.vendors.findById(vendorCart.vendor_id);
var vendorShare = Math.round(vendorCart.subtotal * (1 - commissionRate) * 100); // kobo
return { subaccount: vendor.subaccount_code, share: vendorShare };
})
);
// Create Transaction Split
var splitRes = 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: 'Cart ' + Date.now(),
type: 'flat',
currency: 'NGN',
subaccounts: splitSubaccounts,
bearer_type: 'account',
}),
});
var splitData = await splitRes.json();
// Initialize transaction with split
var txRes = 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,
amount: total * 100,
split_code: splitData.data.split_code,
metadata: { cart: cart.map(v => ({ vendor_id: v.vendor_id, subtotal: v.subtotal })) },
}),
});
var txData = await txRes.json();
res.json({ authorization_url: txData.data.authorization_url });
});Learn More
This guide is part of the Paystack split payments guide.
Key Takeaways
- ✓For mixed-vendor carts, create a Transaction Split group per order listing each vendor's flat share.
- ✓Your platform commission stays as the residual — the sum of all vendor shares must be less than the total charge.
- ✓Create vendor subaccounts during seller onboarding. Store subaccount_code against each vendor record.
- ✓On charge.success, split the order fulfillment tasks by vendor and notify each seller of their items.
- ✓Delete or reuse split groups — creating a new split per order is fine for variable carts.
- ✓Use GET /split to list and reuse existing split groups for fixed vendor combinations.
Frequently Asked Questions
- Is there a limit on how many subaccounts can be in one Transaction Split?
- Paystack supports up to 5 subaccounts in a single Transaction Split group. For carts with more than 5 vendors, split the checkout into separate transactions per vendor or batch vendor payments via transfers after a single platform collection.
- Can the sum of subaccount shares exceed the total transaction amount?
- No. The sum of all flat share amounts in the split must be less than or equal to the transaction total. Any amount not allocated to a subaccount goes to your main account as commission. If shares exceed the total, Paystack will reject the split.
- How do I handle a refund on a multi-vendor cart when only one vendor's items are returned?
- Issue a partial refund for the returned item value from your platform balance. Paystack partial refunds do not automatically claw back the vendor's subaccount share. You either absorb the refund or charge the vendor separately for the returned item.
- Should I delete split groups after use?
- You can, but it is not necessary. Unused split groups do not incur charges. For carts that are always different, create new splits per order. For fixed vendor combinations (e.g., a franchise with 3 fixed outlets), create one split group and reuse the split_code on every transaction.
Ready to build real-world apps?
Join the McTaba Labs full-stack marathon (4 months full-time · 6 months part-time). Learn M-Pesa, USSD, and WhatsApp engineering while shipping 8 production apps.
Apply to the McTaba Marathon