Platební brány

Po dokončení tohoto návodu budete mít na svém Cabintale účtu funkční Stripe bránu s klíči pro Test i Live režim, budete vědět, jak otestovat připojení, vygenerovat novou webhook URL, přepínat výchozí bránu a smazat konfiguraci.

Proč jediná brána na úrovni účtu?

Cabintale je postavené na myšlence, že platby nastavíte jednou pro celý účet, ne pro každé ubytování zvlášť. Většina hostitelů používá jeden Stripe účet pro všechno a brána, kterou tu nastavíte, je výchozí pro jakékoliv ubytování, kde zapnete platby. Pokud byste někdy potřebovali samostatné brány pro různé země nebo značky, postupně budou v katalogu přibývat další poskytovatelé (například ČSOB) — zatím je aktivní pouze Stripe.

Krok 1: Otevřete Nastavení

Postranní lišta → Nastavení. Stránka má novou sekci Platební brány mezi částmi Účet a Zavřít účet.

Uvidíte dvě karty:

• Stripe — fialová ikona, tlačítko Nastavit, připraveno k nakonfigurování
• ČSOB — vybledlá s nápisem Brzy k dispozici. Brána pro české obchodníky; zatím není dostupná

Pokud už máte Stripe nastavený, karta má zelený rámeček + zaškrtávátko a tlačítko se jmenuje Nastavení místo Nastavit.

Krok 2: Otevřete Stripe dialog

Klikněte na Nastavit (nebo Nastavení, pokud už je nakonfigurováno) na kartě Stripe. Otevře se dialog s:

• Logem Stripe a krátkým popisem
• Odkazem na náš tutoriál v dokumentaci (zatím placeholder — odkazuje na naše dokumenty)
• Přepínačem Testovací režim / Ostrý režim nahoře
• Třemi vstupními poli níže: Tajný klíč, Publikovatelný klíč, Podpisový klíč webhooku
• Sekcí Webhook URL s code blokem
• Patičkou: Otestovat připojení (vlevo), Zrušit + Uložit (vpravo). Při úpravě stávající brány vlevo navíc přibude tlačítko Smazat konfiguraci.

Krok 3: Vyberte režim a vložte klíče

Testovací režim je vybraný ve výchozím stavu. Začněte tam — je bezpečnější a později se kdykoliv přepnete do live.

Tři pole:

1. Tajný klíč — začíná na sk_test_… (test) nebo sk_live_… (live). Ze Stripe → Developers → API keys.
2. Publikovatelný klíč — začíná na pk_test_… / pk_live_…. Ze stejného místa.
3. Podpisový klíč webhooku — začíná na whsec_…. Ze Stripe → Developers → Webhooks → váš endpoint → Signing secret. Nejprve musíte ve Stripe vytvořit webhook endpoint směřující na URL, kterou vám ukážeme níže v dialogu (viz Krok 5).

Pokud testujete lokálně se Stripe CLI, CLI vypisuje jiný signing secret — použijte ten v testovacím režimu, ne ten z dashboardu. Viz Nastavení Stripe.

Tlačítka pro zobrazení/skrytí. Pole Tajný klíč a Podpisový klíč webhooku jsou ve výchozím stavu zamaskovaná. Klikněte na ikonu oka vedle nich, aby se zobrazilo, co jste napsali. Klíče nikdy neukládáme tak, abychom vám je mohli zobrazit zpátky — po uložení žijí zašifrované na našich serverech a dialog při dalším otevření zobrazí prázdné inputy (s nápovědou "Ponechte prázdné pro zachování stávajícího").

Krok 4: Otestujte připojení

Pod klíči je tlačítko Otestovat připojení. Klikněte na něj, jakmile vyplníte všechna tři pole. Tlačítko zavolá Stripe API s vaším tajným klíčem a vrátí:

• Connection OK — zelený badge, vše funguje
• Connection failed — červený badge s chybovou hláškou ze Stripe; obvykle překlep v tajném klíči nebo nesprávný režim (test vs. live)

Test běží proti aktuálně zobrazenému režimu. Když přepnete z Test na Live, inputy se změní a můžete otestovat tu stranu samostatně.

Krok 5: Propojte webhook URL

Pod tlačítkem testu je sekce Webhook URL. Je to code block s něčím jako:

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

Tato URL je unikátní pro váš účet. Stripe sem posílá platební události, abychom mohli rezervace v reálném čase označovat jako zaplacené.

1. Klikněte na Kopírovat URL
2. Jděte do Stripe Dashboardu → Developers → Webhooks → Add destination (Stripe nyní webhooky nazývá „event destinations")
3. Select events — nastavte scope na Your account, pak vyhledejte a zaškrtněte: checkout.session.completed, checkout.session.expired, payment_intent.succeeded, payment_intent.payment_failed, charge.refunded. Klikněte Continue.
4. Choose destination type — zvolte Webhook endpoint. Klikněte Continue.
5. Configure destination — vložte zkopírovanou URL do Endpoint URL, pojmenujte cíl (např. Cabintale production) a klikněte Create destination.
6. Na stránce cíle zobrazte Signing secret (whsec_…) a zkopírujte ho zpátky do dialogu cabintale do pole Podpisový klíč webhooku.

Tlačítko Vygenerovat znovu rotuje token webhook URL vašeho účtu. Použijte, pokud máte podezření, že URL unikla. Po rotaci je třeba aktualizovat URL endpointu ve Stripe dashboardu — stará URL přestane okamžitě fungovat.

Starší účty Stripe mohou stále zobrazovat jednoobrazovkový formulář Add endpoint místo třístupňového průvodce. Stejná pole, stejný výsledek.

Krok 6: Uložte

Klikněte na Uložit. Dialog se zavře a:

• Vaše karta má teď zelený rámeček + zaškrtávátko (je výchozí pro účet)
• Tlačítko se přejmenovalo z Nastavit na Nastavení
• Toast potvrdí "Brána uložena. Testujeme připojení…" — na pozadí proběhne reálný test pro ověření

Pokud uvidíte 422 chybu, klíče neprošly validací. Nejčastější příčina: prázdné pole nebo bílé znaky. Zkontrolujte a uložte znovu.

Po nastavení: úprava, zobrazení uložených klíčů

Znovu otevřete dialog kliknutím na Nastavení na kartě Stripe. Dialog teď ukazuje jiný layout:

• Přepínač režimu nahoře
• Orámovaný panel s textem "Klíče pro tento režim jsou uloženy. Z bezpečnostních důvodů jsou skryté." a dvěma tlačítky:
  • Otestovat připojení — okamžitě spustí test proti Stripe; výsledek se zobrazí inline
  • Zadat nové klíče — odkryje vstupní pole pro výměnu klíčů

Po kliknutí na Zadat nové klíče se zobrazí formulář. Zadejte nové hodnoty, klikněte Uložit. Nebo klikněte na Zrušit – ponechat stávající klíče pro návrat.

Tento pohled je per-režim: Test může být vyplněný (panel) zatímco Live je stále prázdný (inputy), a naopak. Přepínáním režimu se mění, který panel se zobrazí.

Přepínání mezi Test a Live

Nejčastější časový plán:

1. Nastavte Test režim, vložte testovací klíče, otestujte rezervace end-to-end
2. Až budete připraveni jít naživo, otevřete dialog, přepněte na Ostrý režim
3. Vložte live klíče (a vytvořte samostatný webhook endpoint v live dashboardu Stripe pro stejnou URL)
4. Dialog teď má vyplněné oba režimy
5. Pro skutečný přechod na ostro nastavte Live jako aktivní režim a Uložte

Mezi Test a Live můžete přepínat kdykoliv — oba sady klíčů zůstávají uložené. Aktivní režim určuje, které klíče cabintale použije pro nové Checkout session.

Webhooky během přepnutí. Když přepnete z testu na live, probíhající webhooky pro session vytvořené v předchozím režimu stále projdou ověřením — cabintale zkouší podpisové klíče obou režimů pro každé doručení. Když tedy přepnete uprostřed dne a o deset sekund později dorazí webhook z testovacího režimu, stále se správně zpracuje.

Více bran (budoucnost)

Dnes je v katalogu aktivní pouze Stripe. ČSOB je placeholder pro nadcházející bránu pro české obchodníky. Až budou další poskytovatelé hotoví, uvidíte v katalogu další karty. Výběr výchozí brány funguje kliknutím na tělo karty — kliknutím na tělo karty Stripe (po nakonfigurování obou poskytovatelů) nastavíte Stripe jako výchozí, indikováno zeleným rámečkem + zaškrtávátkem.

Smazání brány

V dialogu, vlevo dole, Smazat konfiguraci. Dialog se zeptá na potvrzení — "Probíhající nebo dokončené transakce vázané na tuto bránu se nadále zobrazí s historickými údaji."

Dva výsledky:

• Pokud na bránu neodkazují žádné probíhající ani dokončené transakce → smaže se (soft-delete; historické účtenky se stále vyřeší)
• Pokud existují probíhající nebo dokončené transakce → 409 chyba inline. Bránu nelze smazat, dokud je s hostem rozjetá platba. Buď počkejte, až se platba dokončí, nebo ji nejdřív zrušte na detailu rezervace.

Řešení potíží

Související návody

• Nastavení Stripe (strana Stripe dashboardu) — Nastavení Stripe
• Přijímání plateb na ubytování — Přijímání plateb na ubytování
• Nastavení účtu — Nastavení účtu