Platobné brány

Po dokončení tohto návodu budete mať vo svojom účte Cabintale uloženú fungujúcu platobnú bránu s pripravenými testovacími aj ostrými kľúčmi a budete vedieť, ako otestovať spojenie, vygenerovať URL webhooku znova, prepnúť predvolenú bránu a odstrániť nastavenie.

Prečo jedna brána na úrovni účtu?

Cabintale stojí na myšlienke, že platby nastavíte raz pre účet, nie pre každé ubytovanie. Väčšina ubytovateľov používa na všetko jednu platobnú bránu a brána, ktorú tu nastavíte, je predvolená pre každé ubytovanie, pre ktoré zapnete platby. Ak niekedy budete potrebovať samostatné brány pre krajiny alebo značky, v katalógu pribudnú ďalší poskytovatelia (ako ČSOB) – zatiaľ je jedna aktívna možnosť.

Krok 1: Otvorte Nastavenia

Bočné menu → Nastavenia. Stránka má teraz časť Platobné brány medzi Účtom a Zrušiť účet.

Uvidíte dve karty:

• Stripe – fialová ikona, tlačidlo Nastaviť, pripravené na nastavenie
• ČSOB – zosvetlená s označením Čoskoro. Brána pre české obchodníkov; zatiaľ nie je dostupná

Ak ste bránu už nastavili, karta má zelený okraj + fajku a tlačidlo znie Nastavenia namiesto Nastaviť.

Krok 2: Otvorte okno brány

Na karte Stripe kliknite na Nastaviť (alebo Nastavenia, ak už je nastavená). Otvorí sa okno s:

• Logom brány a krátkym popisom
• Odkazom na náš návod v dokumentácii (zatiaľ zástupný – vedie do našej dokumentácie)
• Prepínačom Testovací režim / Ostrý režim navrchu
• Tromi poliami nižšie: Tajný kľúč, Verejný kľúč, Podpisový kľúč webhooku
• Časťou Naša URL webhooku s blokom kódu
• Pätičkou: Otestovať spojenie (vľavo) a Zrušiť + Uložiť (vpravo). Pri úprave existujúcej brány sa vľavo zobrazí aj tlačidlo Odstrániť nastavenie.

Krok 3: Vyberte režim a vložte kľúče

Predvolene je vybraný testovací režim. Začnite v ňom – je bezpečnejší a na ostrý môžete prejsť neskôr.

Tri polia:

1. Tajný kľúč – začína sk_test_… (test) alebo sk_live_… (ostrý). Zo Stripe → Developers → API keys.
2. Verejný kľúč – začína pk_test_… / pk_live_…. Na rovnakom mieste.
3. Podpisový kľúč webhooku – začína whsec_…. Zo Stripe → Developers → Webhooks → váš endpoint → Signing secret. Najprv musíte v Stripe pridať endpoint webhooku smerujúci na URL, ktorú ukazujeme nižšie v okne (pozrite krok 5).

Ak testujete lokálne so Stripe CLI, CLI vypíše iný podpisový kľúč – v testovacom režime použite ten, nie ten zo Stripe Dashboardu. Pozrite Nastavenie Stripe.

O tlačidlách oka na zobrazenie/skrytie. Polia Tajný kľúč a Podpisový kľúč webhooku sú predvolene zakryté. Kliknutím na ikonu oka vedľa nich zobrazíte, čo ste napísali. Neukladáme ich tak, aby sme vám ich mohli ukázať späť – po uložení sú na našich serveroch šifrované a okno pri ďalšom otvorení ukáže prázdne polia (s nápovedou „Nechajte prázdne, ak chcete ponechať súčasný.“).

Krok 4: Otestujte spojenie

Pod kľúčmi je tlačidlo Otestovať spojenie. Kliknite naň, keď ste vložili všetky tri. Zavolá API brány s vaším tajným kľúčom a oznámi:

• Spojenie je v poriadku – zelený štítok, všetko je v poriadku
• Spojenie zlyhalo – červený štítok s chybovou správou brány; zvyčajne preklep v tajnom kľúči alebo zlý režim (test vs. ostrý)

Test beží v práve zobrazenom režime. Ak prepnete z Testu na Ostrý, polia sa zmenia a túto stranu môžete otestovať samostatne.

Krok 5: Prepojte URL webhooku

Pod tlačidlom testu je Naša URL webhooku. Je to blok kódu s niečím takýmto:

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

Táto URL je jedinečná pre váš účet. Brána na ňu posiela udalosti o platbách, aby sme mohli rezervácie označiť ako zaplatené v reálnom čase.

1. Kliknite na Kopírovať URL
2. Prejdite do Stripe Dashboardu → Developers → Webhooks → Add destination (Stripe webhooky teraz nazýva „event destinations“)
3. Select events – nastavte rozsah na Your account, potom vyhľadajte a zaškrtnite: checkout.session.completed, checkout.session.expired, payment_intent.succeeded, payment_intent.payment_failed, charge.refunded. Kliknite na Continue.
4. Choose destination type – vyberte Webhook endpoint. Kliknite na Continue.
5. Configure destination – vložte skopírovanú URL do Endpoint URL, dajte mu názov (napr. Cabintale production) a kliknite na Create destination.
6. Na stránke destinácie zobrazte Signing secret (whsec_…) a skopírujte ho späť do poľa Podpisový kľúč webhooku v okne Cabintale.

Tlačidlo Vygenerovať odkaz znova vymení token URL webhooku vášho účtu. Použite ho, ak máte podozrenie, že URL unikla. Po výmene musíte aktualizovať URL endpointu v Stripe Dashboarde, aby sa zhodovala – stará URL okamžite prestane fungovať.

Staršie účty Stripe môžu ešte ukazovať jednoobrazovkový formulár Add endpoint namiesto trojkrokového sprievodcu destináciou. Rovnaké polia, rovnaký výsledok.

Krok 6: Uložte

Kliknite na Uložiť. Okno sa zatvorí a:

• Vaša karta má zelený okraj + fajku (je predvolenou bránou účtu)
• Označenie tlačidla sa zmenilo z Nastaviť na Nastavenia
• Oznámenie potvrdí „Brána uložená. Testuje sa spojenie…“ – na pozadí beží skutočný test na overenie

Ak uvidíte chybu 422, kľúče neprešli kontrolou. Najčastejšia príčina: prázdne povinné pole alebo vložené medzery. Skontrolujte a uložte znova.

Po nastavení: úprava, zobrazenie uložených kľúčov

Okno znova otvoríte kliknutím na Nastavenia na karte Stripe. Okno teraz ukazuje iné rozloženie:

• Prepínač režimu navrchu
• Orámovaný panel s textom „Vaše kľúče pre tento režim sú uložené. Z bezpečnostných dôvodov sú skryté.“ s dvoma tlačidlami:
  • Otestovať spojenie – okamžite otestuje bránu; výsledok sa zobrazí priamo tu
  • Zadať nové kľúče – zobrazí polia, aby ste kľúče mohli vymeniť

Ak kliknete na Zadať nové kľúče, formulár sa vráti. Zadajte nové hodnoty a kliknite na Uložiť. Alebo kliknutím na Zrušiť — ponechať súčasné kľúče zmenu vrátite.

Toto zobrazenie je pre každý režim zvlášť: Test môže byť vyplnený (ukazuje panel), kým Ostrý je ešte prázdny (ukazuje polia), a naopak. Prepnutím režimu sa mení, ktorý panel je viditeľný.

Prepínanie medzi Testom a Ostrým režimom

Najbežnejší postup:

1. Nastavte testovací režim, vložte testovacie kľúče, otestujte rezervácie od začiatku do konca
2. Keď ste pripravení ísť naostro, otvorte okno a prepnite na Ostrý režim
3. Vložte ostré kľúče (a vytvorte samostatný endpoint webhooku v ostrom Stripe Dashboarde pre tú istú URL)
4. Okno teraz má vyplnené oba režimy
5. Ak chcete naozaj ísť naostro, nastavte Ostrý ako aktívny režim a Uložte

Medzi Testom a Ostrým môžete prepínať kedykoľvek – obe sady zostávajú uložené. Aktívny režim určuje, ktoré kľúče Cabintale používa pri nových reláciách Checkout.

Webhooky pri prepnutí. Keď prepnete z testu na ostrý režim, webhooky pre relácie vytvorené v predchádzajúcom režime sa stále overia správne – Cabintale pri každom doručení skúša podpisové kľúče oboch režimov. Ak teda prepnete uprostred dňa a webhook z testovacieho režimu pristane o desať sekúnd neskôr, spracuje sa správne.

Viac brán (budúcnosť)

Dnes je v katalógu aktívny len Stripe. ČSOB je zástupná pre pripravovanú bránu pre české obchodníkov. Keď pribudnú ďalší poskytovatelia, uvidíte v katalógu ďalšie karty. Predvolená medzi nastavenými sa vyberá kliknutím na telo karty – kliknutie na telo karty Stripe (keď sú nastavení obaja poskytovatelia) nastaví Stripe ako predvolenú, čo označuje zelený okraj + fajka.

Odstránenie brány

V okne vľavo v pätičke Odstrániť nastavenie. Okno požiada o potvrdenie – „Čakajúce alebo dokončené transakcie spojené s touto bránou sa budú naďalej zobrazovať s historickými údajmi.“

Dva výsledky:

• Ak bránu nepoužívajú žiadne čakajúce ani úspešné transakcie → odstráni sa (mäkké odstránenie; historické potvrdenky sa stále zobrazia)
• Ak existujú nejaké čakajúce alebo úspešné transakcie → priamo v okne chyba 409. Bránu, ktorá je ešte uprostred platby s hosťom, odstrániť nemôžete. Buď počkajte, kým sa tieto platby dokončia, alebo ich najprv zrušte na detailnej stránke rezervácie.

Riešenie problémov

Súvisiace návody

• Nastavenie Stripe (strana Stripe Dashboardu) – Nastavenie Stripe
• Prijímanie platieb pri ubytovaní – Prijímanie platieb pri ubytovaní
• Nastavenia účtu – Nastavenia účtu