Nastavenie Stripe

Po dokončení tohto návodu budete mať fungujúci účet Stripe, dve sady kľúčov API (test + ostrý), endpointy webhookov v oboch prostrediach smerujúce na váš účet Cabintale a budete vedieť, ako celý postup lokálne otestovať so Stripe CLI skôr, než pôjdete naostro.

Stripe je len spracovateľ platieb – ceny určujete vy

Cabintale vo Stripe žiadne produkty vopred nevytvára. Každá relácia Checkout sa zostaví na mieste presne so sumou, ktorú rezervácia vypočíta (noci × sadzba, výška zálohy, doplatok, čokoľvek). Vo Stripe nemusíte nastavovať katalóg produktov; nepotrebujete pevné ceny.

Čo vám Stripe dáva:

• Hostovanú stránku pokladne, ktorá prijíma karty (a ďalšie spôsoby, ktoré zapnete) v jazyku a mene hosťa
• Udalosti webhooku, ktoré Cabintale oznamujú, keď platba uspeje, zlyhá alebo vyprší
• Dashboard s podrobnosťami o vyrovnaní a sporoch (vrátenia platieb robíte priamo v Cabintale – pozrite Vrátenia platieb a storná)

To je všetko. Všetko ostatné rieši Cabintale.

Krok 1: Zaregistrujte sa v Stripe

Prejdite na stripe.com a vytvorte účet.

Môžete začať v testovacom režime bez aktivácie firmy – testovací režim umožňuje realistické postupy od začiatku do konca s testovacími kartami (žiadne skutočné peniaze). Keď budete pripravení prijímať skutočné platby, budete musieť účet aktivovať (zadať bankové údaje, údaje o firme, doklad totožnosti).

Krok 2: Zapnite testovací režim

Vpravo hore v Stripe Dashboarde → prepnite „Test mode“ (prepínač sandboxu/vývoja).

Keď je prepínač zapnutý:

• Všetky kľúče API, webhooky, zákazníci, platby a dashboardy sú oddelené od ostrých údajov
• Testovacie karty fungujú; skutočné karty sa odmietnu
• Môžete slobodne všetko pokaziť

Keď je prepínač vypnutý, pozeráte sa na ostré prostredie – rovnaké rozhranie, oddelené údaje.

Test a Ostrý režim sú úplne oddelené. Iné kľúče, iné endpointy webhookov, iné podpisové kľúče, iní zákazníci, iné platby. Nič sa neprenáša. Každý nastavíte raz.

Krok 3: Nájdite svoje kľúče API

V Stripe Dashboarde → Developers (ľavé menu) → API keys.

Uvidíte:

• Publishable key – začína pk_test_… (test) alebo pk_live_… (ostrý). Dá sa bezpečne zdieľať.
• Secret key – začína sk_test_… / sk_live_…. Kliknutím na Reveal test key ho zobrazíte. Nikdy ho nezdieľajte; zaobchádzajte s ním ako s heslom.

Skopírujte oba. Vložte ich do okna Cabintale v zodpovedajúcom režime (momentálne vybraný testovací režim → vložte testovacie kľúče; prepnite na ostrý režim → vložte ostré kľúče).

Stripe niekedy ukáže tajný kľúč len raz. Ak sa to stane, kliknite na Reveal test key (test) alebo Reveal live key (ostrý), aby ste ho videli znova. Pri ostrom kľúči vás Stripe môže prinútiť poslať si kľúč e-mailom – skopírujte ho skôr, než okno zatvoríte.

Krok 4: Vytvorte cieľ udalostí (webhook)

Stripe premenoval webhooky na event destinations. V Stripe Dashboarde → Developers → Webhooks kliknite na Add destination. Otvorí sa trojkrokový sprievodca.

1. Select events

• Event destination scope – vyberte Your account.
• API version – nechajte predvolenú (napr. 2020-08-27).
• V časti Events pomocou vyhľadávacieho poľa nájdite a zaškrtnite týchto päť:
  • checkout.session.completed (kľúčové – označí rezervácie ako zaplatené)
  • checkout.session.expired (uvoľní dátumy, keď hostia platbu včas nedokončia)
  • payment_intent.succeeded (nadbytočná záchranná sieť)
  • payment_intent.payment_failed (označí zlyhané pokusy)
  • charge.refunded (synchronizuje vrátenia späť do Cabintale – vystavené z rozhrania Cabintale alebo zo Stripe Dashboardu, funguje oboje)
• Kliknite na Continue.

2. Choose destination type

Vyberte Webhook endpoint (nie Amazon EventBridge ani Azure Event Grid). Kliknite na Continue.

3. Configure destination

• Destination name – čokoľvek, čo spoznáte, napr. Cabintale production.
• Endpoint URL – vložte URL z časti „Naša URL webhooku“ v okne Cabintale. Vyzerá takto:

https://admin.cabintale.com/api/webhooks/stripe/abc123-def4-...

Táto URL je jedinečná pre váš účet Cabintale. Token na konci hovorí nášmu serveru, ku ktorému účtu udalosti patria.

• Description – voliteľné.
• Kliknite na Create destination.

Na stránke destinácie nájdite Signing secret (začína whsec_…), kliknutím na ikonu oka ho zobrazte a skopírujte.

Prepnite späť do okna Cabintale → vložte ho do Podpisový kľúč webhooku. Kliknite na Uložiť.

Staršie účty Stripe môžu ešte ukazovať klasické tlačidlo Add endpoint namiesto sprievodcu destináciou. Polia sú rovnaké – URL endpointu, udalosti, podpisový kľúč – len na jednej obrazovke.

Krok 5: Otestujte spojenie

Cabintale pri uložení spustí test spojenia automaticky (zavolá API Stripe s vaším tajným kľúčom). Výsledok sa zobrazí ako oznámenie navrchu /settings.

Kedykoľvek ho môžete otestovať znova kliknutím na Nastavenia na karte Stripe → otvorením okna → tlačidlom Otestovať spojenie vedľa panela uložených kľúčov.

Výsledok:

• Spojenie je v poriadku – zelený štítok, všetko je v poriadku
• Spojenie zlyhalo – červený štítok s chybovou správou Stripe; zvyčajne nesprávny tajný kľúč alebo nesprávny režim

Krok 6: Skúšobná rezervácia od začiatku do konca (testovací režim)

Nastavte ubytovanie na Prijímať platby – pozrite Prijímanie platieb pri ubytovaní. Použite kľúče Stripe v testovacom režime.

Potom:

1. Otvorte URL verejného widgetu (použite Zobraziť verejný widget na stránke úpravy widgetu)
2. Vyberte dátumy → Rezervovať
3. Vyplňte formulár → Zaplatiť
4. Stripe Checkout sa otvorí v novej karte
5. Použite testovaciu kartu:
   • Úspech: 4242 4242 4242 4242
   • Zamietnutie: 4000 0000 0000 0002
   • Vyžaduje sa overenie (3DS): 4000 0025 0000 3155
   • Ľubovoľná budúca expirácia, ľubovoľný 3-miestny CVC, ľubovoľné PSČ

1. Po platbe Stripe presmeruje na /payments/success (Cabintale)
2. Otvorte rezerváciu v administrácii → skontrolujte, že je paid a tabuľka Platby ukazuje transakciu brány

Ak niečo zlyhá, pozrite Stripe Dashboard → Developers → Webhooks → kliknite na svoj endpoint → Recent deliveries. Uvidíte každú udalosť, ktorú sa Stripe pokúsil poslať, kód odpovede a telo požiadavky. 200 = v poriadku. Čokoľvek iné = problém na strane Cabintale; stránka tam loguje podrobnosti.

Lokálny vývoj so Stripe CLI

Webhooky Stripe sa nedostanú na localhost. Stripe CLI to premosťuje – preberá udalosti zo Stripe a preposiela ich do vášho lokálneho Cabintale.

Inštalácia

brew install stripe/stripe-cli/stripe
stripe login

stripe login otvorí okno prehliadača – povoľte ho a vráťte sa do terminálu.

Preposielanie webhookov

stripe listen --forward-to http://admin.cabintale.local:8888/api/webhooks/stripe/{your_account_webhook_token}

Nahraďte {your_account_webhook_token} UUID z URL webhooku v okne Cabintale – stačí skopírovať URL a spustiť.

CLI vypíše:

> Ready! Your webhook signing secret is whsec_abc123…

Tento podpisový kľúč je iný ako ten zo Stripe Dashboardu. Vygeneroval ho CLI. Vložte tento do poľa podpisového kľúča webhooku v testovacom režime v Cabintale. Ten z dashboardu je pre endpoint v dashboarde; ten z CLI je pre preposielač CLI.

Nechajte stripe listen bežať. Teraz každá skúšobná rezervácia vo vašom lokálnom widgete spustí udalosti, ktoré tečú cez Stripe → CLI → váš localhost.

Priame spúšťanie vzorových udalostí

Bez vytvorenia skutočnej skúšobnej rezervácie môžete udalosti prehrať znova:

stripe trigger checkout.session.completed

Hodí sa na testovanie okrajových prípadov obsluhy webhooku. Pre realistické postupy prejdite skutočným rezervačným oknom s testovacou kartou.

Opätovné odoslanie konkrétnej udalosti

Ak potrebujete znova prehrať konkrétnu udalosť (napr. takú, ktorá skončila chybou 5xx):

stripe events resend evt_1XXXXXXXXXXXX

(ID udalosti nájdete vo výstupe stripe listen alebo v Stripe Dashboarde → Events.)

Spustenie naostro

Keď ste pripravení prijímať skutočné platby:

1. Vypnite v Stripe Dashboarde testovací režim
2. Aktivujte svoj účet, ak ste tak ešte neurobili (bankové údaje, doklad totožnosti)
3. Developers → API keys → skopírujte ostré sk_live_… a pk_live_…
4. Developers → Webhooks → pridajte NOVÝ endpoint smerujúci na rovnakú URL Cabintale (pre ostrý režim musíte pridať samostatný endpoint – sú nezávislé)
5. Vyberte rovnaké udalosti ako v kroku 4 vyššie
6. Skopírujte ostrý podpisový kľúč
7. Otvorte okno Cabintale → prepnite na Ostrý režim → vložte ostré kľúče → uložte
8. Otvorte jedno zo svojich ubytovaní a overte, že je stále na Prijímať platby. Urobte malú skúšobnú rezerváciu so skutočnou kartou – svojou alebo priateľa s malou platbou.

Testovacie kľúče môžete v okne nechať uložené tiež – prepnutie režimu v Cabintale mení, ktorá sada sa používa pre nové relácie Checkout, a umožňuje vám vrátiť sa k testovaniu bez straty ostrých kľúčov.

Riešenie problémov

Odkazy na dokumentáciu Stripe

• Kľúče API: https://docs.stripe.com/keys
• Webhooky: https://docs.stripe.com/webhooks
• Testovacie karty: https://docs.stripe.com/testing
• CLI: https://docs.stripe.com/stripe-cli
• Jazyky Checkout: https://docs.stripe.com/payments/checkout/customization/appearance#supported-languages

Súvisiace návody

• Platobné brány (nastavenie na strane Cabintale) – Platobné brány
• Prijímanie platieb pri ubytovaní – Prijímanie platieb pri ubytovaní