Split payment fees

Merchants can choose SPLIT alongside MERCHANT and PAYEE. Set buyerFeeShareBps to the buyer's percentage share of total fees, including quote costs (5000 basis points = 50%). The share applies to fiat, Apple Pay, and crypto and is snapshotted on each order. Quoted costs include exchange-rate spread and bridge costs; the final settlement can still vary with execution or slippage.

The dashboard provides a 0–100% step slider and number input in payment settings, in increments of 10%. Ratios are always buyer:merchant: 0:100 means the merchant pays all fees, 30:70 means the buyer pays 30%, and 100:0 means the buyer pays all fees. The number input accepts the same 10% increments.

peer-pay-cli merchant settings --fee-payer SPLIT --buyer-fee-share-bps 3000
peer-pay-cli orders create --amount 100 --fee-payer SPLIT --buyer-fee-share-bps 5000

Omit both order overrides to inherit the merchant configuration. Explicit SPLIT order overrides require buyerFeeShareBps. Valid values are integer basis points from 0 to 10000 in steps of 1000.

A 50:50 split shares the cost equally. If the quoted total cost is $10 for a $100 order, the buyer pays $105 and the merchant receives $95. The final cost depends on the selected rail and quote; the share is a percentage of fees, not a surcharge percentage of the order amount.

Partial payments credit principal using (1 - s) * buyerPaidUSD + s * netSettlement, where s = buyerFeeShareBps / 10000. Apple Pay limits apply to the full buyer charge. Existing orders retain their original share after settings change. Local simulation uses the same pricing and settlement arithmetic as the hosted API.

For fiat SPLIT payments, the local CLI and hosted sandbox use the same deterministic maker spread, signal amount, and cent-rounded buyer charge. For example, a $100 Venmo order with a 50:50 split and a 10% referral fee has a sandbox maker rate of 0.9791 USD per USDC, a 106.433932 USDC signal, and a displayed buyer charge of $104.21. Partial CLI simulations scale the quoted fiat charge to the requested principal fraction, round down to cents, and credit the principal implied by the actual payment and net settlement. This also applies to non-USD fixture currencies.

For live fiat quotes with standard pricing, maxFeeConfig applies to all three fee payers, including PAYEE. New merchant configs still start at 20%; clearing an existing cap remains an explicit opt-out. Set a buyer-paid cap with:

peer-pay-cli merchant settings --fee-payer PAYEE --max-fee-mode flat --max-fee-percentage 20

Standard buyer-paid quotes can match a larger executable deposit while keeping merchant proceeds fixed. Peer collects the scheduled fee plus the remaining surplus; partner fee rates stay unchanged. The larger quote's actual buyer total, including spread, must fit the merchant's cap. For an 85 USDC order with a 9.25% scheduled fee and 20% cap, a fixed 100 USDC deposit at 1:1 charges $100, sends 85 USDC to the merchant, and collects 15 USDC in fees. A cheaper exact-size quote still wins within the merchant's release-flow preference. Fee rounding leaves any uncollectable dust with the merchant.

Normal buyer-paid discovery does not reduce the scheduled fee to fund a smaller release. Split quotes retain their Peer-funded shortfall buffer; merchant-paid quotes retain their merchant-funded buffer. Spread-inclusive (flat all-in) pricing retains its existing fee budget and 20-basis-point buffer. Explicitly clearing the cap disables the larger-deposit search and retains the legacy Peer-funded 0.2% buffer. The default maximum fee remains 20%, a separate setting. Ordinary quotes retain their additive fee-plus-spread cap; only the larger-deposit path checks the actual buyer total against the cap. See the full fee and buffer matrix.

Local simulation uses deterministic sandbox liquidity; it does not simulate live maker capacity or the live max-fee filter. Hosted commands use the API's rules.