Split payments define how an operation’s value is allocated among participants, such as a seller and platform. That allocation must be tracked through settlement, refunds, and actual payout. To operate safely, preserve the rule applied to the order, identify each recipient, and reconcile movements by operation. A correct sum at checkout does not yet prove that each participant received the amount due.
The problem emerges when product calls everything a split, engineering stores only the total amount, and finance has to explain a discrepancy days later. The sale may be captured, commission recognized in operational records, and payout still pending. Each statement describes a different stage.
This guide proposes an operating design connecting these stages. The numbers are entirely fictional; fee and refund policies were chosen to make the calculation reproducible. They do not represent any supplier’s pricing, results, or features.
What is the difference between split allocation, capture, settlement, and payout?
Split allocation determines who is entitled to each portion under the operation’s rule. Capture, in a card flow with separate authorization and capture, confirms that an authorized amount is moving forward for collection. Settlement describes fulfillment of financial obligations in the applicable flow. Payout is the transfer to the designated recipient, which may occur at another time and depend on its own conditions.
An order with two sellers may have one capture and several allocations. It may also have captures per shipment, where supported, each with its own allocation. Counting sellers therefore does not determine the number of captures. Using two instruments for a customer to complete a purchase is a different design, often called split tender.
The ledger records the financial history of these operations. It can explain portions, obligations, costs, and adjustments, but an internal entry does not itself execute an external transfer. This distinction prevents an amount that exists only as an expectation from being shown as received.
In the application, maintain payment state, allocation state, and payout state separately. For more on payment transitions, see the guide to authorization, capture, reversal, and refund. A single label such as completed removes information the operation needs.
Who participates, and who takes each responsibility?
Before the API, map the relationship among buyer, seller, platform, and payment service providers. Identify who sells to the buyer, who onboards the recipient, who receives the financial instruction, and who is responsible for fees, refunds, and disputes. A platform’s commercial name does not answer these questions.
The Central Bank explains that marketplaces may also act as sub-acquirers in certain models, while other sales relationships fall under a different classification. The role actually performed matters for classification, according to the centralized settlement FAQ, in its marketplace question (opens in a new tab ↗), consulted on October 22, 2026. A split field in the integration does not replace that analysis.
Turn approved responsibilities into verifiable rules: who bears the original fee, who bears the refund, who covers insufficient funds, and who receives any adjustment. Also record who may change these rules and from which operation the change applies. Development implements the model validated for that business; it must not infer legal obligations from a percentage.
The article on gateways, PSPs, acquirers, and sub-acquirers helps organize these technical roles. Choosing an integration requires confirming which functions each contracted party actually performs.
When is the allocation sent to the provider?
The answer depends on the product, method, and capture flow. Determine whether the allocation is supplied at authorization, at capture, through a previously registered configuration, or through another documented resource. Also verify how to correct an instruction and what happens when it is missing or invalid.
As a specific example, Adyen’s transaction splitting documentation (opens in a new tab ↗), consulted on October 22, 2026, describes allocation instructions for payment, capture, and refund operations. This illustrates why an integration must understand each operation’s semantics. It does not mean every PSP accepts the same payload or offers the same combination of features.
In this guide’s proposed design, each order retains a version of the allocation rule. The submitted instruction must be traceable to that version and the amount of that capture. If the order changes before capture, produce a new authorized revision and preserve the previous one for auditing.
A change in today’s commission must not silently recalculate yesterday’s sale. Nor is recording that a request was sent enough: track confirmation and investigate rejections or allocation discrepancies. The application must distinguish a calculated rule, an accepted instruction, and a confirmed movement.
What must the allocation contract include?
Start with the calculation basis: item prices, shipping, discounts, commission, and fees are not interchangeable. Define which components belong to each participant and in what order calculations run. A platform-funded discount may have a different effect from a seller-funded discount.
Associate each portion with an internal identity, the correct recipient, currency, amount, and external operation reference where available. Preserve the rounding rule and policy version. Avoid identifying recipients solely by display name, which may change and is not a reliable financial key.
Use exact monetary amounts, such as integer minor units, and distribute any residual cents using a deterministic, approved criterion. The portions must sum to the amount defined for that stage. Do not hide an extra cent in commission without recording the rule that assigned it.
This structure must also represent what has not yet happened. One calculated portion may await confirmation; another may be reserved for a refund. Separating these amounts prevents the same available funds from financing two concurrent outflows. Visible balance, balance eligible for payout, and money already transferred should have distinct product definitions.
Fictional example: how do you split a R$200 order?
Consider a R$200 order with no shipping or discount, involving only one seller and the platform. The commission chosen for the example is 10% of the gross amount: R$20. The fictional processing fee is 3% of the same R$200: R$6. Under this imaginary contract, the platform bears the full fee.
The seller’s portion is R$180, calculated as R$200 less R$20 commission. The platform has R$20 gross commission and R$14 after the R$6 cost. The aggregate net amount is R$194, matching the seller’s R$180 plus the platform’s R$14. No payout has occurred yet.
Notice the basis: deducting R$6 before calculating commission would produce a different agreement. Applying 10% to R$194 would yield R$19.40, inconsistent with the chosen policy. The interface should therefore explain where each number comes from rather than showing only a percentage and a net amount.
The example excludes taxes, early settlement, installments, foreign exchange, reserves, and other expenses. These exclusions define the calculation’s scope. If any component exists in the real operation, it must enter as an identified movement with a designated owner, rather than being absorbed into an unexplained closing difference.
How do you record the example in the operational ledger?
One possible model records, upon confirmed capture, R$200 receivable from the processor, a R$180 obligation to the seller, and R$20 in platform commission. The fee adds R$6 in expense and reduces the receivable by R$6. The expected amount from the processor becomes R$194.
In entry terms, the first entry debits the operational receivable by R$200 and credits the seller obligation by R$180 and commission by R$20. The second debits expense by R$6 and credits the receivable by R$6. This is an educational proposal for operational control, to be adapted to the company’s validated model; it is not an official chart of accounts or proof of legal ownership of funds.
When settlement occurs, the movement should clear the corresponding receivable and recognize the confirmed financial position. Do not generate another R$200 in revenue when importing the file: it confirms or differs from the fact already expected. The reference must connect the records.
Preserve capture, fee, and settlement as distinct facts. If the expected fee was R$6 and the report shows another amount, open an identified discrepancy. The payment ledger guide explores the relationship among transaction, entry, and balance without requiring a mutable column for every situation.
How does a R$50 partial refund work?
Continue the example with no prior payout. The customer receives a R$50 refund. The fictional policy states that commission reverses proportionally to the refunded amount and the original R$6 fee is not returned. This is an assumption for the scenario, not a universal processing rule.
R$50 is 25% of the order. The seller bears R$45, and the platform reverses R$5 in commission. R$135 remains for the seller, R$15 in gross commission, and R$9 for the platform after the original fee. The remaining aggregate is R$144: R$194 less R$50, or R$135 plus R$9.
In operational records, the reversal reduces the obligation to the seller by R$45 and commission by R$5, with a R$50 offset in the financial position corresponding to the refund stage. If the amount has not yet settled, the receivable may be the offset; if it has, the model must represent the outflow or refund obligation in the correct place.
Adyen’s split refund documentation (opens in a new tab ↗) illustrates dedicated instructions and method-specific limitations. Consult the rules of your provider: do not assume a partial refund automatically repeats the original payment’s proportions.
What if the refund corresponds to a specific item?
In a cart with multiple sellers, refunding 25% of the total does not mean debiting 25% from each recipient. If only one item was returned, the reversal must follow that item’s relationship to its seller, commission, discount, and any shipping. The policy must decide how to handle shared components.
Store the original allocation by item or by a commercial unit appropriate to the business. The refund can then point to the portion it reverses. If the system retained only the cart’s final percentage, safely reconstructing who should bear the refund may be impossible.
Also control the amount still eligible for refund. Requests already processing may consume part of that limit, depending on the design and provider restrictions. Two teams cannot simultaneously release the same refundable balance based on stale reads.
In the R$200 scenario, R$45 and R$5 are correct only because we chose one seller and proportional commission reversal. If commission included a nonreversible fixed component, the calculation would change. Support must be able to explain that difference using the original operation’s policy, without retroactively applying a newly edited rule.
What changes if the seller has already received a payout?
Now open a separate branch of the example: before the R$50 refund, the platform had already transferred R$100 to the seller. Its remaining obligation to the seller was R$80. With the R$45 reversal, that obligation falls to R$35. The platform’s net portion remains R$9 under the earlier assumptions.
The remaining aggregate position totals R$44: R$194 less the R$100 payout less the R$50 refund. That R$44 corresponds to R$35 still owed to the seller plus the platform’s R$9. The earlier payout has not disappeared and cannot be subtracted again when calculating the balance.
If the amount to reverse exceeds the obligation still outstanding, the design must represent the exposure and the contractually agreed recovery mechanism. Changing a balance in the database does not bring back money already in the seller’s account. A future offset must also be identified and reconciled.
In another branch, with no prior payout, a full R$200 refund would leave the R$6 cost with the platform, assuming the fee is not returned. The difference requires coverage; it does not authorize creating revenue or arbitrarily reducing the customer’s refund.
How do chargebacks and reserves fit into the allocation?
A dispute requires its own trail, linked to the payment and items involved. A voluntary refund policy does not automatically determine chargeback responsibility. Define with business owners how evidence, debits, possible reversals, and fees will be handled under the actual contract.
In the system, separate dispute opening, an operational hold or reserve, and a confirmed financial debit. A reserve reduces availability as defined by the product; it does not necessarily mean money has left. Mixing these events can deduct the same exposure from the seller twice.
There may also be a prior refund on the disputed payment. Link references and verify external movements before recognizing another final loss. The goal is not to ignore the second event but to explain whether it is a new obligation, a provisional stage, or a discrepancy to challenge.
The guide to chargebacks, disputes, and evidence explores that lifecycle. Here, the architectural requirement is to preserve the relationship between the case and its financial portions. A favorable reversal must offset the appropriate movements without erasing history or releasing a payout before the required confirmation.
How do you reconcile the order, allocation, settlement, and payout?
Use a trail that takes you from the order to each capture, portion, fee, refund, and transfer. Then reverse the path: every external movement must map to an internal operation or an investigable exception. Matching amount and date alone is not sufficient identification.
Reconciliation must distinguish expectation from confirmation. In the example, R$194 was the expected net amount before the refund. The report may show capture, fee, and refund in different records or periods. Comparing only the bank deposit against the day’s sales mixes stages and produces false alarms.
As a concrete report reference, Adyen’s Balance Platform Accounting Report (opens in a new tab ↗) describes balance changes, transfers, payouts, and costs. Fields and frequency are specific to that provider; the application must map the documents actually available in its flow.
Investigate differences by recipient and operation before closing the aggregate. A positive error in one account may numerically offset a negative error in another and hide both. The payment reconciliation roadmap organizes the progression from sale to financial confirmation and the handling of these exceptions.
How do you handle failures, repeated events, and concurrency?
A payout request that times out has an unknown outcome until evidence resolves the uncertainty. Do not send another transfer with a different identity just because the first response was lost. Preserve the intent, any available external reference, and the amount reservation while the operation remains indeterminate.
One safe execution proposal links each financial operation to a stable identity and publishes its internal effects atomically. Reprocessing the same confirmation should retrieve the previous result without creating another commission, obligation, or transfer. Different events for the same operation must remain distinguishable when they represent different legitimate effects.
For concurrency, consider two processes trying to release a payout while another reserves a refund. They cannot both consume the same available funds. Make the decision and reservation within an appropriate transactional boundary, with constraints that remain valid after a process failure.
Out-of-order events require similar care. An old notification must not undo a later confirmation simply because it arrives last. Retain the evidence and apply transitions compatible with the documented lifecycle. When external data conflicts, create a traceable exception and suspend the action dependent on confirmation.
How do you investigate a portion assigned to the wrong recipient?
Consider another fictional incident, independent of the preceding calculations: the order and settled total are correct, but a portion was assigned to the wrong seller. First preserve the original instruction, rule version, and confirmed references. Compare the account record the order should have used with the recipient actually specified and the external movement.
If the error is only in the internal report’s association, correct that association auditably without inventing a transfer. If the external allocation is wrong, resolution depends on an operation documented and permitted at that stage. An internal compensating entry can explain the obligation but does not prove that funds changed recipients at the provider.
During investigation, flag the affected amount and suspend the payout that depends on that confirmation, according to the approved operational control. Avoid indefinitely blocking amounts unrelated to the problem. Record an owner, hypothesis, required evidence, and closure condition.
Closure requires demonstrating both the internal adjustment and its external effect, where applicable. Then test the cause: reused account data, a swapped reference, an old rule, or a correlation error. A global sum that still balances does not close this incident, because each participant’s entitlement may still be represented incorrectly.
What should you test before releasing the operation?
Turn the example into value-conservation tests. Confirm R$200 gross, a R$6 fee, R$180 for the seller, and R$14 net for the platform. After the R$50 refund, confirm R$135 and R$9. In the branch with a prior R$100 payout, confirm R$35 and R$9, totaling R$44.
Test fixed commission, percentage commission, discounts by sponsor, carts with multiple sellers, and residual cents separately. In each scenario, the sum must match the corresponding basis. Do not reuse an expected response that assumes proportionality in an item-based refund case.
In failure tests, interrupt the process between reservation and submission, between submission and response, and between confirmation and local persistence. Redeliver events, change their order, and force two concurrent actions. The expected result must state which movements exist, which await confirmation, and which actions are blocked.
Finish with a reproducible close based on the available external reports. Product and finance must be able to explain a seller’s statement, including refunds after payout. The operation is ready to advance when that explanation can point to concrete rules, references, and movements without depending on a manual balance edit to make the numbers match.