Split Payments Integration

Split payment configurations may be specified similarly across different GraphQL mutations, depending on what API is being used to initiate the transaction:

• Individual Transactions (whether once-off, or tokenized)
• Batch Collections

Individual Transaction Split Payment

The splitSettlements field is available for any initiateTransaction call and accepts an array of settlement objects. Refer to Once-off or Tokenized transaction initiation documentation, for complete integration details.

The example below demonstrates initiating a R400 transaction with R120 split to a destination merchant:

Batch Collection Split Payment

The splitSettlements field is an optional array on each CollectionInput within clientCollectionBatchCreate. Refer to Batch Collection documentation, for complete integration details.

The following example creates a batch with one collection that splits a fixed R120 to the destination merchant:

Split Payment Request Fields

Field	Type	Description
splitSettlements	array (optional)	Split payment instructions for an individual transaction or batch collection. Only a single entry is supported at present.
[].merchantId	string	Pre-registered merchant identifier, provisioned by Stitch.
[].amount	object	Fixed amount to settle to the merchant.
[].amount.currency	string	Must match collection currency (ZAR).
[].amount.quantity	numeric	Amount in rands (up to 2 decimal places). Must be > 0 and ≤ collection amount.

Split Payment Response Fields

Settlement outcomes are returned on the transaction or collection node. primarySettlement.amount and splitSettlements[].amount are the gross designated amounts. The amount actually settled to each beneficiary is its netAmount (the gross amount minus its feeAmount). Every Money object carries a currency and a quantity. feeAmount and netAmount are null until fees are computed (while the transaction is still pending), never zero.

Field	Type	Description
splitSettlements[].amount	object	Gross amount designated to this destination merchant.
splitSettlements[].feeAmount	object	This destination merchant's fee. Null until computed.
splitSettlements[].netAmount	object	This destination merchant's net settlement (amount minus feeAmount). Null until computed.
primarySettlement	object	The client's own settlement: amount (gross, always present), feeAmount, and netAmount.
feeAmount	object	Aggregate fee across all beneficiaries. Null until computed.
netAmount	object	Aggregate net across all beneficiaries (amount minus feeAmount). Null until computed.

Querying Split Payment Status

Individual Transaction

Query the split payment outcome on a single transaction using the node query with a CardTransaction fragment:

Batch Collection

Query the split payment outcome per collection using GetPaymentCollectionBatch. Include primarySettlement, splitSettlements, and the aggregate feeAmount/netAmount on each collection node to retrieve the settlement breakdown.

Webhooks

The transaction webhook fires as normal when a transaction transitions through its lifecycle statuses. No additional webhook configuration is required for split payment. The webhook payload does not deliver any split-settlement data in this phase: it carries neither the per-split merchantId/amount, the primarySettlement, nor any feeAmount/netAmount field. To retrieve split-settlement detail, query the transaction or collection from the read API (see Querying Split Payment Status above). See Webhooks for details.

Error Handling

Split payment validation surfaces differently depending on which API you use.

On initiateTransaction, a split validation failure is returned as a UserInputError. The specific split code is available on the error's extensions.code, and extensions.failures lists each failing split instruction. The specific codes below apply to this path only.

Code	Description
invalid_split_amount	The split amount exceeds the collection amount or is not positive.
split_settlement_not_enabled	Split payments are not enabled for this client. Contact Stitch to enable.
invalid_merchant	The merchantId is not recognised, or is not registered as a sub-merchant under the calling client.
duplicate_merchant	The same merchantId appears more than once in splitSettlements.
splits_limit_exceeded	More split instructions were provided than are allowed (see the single destination merchant limitation).

On clientCollectionBatchCreate, split validation runs per collection but the specific code is not surfaced. Any split validation failure collapses to a single generic entry in the errors array for the affected row:

Code	Description
invalid_split_settlement	A split instruction on this collection failed validation. Returned per failing row in the batch errors array, with the row's nonce. Use initiateTransaction to obtain the specific validation code.