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 via two distinct fields. primaryMerchantAmount reflects the primary merchant's settlement before any applicable fees; splitSettlements[].settledAmount reflects the amount each destination merchant will be settled.

Field	Type	Description
primaryMerchantAmount	object	Settlement amount to the primary merchant, before any fees are applied.
primaryMerchantAmount.currency	string	Settlement currency (ZAR).
primaryMerchantAmount.quantity	numeric	Amount in rands.
splitSettlements[].settledAmount	object	Final amount settled to this destination merchant.

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 primaryMerchantAmount and splitSettlements 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 includes primaryMerchantAmount and splitSettlements data (each destination merchant's merchantId, requested amount, and settledAmount). See Webhooks for details.

Error Handling

The following error codes are specific to split payment and appear in the errors array returned by clientCollectionBatchCreate:

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 not registered for this client.