Skip to content
FluxusDocs
Fluxus DocumentationFluxus Documentation

Atomic Split Payments

Atomic split paymentsAtomic split payments

When a customer pays through the POS terminal, Fluxus can split the payment into up to three simultaneous transfers: one to the merchant, one to a tax wallet, and one to a tip wallet. All three happen in a single on-chain batch. If any leg fails, the entire payment reverts.

How the split is calculated

The customer pays the full amount. Before the payment is submitted, the app computes how that amount divides across recipients. Tax and tip are each a percentage of the total. The merchant receives whatever remains after both deductions.

All amounts use 6-decimal precision (pathUSD is a TIP-20 token with 6 decimals). Integer division floors any fractional unit, and the rounding remainder stays with the merchant.

Example: 10.00 pathUSD, 8.25% tax, 10% tip

Total raw: 10_000_000 (10.000000 pathUSD)

Tax (8.25%): 825_000 ( 0.825000 pathUSD)

Tip (10%): 1_000_000 ( 1.000000 pathUSD)

Merchant: 8_175_000 ( 8.175000 pathUSD)

Tax and tip together cannot exceed 99% of the total. The split configuration is rejected at save time if they do.

Configuring the split in POS settings

Open /app/pos/settings and enable the Split Payment Configuration checkbox. Four fields appear:

  • Tax %. The percentage of each payment routed to the tax wallet. Set to 0 to skip tax collection.
  • Tax wallet. A valid EVM address that receives the tax portion. Required when Tax % is greater than 0.
  • Tip %. The percentage routed to the tip wallet. Set to 0 to disable tipping.
  • Tip wallet. The address that receives tips. Required when Tip % is greater than 0.

A live Net to merchant readout shows the remaining percentage as you adjust the fields. Save the configuration before generating a payment QR code.

Atomic batch execution

When a customer opens the payment link and clicks pay, the app uses Tempo batch calls to submit all transfers in a single transaction. This means:

  • All three wallets (merchant, tax, tip) receive their amounts in the same block.
  • If any transfer in the batch fails (for example, insufficient balance), the whole transaction reverts. No partial payment is possible.
  • The merchant always receives at least the split remainder. The math guarantees merchantAmount + taxAmount + tipAmount = totalAmount with no rounding loss.

The customer sees a split breakdown on the payment page before confirming, showing exactly how many pathUSD go to each recipient.

QR code URL encoding

When split is enabled, the POS QR code URL includes extra parameters that the payment page reads to reconstruct the split configuration:

  • split=1 signals that a split payment is expected.
  • taxPct sets the tax percentage (for example, taxPct=8.25).
  • taxWallet sets the tax recipient address.
  • tipPct sets the tip percentage.
  • tipWallet sets the tip recipient address.

These parameters are validated on the payment page before the batch is submitted. Invalid addresses or percentages that exceed 99% are rejected.

Testnet note: All amounts are in pathUSD (6 decimals) on the Tempo Moderato Testnet. Use the testnet faucet to fund your wallet before testing split payments end-to-end.