Case notes: solving Split payment API for a real merchant

The problem a split payment API solves

A split payment API addresses a common shape of problem: one customer pays once, but the money needs to reach more than one recipient. A marketplace takes a platform fee and pays a seller. A booking site collects for a venue and a service provider. A group purchase divides a bill.

These case notes describe how we approach a split payment API at Flux, written as a general pattern rather than a claim about a specific client, with no invented numbers or outcomes. The goal is to show the reasoning, so you can judge whether it fits your case.

The scenario, kept generic

Picture a merchant who runs a platform connecting customers to independent providers. When a customer pays, the merchant keeps a fee and the rest belongs to the provider who did the work. The merchant does not want to hold funds longer than necessary, wants the provider paid quickly, and does not want to become a card vault or a compliance liability in the process.

That set of constraints, collect once, split by rule, pay out fast, stay out of PCI scope, is the frame we start from. Naming the constraints up front keeps the design honest.

How we approach the money flow

We separate the problem into two halves: collection and disbursement. Collection uses the tools covered elsewhere. The customer pays through Flux's hosted fields, the card is tokenized so it never touches the merchant's servers, and the charge is created through the REST API.

Treating collection as a solved, isolated step keeps the split logic from getting tangled up with card handling, which is exactly the tangle that creates compliance headaches.

Collecting once, disbursing many

With funds collected, the split is a matter of applying the merchant's rules and then moving money to each recipient. This is where instant payouts help. Flux supports push-to-card payouts via Visa Direct, so once the split is calculated the merchant can send each recipient their share to a debit card rather than making them wait on a slower cycle.

The pattern we favor keeps the split calculation in the merchant's own system, where the business rules live, and uses the payout capability purely to execute the transfers the rules produce.

Timing, webhooks, and reconciliation

The subtlety in any split is timing. You generally do not want to pay out a recipient's share before the incoming payment is actually settled, or a reversal later can leave you short. We lean on webhooks to gate disbursement on confirmed collection: the successful-charge event is the trigger to release the corresponding payouts.

We also keep a clear internal record linking each incoming charge to the outgoing payouts it funded, so reconciliation is straightforward and a dispute can be traced end to end. Settlement timing differs by rail, so we make those expectations explicit up front.

What we tell merchants to decide first

Before writing code, we push merchants to nail down the rules. Who are the recipients, and how is each one's share calculated? What happens on a refund or a partial refund after payouts have gone out? Who bears the fee? What is the policy if a recipient's payout destination is invalid?

A split payment API is mostly the encoding of business rules, and the technical pieces, hosted fields, tokenization, the REST API, webhooks, and push-to-card payouts, are the reliable parts. The decisions above are where a split succeeds or fails, so we settle them before we build.