Split payments API for Nigerian marketplaces: A settlement guide

A split payments API for Nigerian marketplaces should help you answer a deceptively simple question: when a buyer pays once, who is entitled to each part of the money, and when can they receive it? For founders and product teams, the answer determines seller trust, platform revenue and how easily operations can resolve disputes.

The challenge is not just sending money to several bank accounts. It is keeping commissions, seller earnings, delivery charges and refunds consistent throughout an order’s lifecycle.

This guide explains how to design that workflow for Nigeria using explicit allocation rules, ledger balances and bank payouts. It also shows where Paddle’s payment infrastructure fits, without assuming that every marketplace needs the same settlement model.

What a split payment actually means

Consider an illustrative marketplace order worth ₦50,000. Your commercial agreement assigns ₦43,000 to the seller, ₦5,000 to the platform and ₦2,000 to a delivery provider. These are example allocations, not Paddle fees or recommended commission rates.

That single payment creates three economic entitlements. It does not necessarily require three immediate transfers.

Keep these concepts separate:

• Collection: receiving the buyer’s payment.
• Allocation: recording who is entitled to each portion.
• Release: deciding when an allocation becomes payable.
• Settlement: moving the payable amount to a beneficiary.

This distinction matters when delivery is incomplete, a seller has several orders, or a buyer requests a partial refund. An internal allocation can change through a controlled adjustment; a completed bank transfer cannot simply be edited.

Your product should therefore treat splitting as a financial workflow, not merely a list of payout destinations.

Split payments API for Nigerian marketplaces: Choose your settlement model

Before selecting endpoints, decide what promise you are making to sellers. “You earned this amount” and “this amount is available for withdrawal” should not mean the same thing unless your operating model genuinely supports it.

Immediate settlement

Eligible funds are sent to beneficiaries soon after confirmed collection. This can suit transactions where fulfilment is immediate and dispute exposure is manageable.

The trade-off is refund funding. If the seller has already received the money, the marketplace needs an agreed recovery mechanism or another source of refund liquidity.

Scheduled settlement

Seller earnings accumulate and are paid in batches according to your published schedule. This can simplify seller statements and reduce the number of small transfers your operations team must track.

Define cut-off times, eligibility rules and how exceptions affect the next settlement run. Avoid promising availability based solely on when a payout request was submitted.

Milestone-based release

Allocations become payable after an agreed event, such as delivery confirmation or acceptance of a service.

Paddle offers escrow capabilities, but do not assume that delaying an internal payout automatically creates an escrow arrangement. Confirm the supported structure, release conditions and partner requirements before presenting the service as escrow.

Define allocation rules before building the payment flow

Your allocation engine should produce the same result from the same order inputs. That means replacing informal commission logic with a versioned policy.

At minimum, specify:

• Whether commission applies to merchandise only or also to delivery.
• Who funds discounts and promotional credits.
• How payment-related charges affect each party’s entitlement.
• How partial cancellations change seller and platform allocations.
• Whether reserves or other deductions apply under your seller agreement.

Store the policy version with each order. A later commission change should not silently rewrite an earlier transaction.

Use integer minor units rather than floating-point arithmetic. For naira amounts, calculate in kobo and adopt a deterministic rounding rule. When a percentage calculation leaves a remainder, assign it consistently and preserve the explanation.

For every confirmed collection, the total allocated amount must equal the amount being distributed. Any unapplied balance should remain explicitly identified, not disappear into a rounding difference.

Build a ledger that explains every balance

A seller dashboard needs more than one balance. A useful starting model distinguishes:

• Pending earnings: allocated funds that have not met release conditions.
• Available earnings: released funds eligible for settlement.
• Reserved amounts: funds restricted under a documented policy.
• Payouts in progress: funds committed to a settlement attempt.
• Settled earnings: amounts associated with confirmed completed payouts.

These are conceptual balance categories, not Paddle API field names.

Use ledger entries to record movements between categories. Do not update a seller’s available balance by overwriting a database number without an audit trail.

A balanced, double-entry model makes each movement explainable: value leaving one account has a corresponding entry elsewhere. Your ledger design should also distinguish actual cash positions from obligations owed to sellers.

Paddle offers ledgers as part of its platform. Check the documentation and confirm the account structure and posting capabilities available for your intended workflow before choosing how much accounting logic to implement yourself.

Separate order events from money movement

An order service knows whether an item was delivered. A financial service knows whether funds are collected, allocated and payable. Connect those services through explicit events rather than letting every order update trigger a bank transfer.

A practical sequence is:

1. Create the order with a snapshot of its allocation policy.
2. Receive and verify collection confirmation through the supported integration.
3. Record the collection and create beneficiary allocations.
4. Wait for the relevant release condition.
5. Move eligible allocations into available balances.
6. Create settlement instructions for verified beneficiaries.
7. Track payout outcomes and publish clear seller statements.

Each step should reference the original order, allocation and beneficiary. If several orders are combined into one seller payout, preserve the relationship between that payout and all the earnings it settles.

Paddle’s virtual accounts, or NUBANs, can support Nigerian bank-transfer collections, while its instant NIP payout capability reaches 120+ Nigerian banks. Confirm the supported account assignment model and payout requirements for your business. Keep allocations and release decisions explicit in your application unless you have confirmed a provider feature that handles them.

Plan refunds before sellers can withdraw

Refunds reveal weaknesses in split-payment designs quickly. A full refund may require reversing seller earnings, platform commission and delivery allocations—but only according to the applicable commercial terms and what has actually been fulfilled.

For a partial refund, use item-level allocations where possible. Recalculating the entire order using today’s commission policy can produce the wrong result.

If funds have not been released, your workflow can adjust the corresponding pending entitlements. If a payout has already completed, record the refund obligation separately and apply the agreed funding or recovery process.

Never assume that a seller balance can become negative without limits or contractual support. Decide who funds the buyer’s refund, how recovery works and when human approval is required.

Preserve the original entries and create linked adjustments. This gives support teams a readable history instead of a transaction that appears to have changed after the fact.

Launch checklist for product and engineering teams

Before enabling seller settlements, test the business rules as carefully as the payment integration:

• Beneficiaries: verify onboarding status and required bank details before making balances withdrawable.
• Allocation: test multiple sellers, discounts, delivery charges and rounding remainders.
• Release: document which event authorises payment and who can override it.
• Refunds: test cancellations before release and refunds after settlement.
• Statements: show gross earnings, deductions, adjustments and payout status separately.
• Access: restrict allocation edits, manual releases and beneficiary changes.
• Exceptions: route missing details, disputed orders and unsuccessful payouts to a visible queue.
• Liquidity: ensure payable ledger balances are backed by funds available for settlement.

For Nigeria, confirm applicable onboarding, AML and funds-handling requirements with your provider and qualified advisers. Check the latest CBN circulars where relevant. This is product and engineering guidance, not legal advice.

Build it with Paddle

Paddle gives African digital businesses building blocks for marketplace settlement: virtual accounts for collections, ledgers, KYB/AML verification, escrow capabilities and instant NIP payouts to 120+ Nigerian banks.

Start by defining your allocation policy and release model, then map each stage to the supported APIs. Confirm whether your required split workflow uses native capabilities, application-level orchestration or both before committing to a launch scope.

Paddle is a banking-as-a-service platform by Pickpadi Global Ltd, not a bank. Banking services are provided by CBN-licensed partner banks.

Ready to build a seller settlement flow your team can explain and operate? Create a free account and read the API docs.