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.

Gateway Outages & System Status

Sometimes Yoco or PayFast themselves have an outage, degraded performance, or scheduled maintenance. The platform watches both gateways' official status feeds continuously and shows the live state on the System Status page (linked in the site footer). While a gateway is down, new checkouts through it are paused automatically: if Yoco is down you'll be asked to tick “Save my card for future payments” to pay via PayFast instead, and if PayFast is down you'll be asked to leave it unticked to pay via Yoco. Only outages touching online card checkout count — a Yoco till/POS problem or a single bank's Instant EFT wobble on PayFast never blocks card payments here.

The same page also shows SMSPortal, the provider behind the platform's text messages (booking confirmations, reminders, and the SMS you send from Dashboard → SMS), whenever the SMS service is switched on. Only problems that affect us count — its REST API, outbound or inbound SMS, or the Africa region. While it reports a problem, the SMS pages in your dashboard show a warning that messages may be delayed or fail to deliver; sending is not blocked, and payments are never affected.

Bring Your Own Keys & Requesting a New Gateway

On the Pro — Bring Your Own Keys subscription (Dashboard → Billing → Subscriptions) you connect your own Yoco and/or PayFast keys from Dashboard → Billing → Payment Gateways. Buyers then pay straight into your gateway account and you keep 100% (0% commission) — only the flat monthly subscription applies. Keys are encrypted at rest and only masked hints are ever shown. Until at least one gateway is connected and verified, checkouts still go through the platform's keys at the fallback rate.

How much has actually settled straight into your own account is shown on your dashboard (“Processed via your own keys”) and on the Subscriptions page; a ROOT/admin with Financial Access sees the platform-wide split between own-keys and platform-processed volume on Financial Reports.

If you use a different payment gateway (for example Ozow, SnapScan, Peach Payments, Stripe, or DPO), you can request an integration from the same Payment Gateways page: give the gateway name, its website, and anything we should know. Your open requests and their review status (pending, under review, approved, declined) are listed there, and you can withdraw an open request at any time. Approved integrations are announced by the platform team once they ship.

Subscription Billing & Invoices

A paid subscription plan (Growth or Pro — Bring Your Own Keys) is billed automatically every month through PayFast's recurring billing feature — you approve it once at signup, and PayFast itself re-charges the same card each month; nothing further to do on your side. Every successful charge (the first one and every monthly renewal) automatically generates a tax invoice that's emailed to you as a PDF attachment and also kept on Dashboard → Billing → Subscriptions, where you can download any past invoice at any time. Cancelling (Dashboard → Billing → Subscriptions → Cancel) or choosing a lower/free plan from the plans list both stop PayFast from billing you again immediately, but you keep your current plan's benefits (commission rate, BYO access) until the end of the period you've already paid for — your account only moves to the new plan (or the free Starter plan) once that day arrives, never before.

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 your banking account (Profile → Banking) has been approved by a ROOT admin — not just submitted. You keep exactly one banking account on file; editing its verified details sends it back for re-verification. 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.