Platby, refundace a výplaty
Hráč platí přímo za VIP přes GoPay, Stripe (karta, Apple/Google Pay) nebo PayPal. Jakmile poskytovatel platbu potvrdí, VIP se aktivuje, plugin dostane doručení a majiteli serveru se připíše výdělek (cena mínus poplatek provozovatele).
Principy, na kterých stojí bezpečnost peněz
Přesměrování z brány nic nedokazuje. Návratová stránka i webhooky jsou jen signál „něco se změnilo“. O stavu platby rozhoduje výhradně dotaz server–server na API poskytovatele. Webhooky Stripe a PayPal navíc ověřujeme podpisem; GoPay podpis nemá, proto se u něj z notifikace bere jen ID platby.
Každá platba se vypořádá právě jednou. Webhook, návratová stránka, reconciliace i ruční „zopakovat“ volají stejnou funkci; unikátní indexy v databázi zaručí, že se výdělek nepřipíše dvakrát, VIP neprodlouží dvakrát a nevznikne druhé doručení — ani při souběhu.
Peníze jsou v účetní knize, ne ve sloupci. Každý pohyb je nový řádek; starý řádek nelze upravit ani smazat (hlídá to databáze). Zůstatek majitele se pravidelně porovnává se součtem knihy.
Tok platby
1. Hráč vybere balíček, jméno a způsob platby → POST /api/orders
→ objednávka (PENDING) se snapshotem ceny, příkazů a poplatku
→ platba u poskytovatele (idempotentně podle našeho ID) → přesměrování
2. Hráč zaplatí na bráně
3. Webhook a/nebo návrat prohlížeče → dotaz na API poskytovatele
PAID → v jedné transakci: platba vypořádána, objednávka PAID,
výdělek majiteli, VIP prodlouženo, doručení GRANT do fronty
zrušeno / zamítnuto → objednávka CANCELLED (pozdní úspěšná platba ji stále vypořádá)
4. Plugin vyzvedne doručení, spustí příkazy, potvrdí → DELIVEREDDvojklik na „Zaplatit“ ani druhá záložka nevytvoří druhou placenou objednávku: každý pokus nese klíč, objednávka je unikátní podle uživatele a klíče a otevřený checkout se znovu použije.
Nastavení poskytovatelů (provozovatel)
GoPay
GOPAY_API_URL (produkce https://gate.gopay.cz/api, sandbox https://gw.sandbox.gopay.com/api), GOPAY_GOID, GOPAY_CLIENT_ID, GOPAY_CLIENT_SECRET. Notifikační URL <APP_URL>/api/webhooks/gopay se posílá s každou platbou. Refundace probíhá automaticky přes GoPay API.
Stripe
STRIPE_SECRET_KEY a STRIPE_WEBHOOK_SECRET. Ve Stripe dashboardu vytvoř webhook na <APP_URL>/api/webhooks/stripe s událostmi:
checkout.session.completed
checkout.session.async_payment_succeeded
checkout.session.async_payment_failed
checkout.session.expired
payment_intent.payment_failed
charge.refunded
refund.created refund.updated refund.failed
charge.dispute.created charge.dispute.updated charge.dispute.closed
charge.dispute.funds_withdrawn charge.dispute.funds_reinstatedPayPal
PAYPAL_ENV=live, PAYPAL_CLIENT_ID, PAYPAL_CLIENT_SECRET, PAYPAL_WEBHOOK_ID. Webhook na <APP_URL>/api/webhooks/paypal s událostmi:
CHECKOUT.ORDER.APPROVED
PAYMENT.CAPTURE.COMPLETED PAYMENT.CAPTURE.PENDING
PAYMENT.CAPTURE.DENIED PAYMENT.CAPTURE.REFUNDED PAYMENT.CAPTURE.REVERSED
CUSTOMER.DISPUTE.CREATED CUSTOMER.DISPUTE.UPDATED CUSTOMER.DISPUTE.RESOLVEDU PayPalu „schváleno“ ještě neznamená „zaplaceno“: peníze strhneme (capture) až na našem serveru a jen pokud je objednávka stále k zaplacení.
PAYMENTS_ALLOW_SANDBOX=true (jen pro staging). Admin může jednotlivé brány a celý checkout vypnout v Administrace → Konfigurace.Refundace
REQUESTED → PROCESSING → SUCCEEDED (nebo FAILED → zopakovat)
1. ověření (zaplaceno, v limitu dní, poskytovatel umí refund)
2. zámek objednávky, jeden refund na platbu (dvojklik nic nezdvojí)
3. volání poskytovatele s idempotenčním klíčem = ID refundace
4. uložení ID refundace poskytovatele
5. po POTVRZENÍ poskytovatelem: zápis REFUND do knihy (strhne podíl
majitele i poplatek), objednávka REFUNDED, VIP zkráceno o dobu
objednávky, REVOKE doručení, e-mail hráči, auditRefundaci spouští majitel (jen pokud jeho zůstatek pokryje stržení — jinak administrátor), administrátor, nebo automaticky systém, když se VIP nepodaří doručit ani po 5 pokusech. Když poskytovatel refundaci odmítne, objednávka zůstane v bezpečném stavu Vrací se (nic se nedoručuje), vznikne kritický alert a administrátor ji může zopakovat. Refundace provedená přímo v dashboardu poskytovatele nebo prohraný spor (chargeback) se zaúčtuje stejně. Částečné refundace z dashboardu se automaticky neúčtují — vznikne alert a rozhodne administrátor.
Když poskytovatel neodpoví jednoznačně (timeout, výpadek), refundace přejde do stavu nejasný výsledek (UNKNOWN). Před každým dalším pokusem se systém nejdřív zeptá poskytovatele, jestli refundace už neexistuje — peníze se tak nikdy nevrátí dvakrát. Refundaci nelze zahájit, dokud k platbě běží spor. Administrátor může automatické refundace dočasně pozastavit a nastavit denní limit (větší refundace pak vyžaduje ruční potvrzení).
Kdy jsou peníze k výplatě (držení a rezerva)
zaplaceno → ČEKÁ NA SPLATNOST (pending) po dobu držení (výchozí 7 dní)
splatnost → K VÝPLATĚ (available) mínus rolling rezerva (výchozí 0 %)
rezerva → REZERVA (reserve) uvolní se po 90 dnech do "K výplatě"
spor otevřen → VE SPORU (dispute) pozice objednávky zadržena do rozhodnutíDobu držení a rezervu určuje provozovatel podle rizikového profilu majitele (neověřený, základní, ověřený, omezený, pozastavený) a lze je nastavit i individuálně. Podmínky platné v okamžiku platby se u objednávky uloží — pozdější změna politiky už zaplacené objednávky neovlivní. Splatnost se odkládá, dokud k objednávce běží spor nebo ruční kontrola podezřelého nákupu. Přehled všech kapes vidíš v Majitel → Výdělky.
Spory (chargebacky)
otevřen (Stripe/PayPal webhook, GoPay ručně adminem)
→ pozice objednávky přesunuta do kapsy "Ve sporu" (DISPUTE_HOLD)
→ admin připraví důkazy (předvyplněno z objednávky, doručení, podmínek)
→ admin je VÝSLOVNĚ odešle poskytovateli (nic se neodesílá automaticky)
vyhráno → zadržená částka se vrací (DISPUTE_RELEASE)
prohráno → zaúčtováno jako refundace (DISPUTE_LOST), VIP odebráno;
poplatek za spor nese majitel jen pokud to provozovatel zapnulGoPay nemá API pro spory — oznámení o chargebacku od GoPay založí administrátor ručně a ručně zadá i výsledek. Částečně prohraný spor se automaticky neúčtuje: vznikne alert a rozhodne administrátor. Vysoký podíl sporů u majitele vyvolá alert a může vést k omezení jeho účtu.
Poplatky
Poplatek platformy = procento (bps) + volitelná pevná částka za objednávku; oba se ukládají k objednávce v okamžiku nákupu. Poplatek nikdy nepřesáhne cenu (balíček, u kterého by majiteli nic nezůstalo, nejde prodat). Poplatek platební brány si systém zjišťuje z API poskytovatele (Stripe, PayPal) nebo ho zadá administrátor (GoPay); slouží pro účetní reporty provozovatele a nemění výdělek majitele. Přepočty měn systém nedělá (viz níže).
Koruny a eura
Hráč může platit v Kč nebo v eurech. Majitel u produktu vyplní vlastní cenu v EUR (nepovinné) — nikdy se nepočítá z korun. Obchod pak ukáže přepínač Kč / € a v eurech prodává jen produkty s EUR cenou. Každá objednávka je celá v jedné měně: cena, platba, poplatek, účetní kniha, refundace, spory i doklad.
Majitel má dva oddělené zůstatky (Kč a EUR) se stejnými kapsami (ochranná lhůta, k výplatě, rezerva, spory) a vybírá je zvlášť; výdělek v EUR jde jen bankovním převodem. Pevná část poplatku za EUR prodej (defaultFeeFixedEurMinor) a minimální výplata v EUR (minPayoutAmountEur) se nastavují v administraci. Limity útraty a výplat (konfigurované v Kč) se pro eura přepočtou konzervativním koeficientem 1 : 25 — jde jen o kontrolu rizika, ne o přepočet peněz. Slevové kupóny na pevnou částku nebo s minimální útratou platí jen pro platby v Kč; procentní kupóny platí v obou měnách. Rekonciliace kontroluje každou měnu zvlášť.
Výplaty majitelům
žádost → RESERVED částka hned odečtena z dostupného zůstatku (PAYOUT_HOLD)
schválení → APPROVED (admin, nikdy vlastní výplatu)
připsání → PROCESSING kredit: volání fakturace BlazeHost s idempotenčním klíčem
účet: admin pošle převod a zadá jeho referenci
potvrzení → COMPLETED PAYOUT_RELEASE + PAYOUT, uložena reference transakce
zamítnutí / zrušení → rezervace se vrací (PAYOUT_RELEASE)
selhání → FAILED peníze zůstávají rezervované, admin zopakuje nebo zrušíVýplata je dokončená až po potvrzení fakturačním systémem, u bankovního převodu když administrátor zadá referenci odeslané platby. Na nově zadaný bankovní účet se první 72 hodin nevyplácí. Timeout se nepovažuje za selhání ani za úspěch: systém se nejdřív zeptá, zda připsání proběhlo. Výplaty zablokuje automatické finanční zmrazení při nesouladu účetní knihy, ruční zmrazení všech výplat nebo zmrazení konkrétního majitele.