Understanding Payment Obligations in a Marketplace
In a marketplace model, payments flow from buyers to providers through the platform. The platform often collects fees or commissions, while providers receive their share of the payment. Before choosing a payment gateway, it is essential to map these obligations clearly:
- Buyer obligations: What payment methods and schedules are supported?
- Platform obligations: How and when does the platform take its commission or fees?
- Provider obligations: When and how do providers get paid, and what are their payout preferences?
This mapping sets the foundation for understanding how your payment flows must behave.
Verifying Gateway Split-Payment Capabilities
Payment gateways differ in their support for split payments. Some support direct split payments to multiple parties in one transaction; others require manual or delayed transfers. Key capabilities to verify include:
- Support for multi-party payments or transfers.
- Ability to deduct platform fees automatically.
- Support for refunds and chargebacks affecting all parties.
- API access for managing payment splits programmatically.
For example, Stripe Connect offers direct charges, destination charges, and separate charges and transfers, each with different fund flow models suitable for marketplaces. Payfast offers a Split Payments feature; assess the exact account and integration model rather than assuming it supports arbitrary recipients, escrow or your desired settlement schedule.
Geographic and Regulatory Considerations
South African marketplaces must consider gateway availability and compliance:
- Stripe lists South Africa under an extended network linked to Paystack, that does not establish access to Stripe Billing or Connect APIs.
- Payfast is a PCI DSS Level 1 Service Provider based in South Africa, advertising recurring billing and a separate split-payment feature; review each feature against your actual merchant arrangement.
Confirm whether the gateway supports South African merchant accounts, complies with local regulations, and allows payouts to providers' bank accounts within South Africa.
Mapping Settlement Behaviour
Settlement behaviour defines when and how funds move to providers and the platform. Consider:
- Timing of settlements (immediate, delayed, scheduled).
- Handling of refunds and chargebacks.
- Managing insufficient funds or failed payments (e.g., provider-specific retry behaviour must be verified).
- Whether any approved holding or delayed-release arrangement exists; do not call a ledger balance escrow.
Design your marketplace logic to align with the gateway's capabilities and contract terms.
Creating a Payment-Provider Requirements Brief
A requirements brief captures all payment-related needs and constraints for gateway evaluation:
| Requirement | Description | Priority | Notes |
|---|---|---|---|
| Multi-party payment support | Ability to split payments between platform and providers automatically | High | Needed for commission deduction |
| Refund handling | Support for refunds affecting all parties correctly | High | Must handle partial refunds |
| API access | Programmatic control over payments and transfers | High | For automation |
| South African merchant support | Gateway must support local entities and bank payouts | High | Compliance and settlement |
| Subscription support | Recurring payments for memberships or retainers | Medium | Useful for some marketplaces |
| Payment retries | Handling failed payments and retries | Medium | E.g., Payfast subscription retries |
Use this brief to compare gateways against your marketplace needs.
Hypothetical obligation model before choosing technology
Suppose the commercial brief proposes a 10% commission. Record buyer gross amount, commission basis, processor fees, provider entitlement, refunds and disputes separately. Do not select manual bank transfers simply because a gateway feature has not been verified. Identify the legal collector, supplier and refund owner, then obtain confirmation that the provider permits the proposed arrangement.
How to Use the Payment-Provider Requirements Brief
- List your marketplace's payment needs and priorities.
- Research gateway features and limitations.
- Map each gateway's capabilities against your brief.
- Select the gateway that best matches your requirements.
- Plan your settlement logic based on confirmed features.
This structured approach reduces risk and aligns technical design with business goals.
Designing a Payment-Provider Requirements Brief: Detailed Template
A well-structured payment-provider requirements brief is essential to align your marketplace’s payment flows with gateway capabilities. Below is a detailed template with fields and decision criteria tailored for South African marketplace founders and product owners.
| Field | Description | Expected Values / Actions | Decision Evidence | Recovery Steps |
|---|---|---|---|---|
| Payment Types Supported | List all payment methods your marketplace must accept (e.g., credit card, EFT, mobile money). | Confirm gateway supports all required methods locally. | Gateway documentation and sandbox tests showing supported methods for South African merchants. | If unsupported, consider adding fallback payment methods or alternative gateways. |
| Split Payment Model | Define how payments split between platform and providers (e.g., automatic split at transaction, manual payout after full payment). | Choose 'automatic', 'manual', or 'hybrid'. | Gateway API docs verifying split payment or multi-party payout features. | If automatic split unavailable, plan manual transfer workflows with reconciliations. |
| Fee Deduction Timing | When platform fees are deducted (upfront, after payment clearance, or delayed). | Specify timing aligned with cash flow needs. | Contract terms and gateway settlement timing details. | Adjust platform accounting for delayed fee recognition if needed. |
| Refund & Chargeback Handling | How refunds or disputes affect split payments and balances. | Confirm gateway supports partial refunds and reversals affecting all parties. | Gateway refund API capabilities and dispute policies. | Implement manual reconciliation if automatic refund splits are unsupported. |
| API Access & Automation | Level of API control required for payment, refund, and transfer operations. | Full programmatic control preferred for automation. | API documentation and sandbox testing results. | Build manual admin tools if API automation is limited. |
| Settlement Timing | Expected timing for payouts to providers and platform (e.g., immediate, T+1, weekly batch). | Match gateway settlement schedules with provider expectations. | Gateway payout schedules and banking cut-off times. | Communicate delays clearly to providers; obtain approval for any delayed release; never invent escrow capability. |
| Provider Bank Account Support | Types of provider bank accounts supported (local banks, international, mobile wallets). | Must support South African banks for providers. | Gateway payout options and regional restrictions. | If unsupported, explore third-party payout services or manual payments. |
| Subscription & Recurring Payments | Requirement for recurring billing for memberships or retainers. | Confirm gateway supports subscriptions with API control. | Gateway subscription feature documentation (e.g., Payfast subscriptions). | Use external subscription management if gateway lacks features. |
| Retry Logic for Failed Payments | How failed payments are retried and subscription status managed. | Define retry count, intervals, and lockout behaviour. | Gateway retry policies and webhook event support. | Implement internal logic for retries or customer notifications if gateway lacks features. |
| Compliance & Security | PCI DSS compliance, data privacy, and local regulatory adherence. | Review applicable obligations and the provider certification scope; a provider certificate does not prove your platform is compliant. | Gateway certifications and compliance statements. | Avoid gateways lacking compliance; plan for additional security controls. |
Use this template to systematically evaluate gateways and communicate your marketplace needs clearly to payment providers.
Hypothetical ledger worksheet and provider questions
An invented artisan marketplace proposes a 12% platform commission on a R1,000 gross order. For this arithmetic example only, processor fees, tax treatment, reserves and rounding are excluded. Initial commercial allocation is R120 platform commission and R880 provider entitlement. Those amounts represent proposed ledger obligations, not actual gateway balances or settled money.
If a R200 partial refund is completed and the adopted contract reverses commission proportionally, commission reduces by R24 and provider entitlement by R176. Remaining allocation is R96 plus R704, totalling the R800 retained gross amount. Another contract may retain some commission or allocate fees differently. Record that choice explicitly; do not treat proportional reversal as universal gateway behaviour.
| Provider question | Written confirmation to obtain | Evidence to test |
|---|---|---|
| Merchant and recipient eligibility | Entity, country, bank account, service category and account requirements | Approved account and capability readback |
| Split model | Main/secondary or connected-account arrangement; supported recipients and methods | Test transaction with expected references and allocation |
| Fees | Calculation basis, who pays, rounding and fee refundability | Gross/fee/net reconciliation |
| Refund responsibility | Partial refund, transfer reversal and insufficient-balance handling | Separate refund and reversal results |
| Disputes | Liable party, reserves and already-paid provider recovery | Recorded exception path and operator owner |
| Settlement | Account credit versus actual bank payout; deadlines and failures | Provider settlement evidence matched to bank result |
| Delayed release | Whether allowed for this arrangement and under which terms | Documented capability; no assumed escrow |
| API and retries | Available operations, idempotency and notification validation | Duplicate, delayed and unknown-outcome cases |
Review collection, allocation and bank payout as separate transitions. Payment pending is not entitlement settled. Funds credited to a gateway account may still await a bank payout. A failed refund request must not reduce a customer liability as though money was returned. A successful bank transfer after a response timeout needs reconciliation before retry, or the provider may receive two payments.
The proposed state worksheet should record order/request reference, buyer, provider, merchant account, gross amount, currency, fee model version, platform allocation, provider allocation and separate payment/refund/transfer/payout states. Link every external result to its authoritative provider reference. Restrict bank-detail edits and money actions by role and keep a reviewable history.
Evaluate options without conflating APIs
Payfast's own feature page establishes a specific account-based split capability. Stripe Connect describes a different set of charge and transfer models. Paystack has its own products and APIs. A commercial association or an extended-network listing does not make these interchangeable. Mark an option as unresolved until its actual product, geography, account configuration and contract meet the brief.
Do not choose a gateway solely from this article. Ask whether the supported split can handle your transaction, what happens after a provider is already paid and which party carries refund/dispute losses. Sandbox results show integration behaviour under test conditions; merchant approval and a properly authorised live reconciliation are separate gates.
Transaction tests to attach to the requirements brief
Test one successful collection with its allocation, a duplicate notification, partial refund before payout, refund after payout, recipient account rejection, bank payout timeout and inconsistent amount/currency. For each, list expected ledger entries, permitted action, customer/provider communication and operator recovery. Test negative entitlement and reserve conditions according to the contract rather than quietly paying an incorrect amount.
These procedures are proposed operating rules and unexecuted tests. They do not show a live merchant approval, client result or compliant financial arrangement. The practical output is a provider brief that exposes decisions requiring confirmation before implementation.
What the primary documentation establishes
Payfast's Split Payments page describes predetermined funds split from a main Payfast account to a secondary Payfast account, with fixed, percentage or combined amounts. This corrects the assumption that Payfast has no automatic splits. It does not establish arbitrary multi-party payouts, escrow or suitability for every marketplace contract.
Payfast's subscriptions page describes scheduled recurring card payments and subscription management. Recurring collection is a separate capability from provider settlement; verify the required combination.
Stripe Connect's charge documentation distinguishes direct charges, destination charges and separate charges/transfers, with different responsibility and funds-flow models. Those are Stripe-specific models, not Payfast or Paystack API instructions.
Stripe's availability page lists South Africa in its extended network with Paystack. That does not establish that a South African business can use Stripe Connect through Paystack. Confirm eligibility for the exact product and entity before designing against its API.
Frequently asked questions
What is a payment split in a marketplace context?
A payment split divides the buyer's payment between the platform (usually as commission) and the providers delivering goods or services.
Can all gateways handle split payments automatically?
No. Check the exact provider product and account arrangement. Payfast documents its own main-to-secondary-account Split Payments feature; Stripe Connect describes different charge and transfer models. Neither establishes arbitrary splits or suitability for every marketplace.
How does geographic location affect gateway choice?
Gateways may have limited support for South African merchants or payouts. Confirm local availability and compliance before selection.
What happens if a payment fails or is refunded?
Specify the exact charge, transfer and payout model in the provider brief. Obtain evidence for partial refunds, transfer reversals, fees and negative balances; do not infer that refunding a customer automatically recovers funds already paid to a provider.
If your business is building a marketplace platform, start by mapping your payment obligations and verifying gateway capabilities carefully. This avoids costly redesigns and ensures smooth settlements.
If you need help designing or developing your marketplace payment flows, get in touch with our experts at Symaxx Marketplace Platform services.
For wider planning, use the SaaS development overview, CMS vs Custom Development guide, Discovery Phase Checklist and User Journey glossary.