Přeskočit na obsah

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

text
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í → DELIVERED

Dvojklik 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:

Stripe events
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_reinstated

PayPal

PAYPAL_ENV=live, PAYPAL_CLIENT_ID, PAYPAL_CLIENT_SECRET, PAYPAL_WEBHOOK_ID. Webhook na <APP_URL>/api/webhooks/paypal s událostmi:

PayPal events
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.RESOLVED

U 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í.

Neúplně nastavená brána aplikaci neshodí: jen se vypne, v logu je varování a checkout ji nenabídne (důvod uvidí admin v Administrace → Systém). Sandbox/testovací klíče v produkci brána nepřijme, pokud výslovně nenastavíš PAYMENTS_ALLOW_SANDBOX=true (jen pro staging). Admin může jednotlivé brány a celý checkout vypnout v Administrace → Konfigurace.

Refundace

text
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, audit

Refundaci 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)

text
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)

text
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 zapnul

GoPay 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

text
žá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.