Skip to main content

Split Payments

Split payment intents allow a primary merchant to split a transaction's settlement between themselves and a destination merchant at the transaction level. Rather than receiving the full settlement and manually on-settling destination merchants, the primary merchant instructs Stitch to settle a destination merchant a portion of the transaction value directly, reducing reconciliation errors and speeding up destination merchant payouts.

How It Works​

  1. The primary merchant includes a splitSettlements array on an initiateTransaction call or within a clientCollectionBatchCreate batch.
  2. The transaction or batch is submitted and processed.
  3. On successful payment, Stitch creates separate settlement intents for the primary merchant and the destination merchant.
  4. Each beneficiary, the primary merchant and each destination merchant, is settled net of its own fee.

Use Cases​

  • Marketplace splits: A marketplace collects payment and splits settlement between itself and the seller.
  • Commission and platform fees: A platform retains a commission while settling the remainder to a service provider.
  • Franchise models: A franchisee collects on behalf of a franchisor and splits settlement accordingly.
  • Collections on behalf of destination merchants: A primary merchant collects funds and directs a portion to a destination merchant.

Key Concepts​

Primary Merchant​

The client initiating the payment. The primary merchant owns the payment request, is responsible for configuring the split, and is settled net of its own fee.

Destination Merchant​

A third-party recipient identified by a pre-registered merchantId. Stitch creates and provisions this identifier against your client.

Destination merchants must be registered with Stitch before they can receive split payments.

Split Types​

Each split instruction specifies a fixed rand amount to allocate to the destination merchant.

Net-of-Fees Settlement​

Stitch charges a fee on every split-enabled transaction, and each beneficiary (the primary merchant and each destination merchant) bears its own fee. A beneficiary's fee has two components: a percentage of that beneficiary's own amount, plus an equal per-beneficiary share of a single fixed fee spread across all beneficiaries. Any rounding residual on the fixed fee is assigned to the primary merchant, and the primary always bears a fixed-fee share even when its own portion is zero.

Each beneficiary is settled net of its own fee. A destination merchant therefore receives its designated amount minus its own fee, not the full amount. The transaction fee is the sum of every beneficiary's fee.

Worked example (card fee schedule of 1% plus a fixed R0.25, applied to a R400.00 transaction with one R120.00 split, so the fixed fee is shared across two beneficiaries):

BeneficiaryamountfeeAmountnetAmount
Split merchant-abc-123120.001.32118.68
primarySettlement280.002.93277.07
Transaction (aggregate)400.004.25395.75

On the transaction or collection read, each beneficiary's fee and net are observable: each destination merchant's feeAmount/netAmount on splitSettlements[], the client's own primarySettlement, and the transaction-level aggregate feeAmount/netAmount.

Prerequisites​

note

Split payments require enablement by Stitch. Contact Stitch to enable split payments for your client and to register destination merchants with merchantId values.

Splitting Rules​

note

Fixed amount splits: Specified up to 2 decimal places (cents). The amount must be greater than zero and cannot exceed the transaction amount.

Limitations​

note
  • Single destination merchant per transaction: One destination merchant per transaction is supported.
  • ZAR only: Split payment is currently available for ZAR transactions only.