Split Payment Refunds

Refunding a split-payment transaction reverses the settlement across the same beneficiaries the original charge settled. A refund is created with the same refundTransactionInitiate mutation and read back on the same CardRefundTransaction node used for any card refund. Split refunds add per-beneficiary and aggregate fee and net detail to that read, in the exact shape you already integrate on the charge side.

How a Split Refund Works

• A refund is its own transaction in the opposite direction to the charge, with its own fresh fee.
• A refund reuses the original charge's split configuration (beneficiary merchants and split proportion). You do not re-specify splits on a refund. They are inherited from the original transaction, so the refund mutation stays exactly as documented on the general Refunds page.
• Each beneficiary's refunded share is apportioned pro-rata by its gross share of the original transaction. In the canonical R400.00 charge with a R120.00 split, the primary holds 70% (R280.00) and the destination merchant 30% (R120.00), so a partial refund is split 70/30.
• Stitch charges a fresh fee on the refund, calculated the same way as the charge fee, and never returns the original charge fee. The fee is charged to each beneficiary and netted off its settlement, with any rounding residual assigned to the primary.
• The cardholder always receives the full refund amount. The fresh refund fee falls on the beneficiaries (the merchant side), not on the cardholder.

Refund Detail

The refund read reuses the charge-side field names (amount, feeAmount, netAmount) but inverts their meaning. On a charge, these fields describe money credited to a beneficiary. On a refund, they describe money debited from the beneficiary: each beneficiary returns its apportioned gross amount and is charged a fresh fee.

note

Do not read a refund's feeAmount/netAmount as money flowing to the beneficiary. On a refund:

• amount is the gross amount moved from the beneficiary back to the cardholder.
• feeAmount is the fresh refund fee that beneficiary is charged.
• netAmount is the total debited from that beneficiary, which is amount plus feeAmount.

This is the opposite direction to the charge side, where netAmount is amount minus feeAmount and represents a credit the beneficiary receives.

Reading the Refund Settlement Breakdown

The refund transaction exposes the same per-beneficiary and aggregate breakdown as the charge, on the CardRefundTransaction node. You do not pass splits on a refund; the breakdown is derived by Stitch from the inherited splits.

Field	Type	Description
splitSettlements[].merchantId	string	The destination merchant the refund applies to. Inherited from the original transaction.
splitSettlements[].amount	object	Gross amount returned from this destination merchant to the cardholder.
splitSettlements[].feeAmount	object	The fresh refund fee charged to this destination merchant. Null until computed.
splitSettlements[].netAmount	object	Total debited from this destination merchant (amount plus feeAmount). Null until computed.
primarySettlement	object	The client's own portion: amount (gross, always present), feeAmount, and netAmount (total debited).
feeAmount	object	Aggregate fresh refund fee across all beneficiaries. Null until computed.
netAmount	object	Aggregate total debited across all beneficiaries (amount plus feeAmount). Null until computed.

As on the charge side, feeAmount and netAmount are null until fees are computed (while the refund is still pending), never zero.

Query the refund breakdown on the CardRefundTransaction node. The query projects the same settlement fields as the charge side. While the refund is pending, feeAmount and netAmount read null and populate once the fee calculation completes:

Rules

note

• Cumulative cap: cumulative refunds cannot exceed the original transaction amount. A refund that would breach this fails with exceedsOriginalAmount, the same rule that applies to any card refund (see Refunds).
• Partials allowed: a transaction may be refunded across multiple partial refunds, each apportioned pro-rata by gross share of the original.
• Final refund settles the remainder: the refund that brings a split to 100% settles whatever gross remains per beneficiary, rather than re-computing pro-rata. A sequence of partials therefore always reconciles to the original with no rounding drift. Any sub-cent residual lands on the primary.
• Fee and net null until computed: feeAmount and netAmount read null until fees are computed, never zero, matching the charge-side contract.

Worked Examples

Both examples use the canonical transaction: R400.00 charge with one R120.00 split to a destination merchant (primary remainder R280.00). These are the same amounts as the charge-side worked example, so you can line the refund up against the charge you already understand. Each beneficiary is also charged a fresh refund fee, netted off its settlement; the fee amounts are not shown here.

Full Refund

Refund the full R400.00. Each beneficiary returns its full gross share to the cardholder:

Beneficiary	gross returned
Primary	280.00
Split merchant	120.00
Customer receives	400.00

280.00 + 120.00 = 400.00, the full original, returned to the cardholder.

Partial Refunds

Two partials, demonstrating the cumulative cap, pro-rata apportionment, and the "final refund settles whatever remains" rule. Same canonical transaction (primary 280.00 / split 120.00). Refund R100.00, then refund the remaining R300.00.

Partial 1, refund R100.00, apportioned pro-rata (primary 70%, split 30%):

Beneficiary	gross returned
Primary	70.00
Split merchant	30.00
Customer receives	100.00

Partial 2 (final), refund the remaining R300.00. This brings the cumulative refund to R400.00 (100%), so it settles whatever gross remains per beneficiary (primary 280.00 - 70.00 = 210.00, split 120.00 - 30.00 = 90.00) rather than re-deriving pro-rata:

Beneficiary	gross returned
Primary	210.00
Split merchant	90.00
Customer receives	300.00

Cumulative reconciliation to state after the sequence:

• Customer received 100.00 + 300.00 = 400.00 (the full original).
• Primary gross returned 70.00 + 210.00 = 280.00; split 30.00 + 90.00 = 120.00 (each equals its original gross).