Payments, Commission & Payouts

Payments & Payouts

Financial transactions are securely processed through Yoco (the default) or PayFast (used specifically when a customer chooses to save their card for future payments — Yoco has no card-vaulting capability).

Transaction Flow

When a user completes a purchase through Yoco (the default, no “save my card” option chosen):

• The system creates a YocoTransaction record and a unique checkout session.
• The user is redirected to Yoco's hosted payment page.
• After payment, Yoco sends a webhook to /yoco/webhook (CSRF‑exempt).
• The webhook handler verifies the HMAC signature, checks for replay attacks (via timestamp), and atomically claims the event_id to ensure idempotency.
• Upon success, the order is fulfilled (tickets issued, rental confirmed, etc.) and the organizer/lessor's account is credited.

Important: Amounts are stored in cents in the database and cast to a Money value object via MoneyCast. Always use ->amount->toRands() or ->amount->toCents() when reading or processing.

PayFast & Saved Cards

Ticking “Save my card for future payments” at checkout routes that purchase through PayFast instead of Yoco. PayFast is a signed form-post redirect rather than a JSON API — the browser is auto-submitted to PayFast's hosted payment page, and confirmation arrives via a server-to-server ITN (Instant Transaction Notification) to /payfast/notify, verified by both a signature check and a second postback confirming the payload genuinely came from PayFast. On success, PayFast returns a tokenized reference for the card, stored as a PaymentMethod (token encrypted at rest — this app never sees or stores the full card number). Customers manage their saved cards from Dashboard → Profile → Payment Methods. PayFast/save-card is now offered on most checkout flows (tickets, equipment rental deposit/balance/group deposit, venue room booking, venue space/table reservation, and provider service bookings); a handful of flows — Request for Quote and waiting-list-offer payments in Provider Bookings among them — still use Yoco only.

Platform Commission Rates

Commissions are automatically deducted. The rate is resolved at runtime:

• Events (Ticket/Stall): 5%
• Event Bookings (Spot booking): 5%
• Venue Bookings: 8%
• Equipment Rentals: 10%
• Artist Bookings: 10%
• Stall Bookings: 7%
• Cooler Box Orders: 5.5%
• Provider Bookings: 7.5% — charged only on the booking fee actually collected, never on a service's full listed price

Rates can be overridden for specific users by a ROOT admin via PersonCommissionRate, and globally by the commission_rates table. All changes require a signed confirmation link.

Bundled purchases: a cooler box entry bought together with a ticket pays only the ticket commission, not a separate Cooler Box rate. A vendor paying for their stall booking together with required employee tickets (and optionally cooler box entries for those staff) in one checkout pays no Stall Bookings commission at all on that booking — only the ticket commission, plus the Cooler Box rate if cooler box was included too.

Refunds

From Dashboard → Events → an event → Insights tab → Ticket Orders, the event's organizer (or a ROOT/SIRE/MANAGER admin) can refund any paid ticket order — partial or full — within a 30-day window from the payment date. A partial amount is validated against the remaining refundable balance (the original payment minus any refunds already issued). Refunds are tracked via YocoRefund or PayFastRefund records depending on which gateway took the payment, and require a reason for the audit trail.

Payouts

Payouts are initiated by a ROOT admin. Recipients must have their Banking Details submitted and verified. Payouts are tracked with AccountPayout records and can be confirmed by the recipient after they receive the funds.

Banking approval also gates publishing: you can't publish an event, an equipment listing, a merchandise product, or make a venue available for booking until at least one of your Banking Details records has been approved by a ROOT admin — not just submitted. This makes sure a payout destination already exists before anything you publish can start earning money.

Settlements & Chargebacks — Why a Payout Can Be Delayed

Before we can pay you out, our payment gateway (Yoco or PayFast) first has to settle the money to the platform's own bank account — that's a separate step from you paying commission-free into your balance. Most of the time this happens on schedule, but either gateway can delay, withhold, or hold funds in a Reserve Account instead of settling normally, for reasons entirely outside the platform's control:

• compliance or verification checks (e.g. FICA) still outstanding on the platform's merchant account;
• suspected fraudulent, illegal, or unauthorised activity on a transaction;
• a chargeback or dispute pending on a transaction; or
• a requirement from a banking partner, card association, or regulator.

If this happens on a transaction feeding your balance, your payout for it may take longer than usual — it isn't the platform sitting on your money. If you have Financial Access, the Refund Window badge on Financial Reports gives visibility into settlement state per transaction (see docs/REFUND_POLICY.md §6).

Chargebacks are a shared risk. Both gateways set a threshold for how many chargebacks the platform can incur before acting — if that threshold is exceeded, the gateway can require additional reserves, adjust settlement terms, or in the worst case suspend the platform's ability to process payments at all, which would affect every provider, not just the one behind the chargebacks. This is why responding quickly to a chargeback and delivering what you sold matters beyond your own transaction — see docs/REFUND_POLICY.md §4 and §9.3 for the full policy.

If a chargeback lands on one of your transactions, an admin records it against your account (Dashboard → Finance → Chargebacks) — you're notified in-app and by email, and the amount is deducted from your balance immediately, the same way an ordinary refund is. Because a payout can never exceed your current balance, this means it's automatically reflected in whatever your next payout turns out to be — there's no extra step on your end. If the platform later disputes and wins the chargeback, the deduction is reversed in full; if it's lost, it stands. See docs/REFUND_POLICY.md §4.5.